yt-transcript-md

Extract a YouTube video's captions and metadata into a clean Markdown file for LLM context. Use when the user gives a YouTube URL or video ID and wants a transcript, captions, chapters, or rich video metadata saved locally.

Why

YouTube is one of the richest sources of context on the planet and one of the most annoying to get into a prompt. yt-transcript-md does the boring part:

• Pulls captions reliably (with a fallback for when the primary provider gets rate-limited).
• Enriches with rich metadata via yt-dlp — views, likes, comments, channel followers, tags, description, chapters.
• Splits the transcript under chapter headings when chapters exist, so the model can navigate.
• Writes a single Markdown file sized for an LLM context window.

Quick Start

npx yt-transcript-md SlGRN8jh2RI

That's it. You'll get a file at out/<youtube-id>-<timestamp>.md with metadata, chapters (if any), and a clean transcript — ready to paste.

Works with full URLs too:

npx yt-transcript-md "https://youtu.be/zjkBMFhNj_g"
npx yt-transcript-md "https://www.youtube.com/watch?v=zjkBMFhNj_g"

Global install — two commands, same tool

npm i -g yt-transcript-md

| Command | When to use | | --- | --- | | yt-transcript-md | Readable, self-documenting — good for scripts and docs | | ytx | Short alias — good for interactive use |

yt-transcript-md zjkBMFhNj_g
ytx zjkBMFhNj_g   # same thing

Variants

| Want | Flag | | --- | --- | | Markdown + [m:ss] appendix | --timestamps | | Plain text paragraph | --format text | | Only [m:ss] lines | --format timestamped | | Structured JSON | --format json | | Specific caption language | --lang <code> | | Custom output path | -o <path> | | Route requests through a proxy | --proxy <url> | | Skip yt-dlp (faster, fewer fields) | --metadata fast | | No metadata | --metadata none |

If yt-dlp is not on PATH: YTDLP_PATH=/path/to/yt-dlp npx yt-transcript-md <url-or-id>.

If YouTube challenges your server IP with "Sign in to confirm you're not a bot", route all YouTube requests through a working HTTP/HTTPS proxy:

npx yt-transcript-md SlGRN8jh2RI --proxy "http://user:pass@host:port" --metadata fast

You can also set YTX_PROXY for agent workflows:

export YTX_PROXY="http://user:pass@host:port"
npx yt-transcript-md SlGRN8jh2RI --metadata fast

Use it as a Skill (Claude Code & Codex)

The npm package ships SKILL.md, so installing it globally also makes the skill available to your agent — just link it into your skills directory.

npm i -g yt-transcript-md

# Claude Code
mkdir -p ~/.claude/skills/yt-transcript-md
ln -sf "$(ytx --skill-path)" ~/.claude/skills/yt-transcript-md/SKILL.md

# Codex CLI
mkdir -p ~/.codex/skills/yt-transcript-md
ln -sf "$(ytx --skill-path)" ~/.codex/skills/yt-transcript-md/SKILL.md

ytx --skill-path prints the absolute path to the bundled SKILL.md, so the install works under any package manager (npm, pnpm, yarn, Volta, fnm).

Restart your agent, then just ask: "grab the transcript for https://youtu.be/SlGRN8jh2RI". The symlink means npm update -g yt-transcript-md keeps the skill fresh too. See AGENTS.md for the full contract.

Use it as a Skill (Hermes Agent)

npm i -g yt-transcript-md
command -v ytx >/dev/null 2>&1 || export PATH="$(npm config get prefix)/bin:$PATH"
mkdir -p ~/.hermes/skills/yt-transcript-md
ln -sf "$(ytx --skill-path)" ~/.hermes/skills/yt-transcript-md/SKILL.md

Restart Hermes, then just ask: "grab the transcript for https://youtu.be/SlGRN8jh2RI". The symlink means npm update -g yt-transcript-md keeps the skill fresh too.

PATH Troubleshooting

If ytx or yt-transcript-md isn't found after install, your package manager's bin dir isn't on PATH yet. Add the right line to your shell profile (~/.zshrc, ~/.bashrc):

| Package manager | Add to shell profile | | --- | --- | | npm / pnpm | export PATH="$(npm config get prefix)/bin:$PATH" | | Volta | export PATH="$HOME/.volta/bin:$PATH" | | nvm | export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH" |

Then source ~/.zshrc (or open a new terminal) and re-run the ln -sf line.

Development

git clone https://github.com/marcinlerka/yt-transcript-md.git
cd yt-transcript-md
npm install
npm run ytx -- <id>     # run via tsx, no build needed
npm run typecheck
npm test
npm run build           # emit dist/ for publishing

npm run ytx uses tsx from dev dependencies, so iteration is fast. The published binary runs against the compiled dist/ and registers both ytx and yt-transcript-md commands.

Notes

The primary caption provider is youtube-transcript, with a direct YouTube timedtext parser kept as a fallback. YouTube can still rate-limit or return empty responses from some IPs — for agent workflows, cache outputs whenever you can.

License

MIT