# How to Use the Transcript Detail Mode in Claude-Video

> Learn to use Claude-Video's transcript detail mode. This flag skips frame extraction and provides a timestamped transcript from YouTube or Whisper, streamlining your video analysis.

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

---

**The `--detail transcript` flag in Claude-Video's `/watch` skill skips all frame extraction and returns only a timestamped transcript**, sourcing either YouTube's native WebVTT captions or falling back to Whisper transcription when needed.

The `bradautomates/claude-video` repository provides a video analysis framework that supports multiple extraction granularities. When you need only the spoken content without visual analysis, the **transcript detail mode** optimizes the workflow by downloading only audio data and bypassing the computationally expensive frame extraction pipeline.

## How the Transcript Detail Mode Works

When you invoke `--detail transcript`, the workflow in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) short-circuits the standard frame-extraction branch and executes a specialized audio-only path.

### 1. Argument Parsing and Validation

The entry point validates that `transcript` is an allowed value for the `--detail` option. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the argument parser accepts `transcript` alongside other detail modes like `low`, `medium`, and `high`.

### 2. Audio-Only Download Optimization

If the selected detail is `transcript` **and** no explicit `--timestamps` are provided, the script avoids downloading the full video file. Instead, it sets `audio_only = True` and fetches only the audio track, significantly reducing bandwidth and processing time.

### 3. WebVTT Caption Extraction

The skill first attempts to retrieve YouTube-provided captions using `fetch_captions`. The `parse_vtt` function in [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) handles the WebVTT parsing, producing clean, deduplicated text segments with accurate timestamps.

### 4. Whisper API Fallback

When native captions are unavailable and Whisper is enabled, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) calls `load_api_key` to retrieve credentials from `~/.config/watch/.env`, then invokes `transcribe_video` from [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) to generate a transcript from the downloaded audio.

### 5. Markdown Report Generation

The final output omits the "Frames" section entirely. According to the implementation in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the transcript prints inside a fenced code block within the Markdown report, containing only the timestamped spoken text.

## Usage Examples

Run these commands from the repository root to extract transcripts using different configurations:

```bash

# Basic usage – fetch only the transcript (captions or Whisper)

python -m skills.watch.scripts.watch \
  "https://www.youtube.com/watch?v=example" \
  --detail transcript

```

```bash

# Force Whisper transcription when captions are missing or insufficient

python -m skills.watch.scripts.watch \
  "https://www.youtube.com/watch?v=example" \
  --detail transcript \
  --whisper openai

```

```bash

# Combine transcript mode with specific cue frames

python -m skills.watch.scripts.watch \
  "https://www.youtube.com/watch?v=example" \
  --detail transcript \
  --timestamps "00:12,01:05"

```

- **Without `--timestamps`**: Downloads audio only, skips video frames entirely
- **With `--timestamps`**: Extracts frames at the specified timestamps while still generating the full transcript
- **With `--whisper openai` or `--whisper groq`**: Forces a specific Whisper backend instead of attempting caption extraction first

## Key Implementation Files

Understanding these source files helps customize the transcript extraction behavior:

- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)**: Entry point that parses `--detail transcript` and orchestrates the transcript-only execution path, including the `audio_only` logic and report formatting.
- **[`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py)**: Contains `parse_vtt` for cleaning WebVTT caption data and deduplicating rolling subtitles.
- **[`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py)**: Implements `transcribe_video` for Whisper API integration when native captions are unavailable.
- **[`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)**: Defines default detail modes and environment variable overrides (e.g., `WATCH_DETAIL`).
- **[`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py)**: Generates the `~/.config/watch/.env` configuration file where `OPENAI_API_KEY` or `GROQ_API_KEY` values are stored for Whisper authentication.

## Summary

- The **transcript detail mode** bypasses all frame extraction and returns only timestamped spoken text.
- When used without `--timestamps`, the mode activates `audio_only` download to minimize bandwidth.
- The pipeline prioritizes **WebVTT captions** from YouTube, falling back to **Whisper transcription** if captions are absent.
- Configuration and API keys are managed through [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and `~/.config/watch/.env`.
- Final output is a Markdown report containing the transcript in a fenced code block, with no "Frames" section.

## Frequently Asked Questions

### Does the transcript detail mode download the full video file?

No. When you specify `--detail transcript` without additional `--timestamps` flags, [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) sets `audio_only = True` and downloads only the audio track. This optimization reduces bandwidth consumption and processing time significantly compared to full video extraction.

### What happens if a YouTube video has no captions available?

If `fetch_captions` cannot retrieve WebVTT data, the workflow checks for Whisper configuration. When enabled via `--whisper openai` or `--whisper groq`, the script calls `transcribe_video` in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) to generate a transcript from the audio. If Whisper is not configured and no captions exist, the operation will fail with an appropriate error message.

### Can I combine transcript mode with frame extraction?

Yes. By adding the `--timestamps` parameter to `--detail transcript`, you instruct Claude-Video to generate the full transcript while also extracting frames at the specific timestamps provided. In this configuration, the script does not set `audio_only = True`, allowing both video frames and transcripts to be processed simultaneously.

### Where does Claude-Video store Whisper API credentials?

The [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) file generates a configuration directory at `~/.config/watch/` containing a `.env` file. This file stores your `OPENAI_API_KEY` or `GROQ_API_KEY`, which `load_api_key` in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) reads when initializing the Whisper fallback transcription.