Skip to content
Back to search

youtube-translate

SkillWorks with Claude CodeGitHub

Given YouTube links (videos, channels, playlists) or local folders/files (subtitles or media), produce per-language translated SRT subtitle files (default en, uk, de, fr, es, pl) ready to upload to YouTube, plus accuracy QA. Works with any OpenAI-compatible endpoint, or with no endpoint at all — the calling model does the translation itself. Not for dubbing/voice-over, video editing, or titles/thumbnails.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/0xsero--youtube-translate-skill/badge.svg)](/listings/0xsero--youtube-translate-skill)

HTML

<a href="/listings/0xsero--youtube-translate-skill"><img src="/api/listings/0xsero--youtube-translate-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Copy the folder into your agent's skills directory:

| Agent | Skills directory | |---|---| | Claude Code | `~/.claude/skills/youtube-translate/` | | Codex | `~/.codex/skills/youtube-translate/` | | omp | `~/.agents/skills/youtube-translate/` | | generic | any folder your harness scans for `SKILL.md` |

git clone https://github.com/<you>/youtube-translate-skill
cp -r youtube-translate-skill ~/.claude/skills/youtube-translate   # adjust path per table

Then ask your agent to "translate <YouTube link or folder> into <languages>". `SKILL.md` carries the full instructions the model follows (both modes and the agent loop).

Standalone (no agent) works too — just call the scripts directly as shown below.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 82 lines
  1. ---
  2. name: youtube-translate
  3. description: Given YouTube links (videos, channels, playlists) or local folders/files (subtitles or media), produce per-language translated SRT subtitle files (default en, uk, de, fr, es, pl) ready to upload to YouTube, plus accuracy QA. Works with any OpenAI-compatible endpoint, or with no endpoint at all — the calling model does the translation itself. Not for dubbing/voice-over, video editing, or titles/thumbnails.
  4. ---
  5. # YouTube / media → translated subtitles
  6. Everything is in `scripts/`. Requirements: `python3` (stdlib only) and `yt-dlp` on PATH for YouTube
  7. inputs. Translation is done either by an OpenAI-compatible endpoint **or by you, the calling model**.
  8. Local media without subtitles is transcribed only if an ASR tool is installed (`faster-whisper`,
  9. `mlx_whisper`, or the `whisper` CLI); otherwise that item is marked `needs-asr` and the run continues.
  10. ## Inputs
  11. Pass any mix of:
  12. - YouTube **video**, **channel** (`https://youtube.com/@Handle`, `/videos`, `/streams`), or **playlist** URLs. `--latest N` = newest N per channel/playlist (0 = all).
  13. - Local **folders or files**: `.srt`, `.vtt`, YouTube `.json3`, or media (`.mp4/.mkv/.mov/.webm/.mp3/.m4a/.wav`). A sidecar subtitle with the same stem is used when present; otherwise media is transcribed (if an ASR tool exists).
  14. `--langs` sets target codes (default `en,uk,de,fr,es,pl`); the source language is skipped automatically.
  15. ## Output (per item, stable across re-runs)
  16. ```
  17. <out>/<source>/<YYYYMMDD>_<slug>_<id>/
  18. video.json metadata, cues, status
  19. original-script.md full original transcript in paragraphs
  20. original.<src>.srt timed original captions
  21. translations/<lang>.srt one SRT per target language, same cues/timings
  22. translations/<lang>.md readable transcript in that language (same paragraph breaks as original-script.md)
  23. ```
  24. ## Mode A — you have an OpenAI-compatible endpoint
  25. ```bash
  26. export YT_TX_BASE_URL=http://<host>:<port>/v1 YT_TX_API_KEY=<key> YT_TX_MODEL=<served-model>
  27. python3 scripts/yt_translate.py run <inputs...> --langs en,uk,de --out ./out --concurrency 8
  28. ```
  29. Re-running is safe: finished `<lang>.srt` files are skipped and every chunk is cached under `<video>/.cache/`.
  30. ## Mode B — no endpoint: you translate (agent mode)
  31. 1. **prepare** — ingest and write numbered work items (no network model needed for translation):
  32. ```bash
  33. python3 scripts/yt_translate.py prepare <inputs...> --langs en,uk,de --out ./out
  34. ```
  35. This writes, per video and language, chunks at `<video>/.work/<lang>/<n>.in.json`:
  36. ```json
  37. {"_meta": {"source_language": "...", "target_language": "...", ...},
  38. "1": "first source line", "2": "second source line", ...}
  39. ```
  40. 2. **translate each work item yourself.** For every `<n>.in.json`:
  41. - Read it. Translate each numbered value from `_meta.source_language` into `_meta.target_language`.
  42. - Lines are consecutive speech fragments; a sentence may span lines — translate so they read naturally in order.
  43. - Write `<n>.out.json` **next to it**: the **same numbered keys** (no `_meta`), each value a **non-empty** translated string.
  44. - Fan this out with subagents or parallel calls if your harness supports it — the items are independent.
  45. 3. **check what's left** (optional): `python3 scripts/yt_translate.py status --out ./out` lists pending items.
  46. 4. **assemble** — validate every `.out.json` and write the SRTs:
  47. ```bash
  48. python3 scripts/yt_translate.py assemble --out ./out
  49. ```
  50. Any item with missing/extra keys or empty values is reported as `invalid`; incomplete languages are
  51. reported and skipped. Fix those `.out.json` files and run `assemble` again.
  52. ## Accuracy QA
  53. ```bash
  54. # structural only (always available, no model):
  55. python3 scripts/qa.py run ./out --sample 0
  56. # with an endpoint GEMBA-MQM judge (use a DIFFERENT model than the translator if you can):
  57. export YT_QA_BASE_URL=... YT_QA_MODEL=... YT_QA_API_KEY=...
  58. python3 scripts/qa.py run ./out --sample 40 --review en,uk
  59. # agent-mode judge (no endpoint): prepare -> fill qa/.judge/*/1.out.json -> assemble
  60. python3 scripts/qa.py prepare ./out --sample 40
  61. python3 scripts/qa.py assemble ./out
  62. ```
  63. The judge follows **GEMBA-MQM** (Kocmi & Federmann, 2023): per line it lists errors by category
  64. (accuracy/mistranslation, omission, addition, terminology, fluency/grammar) × severity (critical 25 /
  65. major 5 / minor 1). Line score = 100 − penalties, clipped at 0. Outputs: `qa/report.md`, `qa/flags.jsonl`,
  66. `qa/judge.jsonl`, `qa/review-*.md`.
  67. ## Upload to YouTube
  68. YouTube Studio → Subtitles → the video → Add language → Upload file → "With timing" → `translations/<lang>.srt`.
  69. ## Known failures
  70. - Members-only/private videos fail in yt-dlp ("Join this channel…") and are logged; the rest continue.
  71. - Videos with captions disabled (or music only) end up `no-captions`.
  72. - Dubbed videos expose several `*-orig` ASR tracks; only the declared-language one is the true original.
  73. - Some videos need cookies: set `YT_DLP_COOKIES_FROM_BROWSER` (e.g. `chrome`, `brave:Profile 1`) or `YT_DLP_COOKIES` (a cookies.txt path).
README.md · README · 120 lines
  1. # youtube-translate-skill
  2. A self-contained **agent skill**: give it YouTube links (videos, channels, playlists) or local
  3. folders/files, and the calling model produces **translated subtitle files** (`.srt`) ready to upload to
  4. YouTube — in several languages at once (default `en, uk, de, fr, es, pl`).
  5. It needs nothing beyond **`python3` (stdlib only)** + **`yt-dlp`** + **the calling model**. An
  6. OpenAI-compatible endpoint is an optional accelerator, not a requirement: in *agent mode* the model that
  7. runs the skill does the translation itself.
  8. ## Install as a skill
  9. Copy the folder into your agent's skills directory:
  10. | Agent | Skills directory |
  11. |---|---|
  12. | Claude Code | `~/.claude/skills/youtube-translate/` |
  13. | Codex | `~/.codex/skills/youtube-translate/` |
  14. | omp | `~/.agents/skills/youtube-translate/` |
  15. | generic | any folder your harness scans for `SKILL.md` |
  16. ```bash
  17. git clone https://github.com/<you>/youtube-translate-skill
  18. cp -r youtube-translate-skill ~/.claude/skills/youtube-translate # adjust path per table
  19. ```
  20. Then ask your agent to "translate <YouTube link or folder> into <languages>". `SKILL.md` carries the
  21. full instructions the model follows (both modes and the agent loop).
  22. Standalone (no agent) works too — just call the scripts directly as shown below.
  23. ## Requirements
  24. - `python3` ≥ 3.8 (standard library only — no pip installs).
  25. - `yt-dlp` on PATH for YouTube inputs: `pipx install yt-dlp` or `brew install yt-dlp`.
  26. - Optional, for local media without subtitles: one of `faster-whisper`, `mlx_whisper`, or the `whisper` CLI. If none is installed, such items are marked `needs-asr` and skipped (the rest of the run continues).
  27. - Optional: an OpenAI-compatible `/chat/completions` endpoint for Mode A.
  28. ## Quickstart
  29. ### Mode A — OpenAI-compatible endpoint
  30. ```bash
  31. export YT_TX_BASE_URL=http://<host>:<port>/v1 YT_TX_API_KEY=<key> YT_TX_MODEL=<served-model>
  32. python3 scripts/yt_translate.py run \
  33. "https://www.youtube.com/@SomeChannel" --latest 10 --langs en,uk,de --out ./out --concurrency 8
  34. ```
  35. Env falls back to `OPENAI_BASE_URL` / `OPENAI_API_KEY` / `OPENAI_MODEL`. The key is never printed.
  36. ### Mode B — no endpoint, the model translates (agent mode)
  37. ```bash
  38. python3 scripts/yt_translate.py prepare ./my-folder --langs en,uk,de --out ./out
  39. # the agent reads each out/<video>/.work/<lang>/<n>.in.json, writes <n>.out.json beside it
  40. python3 scripts/yt_translate.py status --out ./out # what's still pending
  41. python3 scripts/yt_translate.py assemble --out ./out # validate + write the SRTs
  42. ```
  43. Each `.in.json` is a numbered map of source lines plus a `_meta` block naming the source and target
  44. language. The matching `.out.json` must keep the **same numbered keys** (no `_meta`) with **non-empty**
  45. translated strings. See `SKILL.md` for the exact loop.
  46. ### Inputs
  47. Mix freely in one call:
  48. - YouTube **video** / **channel** (`@handle`, `/videos`, `/streams`) / **playlist** URLs — `--latest N`.
  49. - Local **folders or files**: `.srt`, `.vtt`, YouTube `.json3`, or media (`.mp4 .mkv .mov .webm .mp3 .m4a .wav`). A sidecar subtitle with the same stem is used if present; otherwise media is transcribed when an ASR tool is installed (`--no-asr` disables transcription; `--asr-model` picks the Whisper size).
  50. ## Output layout
  51. ```
  52. <out>/<source>/<YYYYMMDD>_<slug>_<id>/
  53. video.json metadata, caption track used, cues, status
  54. original-script.md full original transcript in paragraphs
  55. original.<src>.srt timed original captions (cue-segmented)
  56. translations/<lang>.srt one SRT per target language, cue-for-cue aligned with the original
  57. translations/<lang>.md readable transcript in that language (same paragraph breaks as original-script.md)
  58. <out>/run-summary.json per-item status (Mode A)
  59. ```
  60. ## Upload to YouTube
  61. YouTube Studio → **Subtitles** → pick the video → **Add language** → **Upload file** → **"With timing"**
  62. → choose `translations/<lang>.srt`. Repeat per language. Review and publish.
  63. ## Accuracy QA
  64. There is no human reference translation, so `scripts/qa.py` combines the two checks normally used in that
  65. situation:
  66. - **Structural checks** (every cue, no model): cue count & timing parity with the original, empty or
  67. untranslated lines, wrong script, Russian-letter leakage in Ukrainian, length-ratio outliers, repeat
  68. loops. These are **leads, not verdicts** — brand and person names routinely trip the script/letter checks.
  69. - **GEMBA-MQM judge** (optional, on a sample): an LLM annotator marks each line's errors by **category**
  70. (accuracy/mistranslation, accuracy/omission, accuracy/addition, terminology, fluency/grammar) and
  71. **severity** (critical / major / minor). The per-line score is **100 − weighted penalties**
  72. (critical 25, major 5, minor 1), clipped at 0. This follows **GEMBA-MQM** (Kocmi & Federmann, 2023),
  73. which ranked top for correlation with human judgement at WMT23. Use a **different** model than the
  74. translator (`YT_QA_*`) — a model grading its own output is biased upward. With no endpoint, run the same
  75. `prepare` → fill `qa/.judge/*/1.out.json` → `assemble` loop.
  76. ```bash
  77. python3 scripts/qa.py run ./out --sample 0 # structural only
  78. python3 scripts/qa.py run ./out --sample 40 --review en,uk # + endpoint GEMBA-MQM judge
  79. python3 scripts/qa.py prepare ./out --sample 40 # agent-mode judge: write judge items
  80. python3 scripts/qa.py assemble ./out # ...then score + report
  81. ```
  82. Outputs: `qa/report.md`, `qa/flags.jsonl`, `qa/judge.jsonl`, `qa/review-<a>-<b>.md` (side-by-side sheet,
  83. worst lines first, for a bilingual spot-check).
  84. **Limits of the QA:** the LLM judge is an estimate, not a human verdict; it can miss subtle errors and is
  85. biased toward its own style. Structural flags over-report on names and transliteration. Treat both as
  86. triage that points a human reviewer at the riskiest lines, not as a pass/fail gate.
  87. ## Known failures
  88. - **Members-only / private videos**: yt-dlp fails ("Join this channel…"); logged, run continues.
  89. - **No captions**: captions disabled or music-only videos end up `no-captions`.
  90. - **Dubbed `-orig` tracks**: a dubbed video exposes several `*-orig` ASR tracks; only the declared-language
  91. one is the true original. The others are skipped.
  92. - **Cookie-gated videos**: set `YT_DLP_COOKIES_FROM_BROWSER` (e.g. `chrome`, `brave:Profile 1`) or
  93. `YT_DLP_COOKIES` (a cookies.txt path) if yt-dlp asks you to "confirm you're not a bot".
  94. - **Local media, no ASR tool**: items without a sidecar subtitle are marked `needs-asr`; install
  95. `faster-whisper`/`mlx_whisper`/`whisper` or add a `.srt`/`.vtt` with the same stem.
  96. ## References
  97. - Tom Kocmi and Christian Federmann. *GEMBA-MQM: Detecting Translation Quality Error Spans with GPT-4.*
  98. WMT 2023. https://aclanthology.org/2023.wmt-1.64/
  99. ## License
  100. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.