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

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 and download.py so you can predict and control yt-dlp's behavior.

---

How the Audio-Only Decision Is Made

The watch.py script evaluates user input at line 111 to set the audio_only flag:

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 translates the boolean flag into a yt-dlp format selector at line 126:

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)

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)

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)

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:

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	CLI parsing, audio_only decision	Line 111
skills/watch/scripts/download.py	yt-dlp execution, format selection	Line 126

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 line 111 is the single control point
• 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 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 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.

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