# How Transcript-Only Mode in Claude-Video Completely Skips Frame Extraction

> Discover how Claude-Video's transcript-only mode bypasses frame extraction. Learn how it optimizes processing by leveraging conditional checks and setting video_path to None for efficient transcript generation.

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

---

**Claude-Video bypasses all frame extraction when `--detail transcript` is used by setting `video_path = None` and blocking the ffmpeg processing pipeline through conditional checks in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).**

The `bradautomates/claude-video` repository provides a `watch` command that supports a **transcript-only mode** for lightweight video analysis. When you specify `--detail transcript` without cue timestamps, the tool executes a coordinated three-step bypass in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) that prevents any video download or frame processing from occurring.

## Detecting Transcript-Only Mode

The script first identifies transcript-only requests using a boolean flag that checks both the detail level and timestamp requirements.

```python
audio_only = detail == "transcript" and not cue_timestamps

```

This assignment at line 111-112 sets `audio_only = True` only when the user requests `transcript` detail and does not provide explicit cue timestamps. This flag drives subsequent decisions about resource fetching and processing pipelines.

## Skipping Video Download Entirely

When operating in transcript-only mode, the script prevents the video file from being downloaded, which eliminates the source data required for frame extraction.

```python
if detail == "transcript" and transcript_segments and not cue_timestamps:
    video_path = None               # No video needed → no frames

else:
    … download video …

```

As implemented at lines 112-115, this conditional forces `video_path = None` when subtitles are already available (`transcript_segments`) and no cue timestamps are requested. Without a valid video path, the downstream frame extraction logic cannot execute.

## Blocking the Frame Extraction Pipeline

The final safeguard occurs at the frame processing stage, where a guard clause explicitly prevents the heavy ffmpeg operations from running.

```python
if detail != "transcript" and video_path and detail_budget != 0:
    # … extract keyframes or scene-aware frames …

```

Located at lines 196-198, this condition ensures that **frame extraction only runs when three criteria are met**: the detail level is not `transcript`, a valid video path exists, and the detail budget is non-zero. In transcript-only mode, the first condition fails, completely bypassing the `extract_keyframes` and `extract_scene_or_uniform` functions defined in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).

## User-Facing Confirmation

When the frame extraction step is skipped, the tool provides clear feedback in the output report.

```python
elif not cue_frames:
    print("- **Frames:** skipped (transcript detail)")

```

This messaging at lines 299-301 confirms to the user that no frames were processed due to the transcript detail setting, providing transparency about the skipped processing step.

## Practical Usage Examples

Use the following command patterns to control frame extraction behavior:

```bash

# Transcript-only – no frames are extracted

watch https://example.com/video.mp4 --detail transcript

```

```bash

# Transcript-only with explicit cue timestamps – frames extracted only for specific times

watch https://example.com/video.mp4 \
      --detail transcript \
      --timestamps "00:30,01:45"

```

In the first example, the script sets `audio_only=True`, never downloads the video, and skips all frame extraction calls. In the second example, the presence of `--timestamps` clears the `audio_only` flag and triggers a full video download solely to extract frames at the requested timestamps.

## Key Implementation Files

The transcript-only bypass logic spans several coordinated files:

- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)**: Central orchestration that parses arguments, determines the `detail` level, and decides whether to download video and run frame extraction.
- **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)**: Implements the ffmpeg-heavy frame extraction functions (`extract_keyframes`, `extract_scene_or_uniform`) that are conditionally called only when `detail != "transcript"`.
- **[`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)**: Supplies default `detail` settings and frame caps used by the decision logic.
- **[`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py)**: Handles subtitle parsing and transcript formatting used when subtitles are the only text source.

## Summary

- **Detection**: The `audio_only` flag at line 111 identifies transcript-only requests by checking `detail == "transcript"` and `not cue_timestamps`.
- **Prevention**: The video download is skipped at lines 112-115 by setting `video_path = None` when transcripts exist and no timestamps are requested.
- **Blocking**: The frame extraction guard at lines 196-198 uses `detail != "transcript"` to prevent ffmpeg processing from running.
- **Transparency**: Users see "Frames: skipped (transcript detail)" in the output when frame extraction is bypassed.
- **Efficiency**: This three-step process saves bandwidth, disk space, and compute resources by avoiding video downloads and ffmpeg operations entirely.

## Frequently Asked Questions

### Can I extract specific frames while using transcript-only mode?

Yes, by adding the `--timestamps` flag with specific timecodes, you override the transcript-only bypass. When `cue_timestamps` are provided, the `audio_only` flag evaluates to `False`, forcing a video download and frame extraction limited to your specified timestamps.

### What happens if no transcript is available when using --detail transcript?

If `transcript_segments` is not available, the condition at lines 112-115 fails and the video downloads normally. However, the frame extraction block at lines 196-198 still checks `detail != "transcript"`, so frames would not be extracted unless the logic falls through to a different handling path.

### Why does the tool set `video_path = None` instead of just skipping the extraction loop?

Setting `video_path = None` provides a defense-in-depth mechanism. While the frame extraction guard at lines 196-198 does check `detail != "transcript"`, the null video path ensures that even if that logic were modified or bypassed, subsequent code expecting a valid file path would fail safely rather than attempting to process a non-existent video.

### Which file contains the conditional logic that prevents frame extraction?

The primary conditional logic resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at lines 196-198, where the guard clause `if detail != "transcript" and video_path and detail_budget != 0:` controls access to the frame extraction pipeline. The actual ffmpeg-based extraction functions that are being skipped are implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).