Subtitle Burner
Documentssubtitle-burnerSubtitle Burner is an Agent Skill for documents published in the opensquilla/opensquilla repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Burn an SRT subtitle file into an MP4 via ffmpeg's subtitles filter (libass). Single-pass re-encode of video; audio copied as-is. CJK-friendly font fallback chain (Microsoft YaHei → SimHei → Arial Unicode MS → Arial). Used by meta-short-drama as the final subtitling step after merge.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/opensquilla/opensquilla/blob/HEAD/src/opensquilla/skills/bundled/subtitle-burner/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/subtitle-burner, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
subtitle-burner
Burns an SRT subtitle stream into an MP4. The video is re-encoded (H.264 + faststart), the audio is copied untouched. libass renders the text per ASS-style override flags, so Chinese / Japanese / Korean characters survive when the host has any of the listed fallback fonts installed (on Windows, Microsoft YaHei and SimHei ship with the OS).
Inputs (with:)
| key | required | default | notes |
|---|---|---|---|
input | yes | — | Source MP4 path. |
subtitles | yes | — | .srt path (UTF-8). |
output | yes | — | Output MP4 path. Parent dir created if missing. |
font | no | Microsoft YaHei,SimHei,Arial Unicode MS,Arial | libass FontName fallback chain. First wins. |
font_size | no | 42 | Font size. When play_res=auto this is in source-video pixels. |
margin_v | no | 80 | Bottom margin in source-video pixels (because play_res=auto sets PlayRes to the input W×H). |
play_res | no | auto | auto probes the input MP4 for resolution; or pass WxH like 720x1280. Setting this makes FontSize/MarginV act in source pixels rather than libass's 384×288 default. |
crf | no | 20 | x264 CRF (0-51, lower = better quality). |
preset | no | medium | x264 preset. |
Output
Prints the absolute path of the subtitled MP4 on stdout. Non-zero exit on any ffmpeg failure; stderr tails the last 2.5 KB of the encoder log for diagnosis.
Dependencies
- ffmpeg ≥ 5.0 (libass support is standard in any modern build).
- Python 3.8+.
The script auto-locates ffmpeg via PATH; on Windows it falls back to
the winget Gyan.FFmpeg / scoop / chocolatey install paths if PATH
inheritance failed (matches the resolution logic in video-merger and
video-still-animator).
Path-escaping notes
ffmpeg's subtitles= filter is picky on Windows:
- Drive-letter colons (
C:/…) must be backslash-escaped (C\:/…). - The path uses forward slashes regardless of host OS.
- Single quotes inside the path get backslash-escaped.
The script applies these rules so callers don't have to.
Style chain
The force_style defaults render white text with a 2-px black outline
on a transparent background (BorderStyle=3), bottom-centred,
80 px above the frame edge. Override any of the --* flags via
with.* if you want a different look.