How to Use the Transcript Detail Mode in Claude-Video

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 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, 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 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 calls load_api_key to retrieve credentials from ~/.config/watch/.env, then invokes transcribe_video from 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, 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:

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

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

# 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

# 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: 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: Contains parse_vtt for cleaning WebVTT caption data and deduplicating rolling subtitles.
• skills/watch/scripts/whisper.py: Implements transcribe_video for Whisper API integration when native captions are unavailable.
• skills/watch/scripts/config.py: Defines default detail modes and environment variable overrides (e.g., WATCH_DETAIL).
• 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 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 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 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 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 reads when initializing the Whisper fallback transcription.

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