What Happens in claude-video When a Video File Lacks an Audio Stream

When a video file lacks an audio stream, claude-video detects the missing audio via ffprobe metadata, skips all transcription steps including captions and Whisper, and proceeds to generate a frames-only analysis report while emitting a clear warning to stderr.

The claude-video repository by bradautomates provides AI-powered video analysis through its specialized watch skill. Understanding how the pipeline handles edge cases like silent videos ensures you know what to expect when processing media files that contain visual content but no audio track.

Audio Stream Detection via ffprobe

The detection process begins in skills/watch/scripts/frames.py, where the system extracts comprehensive video metadata using ffprobe. At line 118, the code analyzes the ffprobe output to determine whether an audio stream exists and sets the has_audio flag accordingly.

When no audio stream is detected, the metadata dictionary contains "has_audio": False, which serves as the gatekeeper for downstream transcription logic.

Transcription Decision Logic

The orchestration script skills/watch/scripts/watch.py implements a fail-safe check at lines 259-267 that evaluates the metadata before attempting audio-dependent processing. After attempting to download existing captions and falling back to Whisper transcription, the code verifies the audio stream status:

elif not transcript_segments and video_path and not meta.get("has_audio"):
    print("[watch] no audio stream found — proceeding without transcription", file=sys.stderr)

This conditional ensures that silent videos bypass expensive transcription API calls while keeping the user informed through stderr output.

Frames-Only Output Generation

When processing a video without audio, the pipeline continues with frame extraction based on the specified --detail level (low, balanced, or high). The final analysis report contains the extracted frame visuals but explicitly omits any transcript section.

The user receives immediate feedback through stderr indicating that the video lacks an audio stream, while stdout delivers the complete visual analysis. This graceful degradation ensures that silent CCTV footage, GIF conversions, or muted clips still undergo AI visual analysis without throwing errors.

Practical Example

Execute the watch command on a silent video to observe the audio detection behavior:

# Process a silent video file

watch silent_clip.mp4 --detail balanced

Expected output behavior:

stderr: [watch] no audio stream found — proceeding without transcription
stdout: Complete report containing extracted frames but no transcript section

Internally, the Python logic evaluates the metadata flag as implemented in bradautomates/claude-video:

if not transcript_segments and video_path and not meta.get("has_audio"):
    print("[watch] no audio stream found — proceeding without transcription")

Summary

• Early Detection: The skills/watch/scripts/frames.py helper detects missing audio streams via ffprobe at line 118, setting has_audio to False in the metadata dictionary.
• Smart Bypass: skills/watch/scripts/watch.py checks this flag at lines 259-267 to skip caption downloads and Whisper transcription when no audio exists.
• Graceful Degradation: Silent videos proceed through frame extraction based on the --detail parameter, generating complete visual analysis without transcription.
• Clear Feedback: Users receive explicit stderr warnings indicating the absence of audio while the tool continues with frames-only output.

Frequently Asked Questions

Does claude-video throw an error when processing videos without audio?

No, claude-video does not throw an error when a video file lacks an audio stream. According to the source code in skills/watch/scripts/watch.py, the pipeline detects the missing audio and prints an informational message to stderr before proceeding with frame extraction.

Will claude-video still analyze frames if there is no audio?

Yes, the tool continues processing visual content even when no audio stream is present. The watch skill extracts frames according to the specified --detail level (low, balanced, or high) and generates an analysis report based solely on the visual content.

How does claude-video detect that a video lacks an audio stream?

The detection occurs in skills/watch/scripts/frames.py using ffprobe metadata extraction. The code sets a has_audio boolean flag in the metadata dictionary, which downstream logic in watch.py checks before attempting any transcription operations.

Can I force transcription on a video without an audio stream?

No, you cannot force transcription on a video that lacks an audio stream in claude-video. When the has_audio flag is False and no existing captions are found, the code explicitly bypasses Whisper transcription and proceeds without text conversion, as shown in lines 259-267 of watch.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}