YouTube Caption Download

Download video subtitles and display content. Automatically detects video's original language and distinguishes between manual and auto-generated subtitles.

Quick Start

/mk-youtube-get-caption <URL> [language|auto] [--force]

Examples

/mk-youtube-get-caption https://youtube.com/watch?v=xxx - Auto-detect original language
/mk-youtube-get-caption https://youtube.com/watch?v=xxx auto - Explicitly use original language
/mk-youtube-get-caption https://youtube.com/watch?v=xxx ja - Download Japanese subtitles
/mk-youtube-get-caption https://youtube.com/watch?v=xxx "zh-TW,en" - Language priority list

Parameters

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | URL | Yes | - | YouTube video URL | | language | No | auto | Language code or priority list | | --force | No | false | Force re-download even if cached file exists |

Language Options

| Value | Behavior | |-------|----------| | (empty) | Auto-detect video's original language | | auto | Same as empty | | en, ja, etc. | Specific language code | | "en,ja,zh-TW" | Comma-separated priority list |

How it Works

Execute: {baseDir}/scripts/caption.sh "<URL>" "<language>"
If no language specified, detect video's original language
Try to download manual (author-uploaded) subtitles first
If unavailable, fall back to auto-generated subtitles
Parse JSON output to get file path and metadata
Use Read tool to get subtitle content if needed

Output Format

Success:

{
  "status": "success",
  "file_path": "{baseDir}/data/20091025__VIDEO_ID.en.srt",
  "text_file_path": "{baseDir}/data/20091025__VIDEO_ID.en.txt",
  "language": "en",
  "subtitle_type": "manual",
  "char_count": 30287,
  "line_count": 1555,
  "text_char_count": 25000,
  "text_line_count": 800,
  "cached": false,
  "video_id": "dQw4w9WgXcQ",
  "title": "Video Title",
  "channel": "Channel Name",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Cache hit (returns existing file):

{
  "status": "success",
  "file_path": "{baseDir}/data/20091025__VIDEO_ID.en.srt",
  "subtitle_type": "cached",
  "cached": true,
  ...
}

Error:

{
  "status": "error",
  "message": "No subtitles found (this video may not have subtitles)"
}

Output Fields

| Field | Description | |-------|-------------| | file_path | Absolute path to the downloaded SRT file | | text_file_path | Absolute path to plain text file (no timestamps) | | language | Detected language code of the downloaded subtitle | | subtitle_type | manual (author-uploaded) or auto-generated (YouTube AI) | | char_count | Number of characters in the SRT file | | line_count | Number of lines in the SRT file | | text_char_count | Number of characters in the plain text file | | text_line_count | Number of lines in the plain text file | | video_id | YouTube video ID | | title | Video title | | channel | Channel name | | url | Full video URL |

Filename Format

Files use unified naming with date prefix: {YYYYMMDD}__{video_id}.{lang}.{ext}

Example: 20091025__dQw4w9WgXcQ.en.srt

Notes

File caching: If caption file already exists for this video/language, it will be reused (returns cached: true)
Force refresh: Use --force flag to re-download even if cached file exists
Uses system yt-dlp/jq if available, otherwise auto-downloads on first run
Some videos may not have subtitles
Manual subtitles are prioritized over auto-generated ones
Auto-generated subtitles may be less accurate

Next Step

After downloading the caption, invoke /mk-youtube-transcript-summarize with the text_file_path from the output to generate a structured summary:

/mk-youtube-transcript-summarize <text_file_path>

IMPORTANT: Always use the Skill tool to invoke /mk-youtube-transcript-summarize. Do NOT generate summaries directly without loading the skill — it contains critical rules for compression ratio, section structure, data preservation, and language handling.