What Is the Transcript‑Only Detail Mode in claude‑video? Purpose, Behavior, and Use Cases

The transcript‑only detail mode skips all video‑frame extraction and returns only the spoken or captioned text from a source media file.

The transcript‑only detail mode is a specialized operating setting in claude‑video's watch skill, designed for users who need rapid, text‑only access to video content without the computational overhead of frame analysis. This mode is particularly valuable when working with large video libraries or when token efficiency in downstream LLM processing is a priority.

How Transcript‑Only Mode Works in watch.py

The mode is controlled through the --detail command‑line argument, which accepts one of four fidelity options defined in skills/watch/scripts/watch.py at line 36:

DETAIL_OPTIONS = ["transcript", "efficient", "balanced", "token-burner"]

The help text at line 38 explicitly describes this mode as "transcript (no frames)", making its behavior immediately clear to users.

Audio‑Only Download Trigger

When detail == "transcript", the watch.py script at line 111 forces an audio‑only download pathway:

if detail == "transcript" and not timestamps:
    download_audio_only = True

This single conditional check eliminates the heavier video download and frame extraction pipeline entirely, reducing both bandwidth consumption and processing time.

Skipped Frame Reporting

In the final report generation section (lines 300‑306), watch.py prints an explicit confirmation that frames were omitted:

if detail == "transcript":
    print("**Note:** Frames skipped — transcript only.")

This transparency ensures users understand exactly what was processed and what was excluded.

When to Use Transcript‑Only Mode

This detail setting excels in three primary scenarios:

• Quick summarization — Extract the full spoken content for rapid review without visual distraction
• Text‑only analysis — Feed transcript data into NLP pipelines, search indexes, or document processing workflows
• Token optimization — Minimize context window usage in downstream LLM calls by eliminating frame descriptions and image embeddings

Command Examples for Transcript‑Only Mode

Basic Transcript Extraction

watch https://www.youtube.com/watch?v=abc123 --detail transcript

This produces a markdown report containing only the formatted transcript, with no frame references.

Transcript with Timestamps

watch https://example.com/video.mp4 --detail transcript --timestamps 10,30,45

This variant still skips frame extraction but adds cue timestamps at the specified moments. These cues are treated as "transcript‑cued" references—text annotations without associated visual frames.

Supporting Files in the claude‑video Repository

The transcript‑only mode spans multiple source files:

File	Purpose
skills/watch/scripts/watch.py	Main entry point; parses --detail transcript, forces audio‑only download, suppresses frame output
skills/watch/scripts/config.py	Defines permitted detail values including "transcript"
skills/watch/scripts/transcribe.py	Parses subtitle files and formats the final transcript display
skills/watch/SKILL.md	Documents the slash‑command interface for the watch skill

Summary

• Transcript‑only mode (--detail transcript) eliminates all frame processing from the claude‑video pipeline
• The implementation in watch.py forces audio‑only downloads and prints explicit frame‑skip confirmation
• Four fidelity levels exist: transcript, efficient, balanced, and token‑burner
• Use this mode for speed, bandwidth savings, and token‑efficient text extraction from video sources

Frequently Asked Questions

What happens to frame analysis when I use --detail transcript?

Frame analysis is completely bypassed. According to the watch.py source code, the conditional at line 111 sets download_audio_only = True, which routes the pipeline through an audio‑extraction path that never invokes frame generation or computer vision processing.

Can I still get timestamps with transcript‑only mode?

Yes. The --timestamps flag functions normally with transcript‑only mode. When combined, the script downloads audio only, extracts the transcript, and inserts cue markers at your specified timestamps—still without generating any visual frames.

How does transcript‑only mode compare to the other detail settings?

transcript provides maximum speed and minimum token usage by returning text only. efficient and balanced include selected frames at reduced sampling rates. token‑burner processes the full video with maximum frame density for comprehensive visual analysis. Choose based on whether your use case requires visual evidence or can operate on spoken content alone.

Why would I choose transcript‑only over efficient mode?

Choose transcript‑only when you explicitly do not need visual information. If you are analyzing speeches, podcast content, or captioned tutorials where the spoken text contains all relevant information, transcript‑only eliminates unnecessary computation. Efficient mode still downloads and processes some frames, which adds latency and token cost even when visual data provides marginal value.

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