How Transcript-Only Mode in Claude-Video Completely Skips Frame Extraction

Claude-Video bypasses all frame extraction when --detail transcript is used by setting video_path = None and blocking the ffmpeg processing pipeline through conditional checks in skills/watch/scripts/watch.py.

The bradautomates/claude-video repository provides a watch command that supports a transcript-only mode for lightweight video analysis. When you specify --detail transcript without cue timestamps, the tool executes a coordinated three-step bypass in skills/watch/scripts/watch.py that prevents any video download or frame processing from occurring.

Detecting Transcript-Only Mode

The script first identifies transcript-only requests using a boolean flag that checks both the detail level and timestamp requirements.

audio_only = detail == "transcript" and not cue_timestamps

This assignment at line 111-112 sets audio_only = True only when the user requests transcript detail and does not provide explicit cue timestamps. This flag drives subsequent decisions about resource fetching and processing pipelines.

Skipping Video Download Entirely

When operating in transcript-only mode, the script prevents the video file from being downloaded, which eliminates the source data required for frame extraction.

if detail == "transcript" and transcript_segments and not cue_timestamps:
    video_path = None               # No video needed → no frames

else:
    … download video …

As implemented at lines 112-115, this conditional forces video_path = None when subtitles are already available (transcript_segments) and no cue timestamps are requested. Without a valid video path, the downstream frame extraction logic cannot execute.

Blocking the Frame Extraction Pipeline

The final safeguard occurs at the frame processing stage, where a guard clause explicitly prevents the heavy ffmpeg operations from running.

if detail != "transcript" and video_path and detail_budget != 0:
    # … extract keyframes or scene-aware frames …

Located at lines 196-198, this condition ensures that frame extraction only runs when three criteria are met: the detail level is not transcript, a valid video path exists, and the detail budget is non-zero. In transcript-only mode, the first condition fails, completely bypassing the extract_keyframes and extract_scene_or_uniform functions defined in skills/watch/scripts/frames.py.

User-Facing Confirmation

When the frame extraction step is skipped, the tool provides clear feedback in the output report.

elif not cue_frames:
    print("- **Frames:** skipped (transcript detail)")

This messaging at lines 299-301 confirms to the user that no frames were processed due to the transcript detail setting, providing transparency about the skipped processing step.

Practical Usage Examples

Use the following command patterns to control frame extraction behavior:

# Transcript-only – no frames are extracted

watch https://example.com/video.mp4 --detail transcript

# Transcript-only with explicit cue timestamps – frames extracted only for specific times

watch https://example.com/video.mp4 \
      --detail transcript \
      --timestamps "00:30,01:45"

In the first example, the script sets audio_only=True, never downloads the video, and skips all frame extraction calls. In the second example, the presence of --timestamps clears the audio_only flag and triggers a full video download solely to extract frames at the requested timestamps.

Key Implementation Files

The transcript-only bypass logic spans several coordinated files:

• skills/watch/scripts/watch.py: Central orchestration that parses arguments, determines the detail level, and decides whether to download video and run frame extraction.
• skills/watch/scripts/frames.py: Implements the ffmpeg-heavy frame extraction functions (extract_keyframes, extract_scene_or_uniform) that are conditionally called only when detail != "transcript".
• skills/watch/scripts/config.py: Supplies default detail settings and frame caps used by the decision logic.
• skills/watch/scripts/transcribe.py: Handles subtitle parsing and transcript formatting used when subtitles are the only text source.

Summary

• Detection: The audio_only flag at line 111 identifies transcript-only requests by checking detail == "transcript" and not cue_timestamps.
• Prevention: The video download is skipped at lines 112-115 by setting video_path = None when transcripts exist and no timestamps are requested.
• Blocking: The frame extraction guard at lines 196-198 uses detail != "transcript" to prevent ffmpeg processing from running.
• Transparency: Users see "Frames: skipped (transcript detail)" in the output when frame extraction is bypassed.
• Efficiency: This three-step process saves bandwidth, disk space, and compute resources by avoiding video downloads and ffmpeg operations entirely.

Frequently Asked Questions

Can I extract specific frames while using transcript-only mode?

Yes, by adding the --timestamps flag with specific timecodes, you override the transcript-only bypass. When cue_timestamps are provided, the audio_only flag evaluates to False, forcing a video download and frame extraction limited to your specified timestamps.

What happens if no transcript is available when using --detail transcript?

If transcript_segments is not available, the condition at lines 112-115 fails and the video downloads normally. However, the frame extraction block at lines 196-198 still checks detail != "transcript", so frames would not be extracted unless the logic falls through to a different handling path.

Why does the tool set video_path = None instead of just skipping the extraction loop?

Setting video_path = None provides a defense-in-depth mechanism. While the frame extraction guard at lines 196-198 does check detail != "transcript", the null video path ensures that even if that logic were modified or bypassed, subsequent code expecting a valid file path would fail safely rather than attempting to process a non-existent video.

Which file contains the conditional logic that prevents frame extraction?

The primary conditional logic resides in skills/watch/scripts/watch.py at lines 196-198, where the guard clause if detail != "transcript" and video_path and detail_budget != 0: controls access to the frame extraction pipeline. The actual ffmpeg-based extraction functions that are being skipped are implemented in skills/watch/scripts/frames.py.

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