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

> Discover how claude-video's transcript mode smartly skips video downloads when captions are present. Learn how it leverages fetched captions to save you time and resources.

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

---

**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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) orchestrates a lightweight subtitle check. The script calls `fetch_captions` from [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). After the caption check completes, the script evaluates three variables: `detail`, `transcript_segments`, and `cue_timestamps`.

```python
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:

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

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