Use when the user wants to repurpose a YouTube video for Bilibili, add bilingual (English-Chinese) subtitles to a video, or create hardcoded subtitle versions for Chinese platforms.
Use when the user wants to repurpose a YouTube video for Bilibili, add bilingual (English-Chinese) subtitles to a video, or create hardcoded subtitle versions for Chinese platforms.
license
MIT
homepage
https://github.com/Agents365-ai/yt2bb
compatibility
Requires Python 3, ffmpeg, yt-dlp, whisper (openai-whisper) on PATH. Self-check steps that need vision are gracefully skipped if unavailable.
Resolve SKILL_DIR for use by later pipeline steps:
# Find the skill dir: a 'yt2bb' folder that actually contains SKILL.md.# Works whether installed flat (~/.claude/skills/yt2bb) or pulled from this repo (skills/yt2bb).
SKILL_DIR="$(find ~/.claude/skills ~/.openclaw/skills ~/.hermes/skills ~/.pi/agent/skills ~/.agents/skills ~/myagents/myskills -type d -name 'yt2bb' -exec test -f '{}/SKILL.md' \; -print 2>/dev/null | head -1)"
%(playlist_index)03d: zero-padded index to preserve playlist order
If --cookies-from-browser fails, export cookies first — see Troubleshooting
Step 2: Transcribe
First run the environment check to detect your platform and get a tailored whisper command:
python3 "$SKILL_DIR/srt_utils.py" check-whisper
This auto-detects OS, GPU (CUDA/Metal/CPU), memory, and installed backends, then recommends the best backend + model for your hardware. If memory detection is unavailable, it falls back conservatively instead of assuming a low-memory machine. Use the command it prints.
Manual fallback (openai-whisper, works everywhere):
src_lang="en"# Change to ja/ko/es/etc. based on source video
whisper_model="medium"# check-whisper recommends the best model for your hardware
whisper "${slug}/${slug}.mp4" \
--model "$whisper_model" \
--language "$src_lang" \
--word_timestamps True \
--condition_on_previous_text False \
--output_format srt \
--max_line_width 40 --max_line_count 1 \
--output_dir "${slug}"mv"${slug}/${slug}.srt""${slug}/${slug}_${src_lang}.srt"
Supported backends:
Backend
Best for
Install
mlx-whisper
macOS Apple Silicon (fastest)
pip install mlx-whisper
whisper-ctranslate2
Windows/Linux CUDA, or CPU (~4x faster)
pip install whisper-ctranslate2
openai-whisper
Universal fallback
pip install openai-whisper
Model selection (auto-recommended by check-whisper):
tiny — fast draft, low accuracy, CPU-friendly (~1 GB)
medium — default, good balance (~5 GB)
large-v3 — best accuracy, recommended for JA/KO/ZH source (~10 GB)
Notes:
--language: explicitly set to avoid misdetection; supports en, ja, ko, es, etc.
--word_timestamps True: more precise subtitle timing
Read {slug}_{src_lang}.srt and translate to Chinese. Critical rules:
These rules are modeled on the Netflix Simplified Chinese Timed Text Style Guide; follow them to produce broadcast-grade subtitles.
Keep SRT format intact — preserve index numbers, timestamps (--> lines) exactly as-is
1:1 entry mapping — every source entry must produce exactly one translated entry (same count)
Optimize for bottom subtitles — keep each Chinese entry to 1 line whenever possible so the final bilingual subtitle stays compact near the bottom of the frame
Max 16 full-width characters per line (Netflix SC spec). Prefer 12–16; if a cue is very short (< 1 s) compress further so reading speed stays ≤ 9 characters/second
Shorten with judgment, not mechanically — remove filler words, repeated subjects, weak interjections, and redundant politeness before dropping key meaning
Match subtitle duration — the line must feel readable within the time on screen; if the cue is very short, compress more aggressively
No trailing punctuation on Chinese cues — drop ending 。, ！, ？; keep mid-sentence ，, 、, ； only when they add clarity
Use full-width Chinese punctuation inside cues (，。！？、；：); use 「」 for inner quotes, not "" or ''
Half-width digits and Latin — numbers, units, product names, and code identifiers stay half-width (GPT-4, 30fps, 2026); only punctuation is full-width
Each cue reads as one complete, self-contained line — every displayed line should be a whole sentence or a short unit of meaning, never a truncated clause, exactly like the bilingual subtitles you see in movies or TV dramas. In practice: don't break after function words (的, 了, 吗, 呢, 吧, 啊); don't split an English phrasal unit across a break; keep modifiers with their heads
Keep terminology consistent — technical terms, names, product names, and recurring phrases should be translated the same way across batches. Maintain an inline glossary if needed
Adapt, don't transliterate — preserve register, tone, and intent over literal word matching; idioms become natural Chinese equivalents
Translate in batches of 10 entries — output each batch in valid SRT format, then continue
Do NOT merge or split entries — maintain original segmentation
Run lint on the merged bilingual SRT to catch Netflix Timed Text Style Guide violations that validate doesn't cover — reading speed (CPS), per-line length, inter-cue gaps, and line count.
Errors (exit code 2): duration out of bounds, CPS over limit, > 2 lines per cue. These break Netflix acceptance and should be fixed before burning.
Warnings (exit 0 unless errors also exist): per-line length, tight gaps. These are recommendations — address if feasible, but they don't block delivery.
When CPS errors fire, the fix is almost always upstream — go back to Step 3 and rewrite the offending Chinese entry to fit the time window. Do not solve CPS by extending the cue past the source's spoken duration.
Convert the bilingual SRT to an ASS file. ASS enables per-line color, font size, and glow effects that are impossible with SRT force_style. Layout rule: subtitles always stay at the bottom. Default stack: ZH on the upper line of the bottom stack, EN on the lower line. The presets are tuned to keep the block readable while reducing overlap risk with lower-screen content.
IMPORTANT — Ask before proceeding. Present the preset table below to the user and ask which style they prefer. Do NOT silently pick a default. If the user has no preference, use clean.
Available presets:
Preset
Look
Best for
netflix
Pure white text, thin black outline, soft drop shadow, no box — modeled on the Netflix Timed Text Style Guide
Professional, broadcast-grade look. Best default for documentaries, interviews, long-form content, and anything that should feel "streaming-platform native". Use with --font "Source Han Sans SC" on Linux / "PingFang SC" on macOS for closest Netflix Sans feel
clean
Yellow text on gray box — golden ZH + light yellow EN, semi-transparent light gray background
Readability safety net for busy or mixed-brightness footage where netflix's outline-only text could get visually lost. The gray box guarantees a readable contrast pad
glow
Yellow ZH + white EN with colored glow — bright yellow ZH + white EN, blurred outer glow, no background box
Entertainment, vlogs, energetic edits. Most eye-catching, but weakest on bright or busy backgrounds
# Netflix-grade default (white + outline + soft shadow), ZH on top
python3 "$SKILL_DIR/srt_utils.py" to_ass \
"${slug}/${slug}_bilingual.srt""${slug}/${slug}_bilingual.ass" \
--preset netflix
# Gray-box fallback for busy backgrounds, EN on top
python3 "$SKILL_DIR/srt_utils.py" to_ass \
"${slug}/${slug}_bilingual.srt""${slug}/${slug}_bilingual.ass" \
--preset clean --top en
# Vibrant glow (B站 entertainment style)
python3 "$SKILL_DIR/srt_utils.py" to_ass \
"${slug}/${slug}_bilingual.srt""${slug}/${slug}_bilingual.ass" \
--preset glow
Custom style file — for full control, provide an external .ass file with your own [V4+ Styles] section. It must contain styles named EN and ZH, or to_ass will fail early with a validation error. You can design styles visually with Aegisub and export.
If language is still misdetected, the audio likely has long silence or non-speech segments — add --vad_filter True to suppress them.
ffmpeg: Font Not Found / CJK Boxes
Pass the correct font via --font in the to_ass step (Step 4.5). The ASS file embeds the font name, so ffmpeg needs it installed at burn time.
Platform
Font
Install
macOS
PingFang SC
pre-installed
Linux
Noto Sans CJK SC
sudo apt install fonts-noto-cjk
Linux (alt)
WenQuanYi Micro Hei
sudo apt install fonts-wqy-microhei
Windows
Microsoft YaHei
pre-installed
Regenerate the ASS file with the correct --font flag, then re-run the burn step.
Privacy & Data Flow
Browser cookies: Step 1 uses yt-dlp --cookies-from-browser chrome to access age-gated or private videos. This reads Chrome cookies locally — no cookies are transmitted beyond YouTube's own servers. To avoid this, export cookies to a file first (see Troubleshooting above).
Transcripts & translation: Step 3 (translate) and Step 6 (publish info) are performed by the AI agent in the conversation. Transcripts are sent to whatever model/service the agent uses (e.g. Claude API). If the video contains sensitive content, use a local model for those steps.
No telemetry: srt_utils.py makes no network requests. All processing (SRT parsing, merging, ASS generation, hardware detection) is fully local.
