# When Does yt-dlp Extract Only Audio vs Full Video in claude-video?

> Learn when yt-dlp extracts only audio versus full video for claude-video. Discover the specific conditions for audio-only or full video downloads based on detail modes and timestamps.

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

---

**yt-dlp downloads audio-only when the `transcript` detail mode is selected without timestamps, and full video for all other detail modes or when timestamps are provided.**

The `claude-video` repository uses a conditional flag system to optimize downloads based on user intent. Whether you need just audio for transcription or full video for frame analysis depends on two CLI parameters: `--detail` and `--timestamps`. This guide breaks down the exact logic in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) and [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) so you can predict and control yt-dlp's behavior.

---

## How the Audio-Only Decision Is Made

The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script evaluates user input at line 111 to set the `audio_only` flag:

```python
audio_only = detail == "transcript" and not cue_timestamps   # ← watch.py L111

```

This single expression governs all downstream format selection. The flag becomes **True** only when both conditions are satisfied:

| Condition | Required Value | Purpose |
|-----------|--------------|---------|
| `detail` | `"transcript"` | Signals intent to generate text output only |
| `cue_timestamps` | Empty/absent | No frame extraction needed at specific times |

Any deviation—different detail mode or explicit timestamps—forces `audio_only = False` and triggers a full video download.

---

## The Format String Passed to yt-dlp

The `download_url` function in [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) translates the boolean flag into a yt-dlp format selector at line 126:

```python
fmt = "ba/bestaudio" if audio_only else "bv*[height<=720]+ba/b[height<=720]/bv+ba/b"

```

**For audio-only downloads (`audio_only=True`):**

- `"ba/bestaudio"` requests the best available audio stream without video
- `ba` = best audio (yt-dlp shorthand)
- `bestaudio` = fallback if `ba` is unavailable

**For full video downloads (`audio_only=False`):**

- Composite format selects video up to 720p plus audio
- Falls back through multiple quality tiers if preferred streams are unavailable

This format string directly controls whether yt-dlp performs a lightweight audio extraction or a heavier video merge operation.

---

## Command Examples: Triggering Each Mode

### Audio-Only Download (Transcript Without Timestamps)

```bash
watch https://youtu.be/dQw4w9WgXcQ --detail transcript

```

This produces `audio_only = True` → yt-dlp runs with `"ba/bestaudio"` → only audio file saved.

### Full Video Download (Other Detail Modes)

```bash
watch https://youtu.be/dQw4w9WgXcQ --detail balanced
watch https://youtu.be/dQw4w9WgXcQ --detail efficient
watch https://youtu.be/dQw4w9WgXcQ --detail token-burner

```

All three set `audio_only = False` → yt-dlp downloads video + audio streams.

### Full Video Even With Transcript (Timestamps Provided)

```bash
watch https://youtu.be/dQw4w9WgXcQ --detail transcript --timestamps "00:30,01:15"

```

The non-empty `cue_timestamps` overrides the audio-only optimization—frames are needed at the specified times.

---

## Programmatic Control for Developers

You can bypass the CLI logic and call the download helper directly:

```python
from pathlib import Path
from skills.watch.scripts.download import download_url

# Force audio-only extraction

result = download_url(
    "https://youtu.be/dQw4w9WgXcQ",
    Path("/tmp/watch-download"),
    audio_only=True,
)

# Force full video download

result = download_url(
    "https://youtu.be/dQw4w9WgXcQ",
    Path("/tmp/watch-download"),
    audio_only=False,
)

```

The `audio_only` parameter accepts an explicit boolean, making it suitable for testing, automation scripts, or custom integrations.

---

## Source Files and Key Lines

| File | Role | Critical Line |
|------|------|---------------|
| [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) | CLI parsing, `audio_only` decision | [Line 111](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L111) |
| [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) | yt-dlp execution, format selection | [Line 126](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py#L126) |

These two files implement the complete pipeline from user intent to yt-dlp invocation.

---

## Summary

- **Audio-only extraction** requires `--detail transcript` with **no** `--timestamps`
- **Full video download** occurs for all other detail modes or when timestamps are supplied
- The `audio_only` boolean in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) line 111 is the single control point
- [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) line 126 converts this flag to yt-dlp format strings: `"ba/bestaudio"` versus composite video formats
- Developers can override via direct `download_url()` calls with explicit `audio_only` parameter

---

## Frequently Asked Questions

### What happens if I specify `--detail transcript` with timestamps?

yt-dlp downloads the full video. The presence of timestamps indicates you need frames at specific moments, so the `audio_only` flag becomes `False` even though you requested transcript detail.

### Can I force audio-only download with timestamps?

Not through the standard CLI. The logic in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) treats timestamps as requiring video. You would need to modify the source or call `download_url()` directly with `audio_only=True` and handle timestamp extraction separately.

### Why is video quality capped at 720p?

The format string in [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) explicitly limits video height with `height<=720`. This balances quality against download size and processing time for frame extraction. The repository prioritizes efficiency over maximum resolution.

### Does audio-only mode skip Whisper transcription?

No. Audio-only downloads still proceed to transcription via subtitles (if available in the video) or Whisper processing. The mode only affects what yt-dlp fetches, not the downstream NLP pipeline.