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

> Learn how transcript-only mode in Claude Video skips video file downloads by prioritizing captions and bypassing downloads when timestamps aren't needed.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-07

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py):

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/download.py).

## Practical Code Examples

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

### Transcript-Only with Captions (No Download)

```bash
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)

```bash
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)

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 111-114) | Implements the skip logic that sets `video_path = None` |
| [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 97-105) | Retrieves captions via `fetch_captions` to populate `transcript_segments` |
| [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) | Handles `yt-dlp` invocations with the `audio_only` parameter |
| [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.