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

> Discover the transcript-only detail mode in claude-video. Learn its purpose, how it works, and when to use it to extract only spoken or captioned text from media files.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-08-04

---

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

```python
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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script at line 111 forces an **audio‑only download** pathway:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) prints an explicit confirmation that frames were omitted:

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

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

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) | Main entry point; parses `--detail transcript`, forces audio‑only download, suppresses frame output |
| [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) | Defines permitted detail values including `"transcript"` |
| [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) | Parses subtitle files and formats the final transcript display |
| [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.