yt-transcript

You are using the YouTube Transcript (yt-dlp) Formatting skill.

Goal: produce a clean markdown transcript artifact in the established youtube-transcripts format.

When To Use This Skill

Invoke this skill when the user requests:

• /yt-transcript <URL>
• /yt-transcript <URL> output to <directory>
• /yt-transcript <URL> --no-chapters
• Any request to generate or update a YouTube transcript artifact

Core Contract

The script is the deterministic engine. The agent orchestrates:

• path selection
• explicit filename override requests (only when user asks)
• user confirmation
• result communication

The script handles extraction, fallback logic, formatting, and file writes. The script also auto-generates canonical filenames when given a directory target.

Runtime Requirements

Install dependencies into the same Python interpreter used to run the script. Python 3.10+ is required.

• macOS/Linux:

python -m pip install "yt-dlp[default]"

• Windows:

py -m pip install "yt-dlp[default]"

Optional fallback dependencies:

• youtube-transcript-api
• openai-whisper
• ffmpeg

Example install:

python -m pip install youtube-transcript-api openai-whisper

If your default python is older, create a venv with Python 3.10+ first:

/opt/homebrew/bin/python3.13 -m venv .venv
.venv/bin/python -m pip install "yt-dlp[default]" youtube-transcript-api

Workflow

Step 1: Determine Output Path

• Parse the user request for output directory or filename hints.
• If no directory is specified, propose a youtube-transcripts/ directory in the current workspace context.
• Build an absolute output path.

Step 2: Let Script Generate Filename

Default behavior: pass an output directory and let the script generate: YYYY-MM-DD_identifier_topic-keywords.md

Only pass an explicit .md file path when the user explicitly requests a custom filename.

Step 3: Decide Extraction Flags

Default invocation is English subtitle-first.

Available flags:

• --no-chapters: force flat transcript body
• --lang <code>: preferred subtitle language (default en)
• --proxy <url>: global proxy for yt-dlp requests
• --http-proxy <url>: HTTP proxy override for transcript API fallback
• --https-proxy <url>: HTTPS proxy override for transcript API fallback
• --cookies <file>: Netscape-format cookie file for yt-dlp
• --cookies-from-browser <spec>: browser cookie import for yt-dlp
• --yt-impersonate <client[:os]>: yt-dlp impersonation target
• --asr-fallback: use Whisper fallback if subtitle providers fail
• --asr-model <name>: Whisper model (default small)
• --no-artifact-on-failure: fail hard instead of writing fallback artifact

Step 4: Preview + Confirm

Before execution, show:

• output directory or explicit file path
• URL
• whether chapters are expected
• whether fallback flags will be used

Wait for user confirmation.

Step 5: Invoke Script

Use absolute paths and quote arguments.

Linux/macOS example:

python "/full/path/to/yt-transcript/script" "https://www.youtube.com/watch?v=VIDEO_ID" "/full/path/to/youtube-transcripts"

Windows example:

py "C:\path\to\yt-transcript\script" "https://www.youtube.com/watch?v=VIDEO_ID" "C:\path\to\youtube-transcripts"

With fallbacks:

python "/full/path/to/yt-transcript/script" "URL" "/full/path/to/youtube-transcripts" --cookies-from-browser "chrome" --proxy "socks5://127.0.0.1:1080" --asr-fallback

Step 6: Report Outcome

On success:

• confirm output path
• summarize whether transcript came from subtitles or fallback path

If fallback artifact was written (extraction failed but file created):

• tell user artifact exists
• summarize embedded extraction failure note
• suggest rerun flags if needed

Output Format Expectations

The generated markdown artifact should follow this shape:

• # <title>
• **Source:** ...
• **Speaker/Channel:** ...
• **Published:** ...
• **Duration:** ...
• **Type:** Video Transcript
• **Summary:** ...
• **Topics:** ...
• optional **Chapters:** list
• ---
• transcript body (chaptered when available unless --no-chapters)

Error Handling Guidance

Common failures and responses:

• yt-dlp missing in active interpreter -> provide interpreter-specific install command
• JS runtime / yt-dlp-ejs messages -> recommend yt-dlp[default] + runtime install
• missing preferred language subtitles -> ensure youtube-transcript-api is installed, then rerun
• no subtitles from provider fallbacks -> rerun with --asr-fallback
• blocked/rate-limited requests -> rerun with proxy flags (--proxy, --http-proxy, --https-proxy)
• gated/auth-required access -> rerun with --cookies or --cookies-from-browser
• invalid URL -> ask user to verify URL format

Important Notes

• Use the script as the source of truth for extraction and rendering.
• Do not manually parse VTT in the agent response flow.
• Always use absolute paths for invocation.
• Confirm with the user before running when path/flags are ambiguous.