YouTube Bilingual Subtitles

Overview

Use this skill to turn a YouTube video link into reusable Chinese-English subtitle outputs:

• English .vtt subtitles downloaded with yt-dlp
• Chinese translation from YouTube's translated caption track when available
• Local English-to-Chinese machine translation fallback with Argos Translate
• A required local .md reading document with time-coded English and Chinese text
• A required bilingual .srt subtitle file
• Optional Feishu/Lark doc creation with lark-cli, created from the same Markdown file

The bundled script is the preferred path. Patch it only when the local environment or YouTube behavior requires it.

Quick Start

Run the bundled script from any workspace:

python3 ~/.codex/skills/youtube-bilingual-subtitles/scripts/youtube_bilingual_subtitles.py \
  --url "https://www.youtube.com/watch?v=VIDEO_ID" \
  --output-dir outputs \
  --create-feishu-doc

This produces the same three-part deliverable pattern used in the original workflow:

• markdown_file=...md local Markdown transcript for archiving or Feishu import
• subtitle_file=...srt bilingual subtitle file
• feishu_doc=... when --create-feishu-doc is used

If python3 is the system Python and dependencies are missing, activate a Python environment with the required dependencies installed, then run the same command with that environment's interpreter:

path/to/python3 \
  ~/.codex/skills/youtube-bilingual-subtitles/scripts/youtube_bilingual_subtitles.py \
  --url "https://www.youtube.com/watch?v=VIDEO_ID" \
  --output-dir outputs

If an English .vtt already exists, skip YouTube and generate local outputs from it:

python3 ~/.codex/skills/youtube-bilingual-subtitles/scripts/youtube_bilingual_subtitles.py \
  --english-vtt "path/to/video.en-US.vtt" \
  --output-dir outputs

Workflow

1. Confirm the user has rights to process full subtitles if they ask for full bilingual transcript output.
2. Prefer scripts/youtube_bilingual_subtitles.py for the whole workflow.
3. If YouTube public subtitle discovery says "no subtitles", retry with mobile player clients (android, then ios) before giving up.
4. Do not read browser cookies automatically. If a PO token or cookies are required, explain the limitation and ask before using any browser/session-derived data.
5. If YouTube Chinese translated captions fail with 429 or timeout, use local Argos Translate fallback.
6. For Feishu output, prefer Markdown import because long subtitle transcripts are simpler and safer as Markdown than XML.
7. Always return the Markdown file path and bilingual SRT path. If a Feishu doc is created, also return its URL.

Dependencies

The script expects:

• yt-dlp available as python -m yt_dlp, or installable with python -m pip install -U yt-dlp
• Optional local translation fallback: argostranslate
• Optional Feishu doc creation: lark-cli authenticated as user

Install local translation dependencies only when needed:

python3 -m pip install -U argostranslate

Then install the English-to-Chinese Argos package. The script can attempt this with --install-argos-model, but if the network is unstable, install once manually and rerun.

Output Conventions

Always create these user-facing files:

• <safe-title>.en.vtt
• <safe-title>.zh.vtt when YouTube Chinese captions were downloaded
• <safe-title>.bilingual.zh-en.srt
• <safe-title>.feishu-bilingual.md

The Markdown document should group subtitles into readable 30-40 second blocks:

### 10:14 - 10:45

**English**
...

**中文**
...

The SRT file should keep cue-level timing and include English followed by Chinese in each subtitle item.

Notes

• YouTube's normal web client may hide subtitles behind PO token restrictions. Mobile clients often expose caption tracks.
• YouTube translated tracks may be listed but fail to download because of rate limits. Treat this as recoverable and fall back to local translation.
• Local Argos translation is an initial machine translation. Tell the user technical terms may need human proofreading.
• The script includes a small AI-course glossary postprocessor for common mistranslations such as agents → 智能体 and prompts → 提示词. Extend the glossary in the script when working with a recurring domain.