name: omnicaptions-download
description: Use when downloading videos, audio, or captions from YouTube and other video platforms. Supports quality selection.
allowed-tools: Bash(omnicaptions:*)

Download from Video Platforms

Download videos, audio, and captions from YouTube and 1000+ video platforms using yt-dlp.

Confirmation Required

IMPORTANT: Before executing any download, you MUST confirm with the user using AskUserQuestion:

1. Show the URL to download
2. Show the quality setting (audio/video)
3. Show the output directory
4. Ask for confirmation

Example confirmation:

Ready to download:
- URL: https://youtube.com/watch?v=xxx
- Type: Audio only / Video (1080p)
- Save to: Current directory

Confirm download?

Only proceed with the download command after user confirms.

When to Use

• Download YouTube videos/audio for offline use
• Extract captions from video platforms
• Get audio for local transcription or editing

When NOT to Use

• Just need transcription (use /omnicaptions:transcribe - Gemini handles URLs directly)
• Converting existing caption formats (use /omnicaptions:convert)

Setup

pip install https://github.com/lattifai/omni-captions-skills/raw/main/packages/lattifai_captions-0.1.0.tar.gz
pip install https://github.com/lattifai/omni-captions-skills/raw/main/packages/omnicaptions-0.1.0.tar.gz

CLI Usage

Note: By default, files are saved to the current working directory. Do not specify -o unless the user explicitly requests a different location.

# Download audio only (default, saves to current directory)
omnicaptions download "https://www.youtube.com/watch?v=VIDEO_ID"

# Download video (1080p recommended)
omnicaptions download "https://youtube.com/watch?v=VIDEO_ID" -q 1080p

# Only use -o when user explicitly requests a different location
omnicaptions download "https://youtube.com/watch?v=VIDEO_ID" -o ./downloads/

Quality Presets

Output

Downloads produce:
- Audio/Video file: .m4a, .mp4, etc.
- Captions (if available): .vtt or .srt
- Metadata: .meta.json (video resolution, title, etc. for ASS font scaling)

Video: ./VIDEO_ID.mp4
Audio: ./VIDEO_ID.m4a
Caption: ./VIDEO_ID.en.vtt
Metadata: ./VIDEO_ID.meta.json  # Used by convert for auto font size
Title: Video Title Here

The .meta.json file stores video resolution, which omnicaptions convert uses to auto-calculate font size for ASS karaoke output.

Supported Platforms

YouTube, Bilibili, Vimeo, Twitter/X, and 1000+ sites.

Related Skills

Workflow Examples

Important: Generate bilingual captions AFTER LaiCut alignment. Preserve language tag in filename.

# Has caption: download → LaiCut align (JSON) → convert → translate
omnicaptions download "https://youtube.com/watch?v=xxx"
# → xxx.en.vtt
omnicaptions LaiCut xxx.mp4 xxx.en.vtt
# → xxx.en_LaiCut.json
omnicaptions convert xxx.en_LaiCut.json -o xxx.en_LaiCut.srt
# → xxx.en_LaiCut_Claude_zh.srt (after translate)

# No caption: download → transcribe → LaiCut align (JSON) → convert → translate
omnicaptions download "https://youtube.com/watch?v=xxx"
omnicaptions transcribe xxx.mp4
# → xxx_GeminiUnd.md
omnicaptions LaiCut xxx.mp4 xxx_GeminiUnd.md
# → xxx_GeminiUnd_LaiCut.json
omnicaptions convert xxx_GeminiUnd_LaiCut.json -o xxx_GeminiUnd_LaiCut.srt
# → xxx_GeminiUnd_LaiCut_Claude_zh.srt (after translate)