How the Transcript Detail Mode in claude-video Skips Video Download When Captions Exist

When you invoke the watch command with --detail transcript, the script checks for existing captions via fetch_captions and sets video_path = None to bypass video downloads entirely, unless timestamped frames are explicitly requested.

The bradautomates/claude-video repository provides an intelligent mechanism to avoid unnecessary video downloads when processing YouTube URLs. By utilizing the transcript detail mode, the tool extracts metadata and text from existing subtitle files rather than downloading the full media, significantly reducing bandwidth and processing overhead.

Initial Caption Check Without Media Download

Before any video processing begins, watch.py orchestrates a lightweight subtitle check. The script calls fetch_captions from skills/watch/scripts/download.py, which leverages yt‑dlp to query available subtitle files without fetching the actual media.

If subtitles exist, the function returns a file path immediately. The transcript is then parsed by parse_vtt in skills/watch/scripts/transcribe.py, which builds the transcript_segments list and generates transcript_text. This phase requires only the subtitle file, not the video stream.

The Decision Point Logic

The skip mechanism relies on a specific conditional check in skills/watch/scripts/watch.py. After the caption check completes, the script evaluates three variables: detail, transcript_segments, and cue_timestamps.

audio_only = detail == "transcript" and not cue_timestamps
if detail == "transcript" and transcript_segments and not cue_timestamps:
    video_path = None          # ← skip video download

else:
    # ... download video logic ...

When the skip occurs:

• The user requested --detail transcript
• transcript_segments is non-empty (captions were found)
• No --timestamps argument was provided

When all conditions are met, the script assigns video_path = None. This signals downstream logic to omit all frame-extraction steps and proceed directly to transcript formatting.

Why Timestamps Force a Download

The --timestamps option requires access to actual video frames to extract cue images. When cue_timestamps contains any values, the conditional evaluates to false regardless of caption availability.

If you request specific timestamps, the script overrides the skip optimization and executes the download path to obtain the necessary frames. This ensures visual extraction capabilities remain available even when subtitles exist.

Resulting Output Behavior

When the skip is active, the final report indicates the bypass explicitly:

- **Frames:** skipped (transcript detail)

The script proceeds with metadata handling using data returned by fetch_captions, formats the transcript text, and outputs the analysis without ever touching the video file.

Code Examples

Run transcript mode to skip downloads when captions exist:

watch https://youtu.be/abcd1234 --detail transcript

If captions are available, the output displays the transcript and the frame skip notice:

- **Frames:** skipped (transcript detail)

Force a download to extract cue frames at specific timestamps:

watch https://youtu.be/abcd1234 --detail transcript --timestamps 00:30,01:20

The presence of --timestamps forces the download regardless of subtitle availability.

Summary

• The transcript detail mode checks for existing captions via fetch_captions before considering a download.
• When transcript_segments exists and no timestamps are requested, the script sets video_path = None in skills/watch/scripts/watch.py.
• The --timestamps flag overrides the skip because frame extraction requires actual video data.
• This optimization reduces bandwidth usage by processing only subtitle files when text analysis is sufficient.

Frequently Asked Questions

Why does the transcript mode still download some videos?

If the video lacks available captions or if you specify the --timestamps flag, the script cannot skip the download. Timestamp extraction requires actual video frames, so video_path remains assigned and the download proceeds even in transcript detail mode.

Where is the skip logic implemented in the source code?

The primary decision logic resides in skills/watch/scripts/watch.py. This file evaluates the detail mode, checks the transcript_segments variable populated by parse_vtt, and conditionally sets video_path = None to bypass the download phase.

How does the script obtain captions without downloading the video?

The fetch_captions function in skills/watch/scripts/download.py uses yt‑dlp with subtitle-specific options to retrieve available .vtt files. This operation queries YouTube's caption API without fetching the video stream, returning only the text metadata needed for transcript generation.

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