How Transcript-Only Mode Avoids Downloading Video Files in Claude Video

Transcript-only mode avoids downloading video files by checking for available captions first, then short-circuiting the download step when captions exist and no frame timestamps are requested.

The bradautomates/claude-video repository provides a /watch skill that processes YouTube videos efficiently. When users request transcript-only mode, the system minimizes network bandwidth by fetching only metadata and captions rather than full video files. This optimization relies on early decision logic that evaluates available data before invoking heavy download operations.

The Decision Logic in watch.py

The transcript-only optimization centers in skills/watch/scripts/watch.py, where the script determines download requirements before any heavy-weight processing begins.

Early Caption Retrieval

Before considering video downloads, the script runs fetch_captions to execute a lightweight yt-dlp metadata request. This operation pulls available subtitle files without transferring video bytes. According to the source code at lines 97-105, this early fetch populates the transcript_segments variable that drives subsequent decisions.

The Core Skip Condition (Lines 111-114)

The definitive logic preventing unnecessary downloads appears at lines 111-114 of watch.py:

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

else:
    # download audio-only or full video depending on `audio_only`

    dl = download(args.source, work / "download", audio_only=audio_only)

This code establishes three critical conditions:

• detail == "transcript": The user requested transcript-only output via the --detail transcript flag
• transcript_segments: Captions were successfully parsed and are available
• not cue_timestamps: No frame timestamps were requested via --timestamps

When all conditions are met, video_path is set to None, bypassing the download() call entirely.

When Downloads Are Skipped vs. Fallbacks

The transcript-only mode operates differently depending on caption availability and user parameters.

Full Skip with Available Captions

When captions exist and no timestamps are requested, the system transfers zero video or audio bytes. The transcript_segments data provides sufficient information for output, making this the most efficient path. The SKILL.md documentation confirms this behavior: "transcript — no frames at all, transcript only (skips video download when captions exist)."

Audio-Only Fallback Without Captions

If captions are unavailable (transcript_segments is empty), the script falls back to downloading audio only. While this transfers data, it remains significantly lighter than full video downloads. The audio file feeds into Whisper for transcription generation, ensuring users still receive transcript output even when source captions are missing.

Forced Video Download with Timestamps

Requesting specific timestamps via --timestamps overrides the skip logic. Even in transcript-only mode, frame extraction requires video bytes. When cue_timestamps are present, the audio_only boolean remains False, forcing a full video download through download.py.

Practical Code Examples

These scenarios demonstrate the three operational modes of transcript-only processing.

Transcript-Only with Captions (No Download)

python3 skills/watch/scripts/watch.py \
    "https://youtu.be/example" \
    --detail transcript

Output showing the skip:

[watch] checking metadata/captions via yt-dlp…
[watch] working dir: /tmp/watch-abc123
[watch] extracting ... (transcript only)
- **Transcript:** 27 segments (via captions)

Transcript-Only Without Captions (Audio Download)

python3 skills/watch/scripts/watch.py \
    "https://youtu.be/no-captions" \
    --detail transcript

Output showing audio fallback:

[watch] checking metadata/captions via yt-dlp…
[watch] downloading audio via yt-dlp…
- **Transcript:** 42 segments (via whisper (groq))

Transcript-Only with Timestamps (Video Download)

python3 skills/watch/scripts/watch.py \
    "https://youtu.be/example" \
    --detail transcript \
    --timestamps 00:45,01:20

Output showing forced video download:

[watch] checking metadata/captions via yt-dlp…
[watch] downloading video via yt-dlp…
- **Cue frames:** 2 at transcript-flagged timestamps (transcript-cue)
- **Transcript:** 27 segments (via captions)

Key Implementation Files

File	Purpose
skills/watch/scripts/watch.py (lines 111-114)	Implements the skip logic that sets video_path = None
skills/watch/scripts/watch.py (lines 97-105)	Retrieves captions via fetch_captions to populate transcript_segments
skills/watch/scripts/download.py	Handles yt-dlp invocations with the audio_only parameter
skills/watch/SKILL.md	Documents the --detail transcript behavior and download skip conditions

Summary

• Transcript-only mode checks for captions first via lightweight metadata requests before downloading any media.
• When captions exist and no timestamps are requested, video_path is set to None at lines 111-114 of watch.py, completely bypassing video downloads.
• If captions are missing, the system falls back to audio-only downloads rather than full video, still minimizing bandwidth.
• The --timestamps flag forces full video downloads when frame extraction is required, overriding the skip optimization.
• This architecture makes transcript processing fast and network-efficient whenever source captions are available.

Frequently Asked Questions

Does transcript-only mode ever download video files?

Transcript-only mode only downloads video files when you specify the --timestamps flag, which requires frame extraction at specific times. Otherwise, it either skips downloads entirely (when captions exist) or downloads audio-only (when captions are missing and Whisper transcription is needed).

What happens if a YouTube video has no captions?

When captions are unavailable, transcript_segments remains empty and the script falls back to downloading audio only. This audio file is then processed through Whisper to generate the transcript, ensuring you still receive text output without downloading the full video file.

Where is the download skip logic implemented in the source code?

The core skip logic resides in skills/watch/scripts/watch.py at lines 111-114. This code checks if detail == "transcript" and transcript_segments exists while cue_timestamps is false, setting video_path = None to prevent the download() function from executing.

Can I force transcript-only mode to download the video anyway?

Yes, by adding the --timestamps parameter with specific time codes, you force a full video download. This overrides the default skip behavior because extracting frames at precise timestamps requires access to the actual video file bytes, not just captions or audio.

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