Bilingual Subtitles — Development skill for Claude Code

bilingual-video-subtitles

A [Claude Code](https://claude.com/claude-code) / Claude Agent skill that burns beautiful **bilingual subtitles** into a video: one language on top (say Chinese) in a rounded box, the other below it (say English, bold), white text, centered or shifted to clear a corner webcam.

It was built for Chinese over English, but it works for any CJK over Latin pair.

Why it exists

Most subtitle tutorials tell you to use ffmpeg's `subtitles=` or `ass=` filter. That filter needs **libass**, and many ffmpeg builds (including Homebrew's slim `ffmpeg`) ship without it, so the command just fails.

This skill sidesteps that entirely. It renders each caption as a transparent PNG with Pillow, then composites the PNGs onto the video with ffmpeg's `overlay` filter, which every build has. Bonus: you get pixel perfect rounded boxes and true bold CJK that libass cannot easily produce.

No libass, no cloud service, no API keys.

What it handles for you

• Two stacked caption boxes, styled and auto scaled to the video's resolution.
• Smart wrapping: an embedded Latin word (Claude, HTML, Figma, Lissajous) is treated as atomic and never breaks across lines.
• Chinese line head rules (行首禁则): punctuation never starts a line, it hangs on the previous line.
• Auto splitting of any caption that would orphan a single word or run past 3 lines, into shorter timed cues at a clause boundary.
• Fake bold for the CJK line so its weight matches a bold Latin font.

Requirements

• python3 with Pillow (pip install pillow)
• ffmpeg and ffprobe on your PATH
• Optional, only if you start from a video with no transcript: faster-whisper (pip install faster-whisper) for the transcription step. The burn engine itself needs neither this nor any network.

Install as a skill

Clone into your Claude skills folder:

git clone https://github.com/zarazhangrui/bilingual-subtitles.git