subtitle-burner
Burn an SRT subtitle file into an MP4 via ffmpeg's subtitles filter (libass). Single-pass re-encode of video; audio copied as-is. Uses a verified managed Noto Sans CJK font when available. Used by meta-short-drama as the final subtitling step after merge.
61
73%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
View guide
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./src/opensquilla/skills/bundled/subtitle-burner/SKILL.mdsubtitle-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 render through the managed Noto Sans CJK font. The font directory
is supplied through OPENSQUILLA_MEDIA_FONTS_DIR by the managed toolchain.
An empty/whitespace-only SRT is a valid no-subtitle request: the input video is
probed, copied to the requested output, and reported as
SUBTITLES_SKIPPED: empty without invoking libass.
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 | Noto Sans CJK SC | One libass FontName; comma-separated names are not a fallback chain. |
fonts_dir | no | managed environment | Directory containing subtitle fonts, normally supplied by OpenSquilla. |
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. Empty SRT input first
prints SUBTITLES_SKIPPED: empty. Both paths stage the result in the output
directory, require ffprobe to confirm a decodable positive-duration video
stream, and atomically replace the destination only after validation. Non-zero
exit on any encoding, copy, probe, or output-installation failure; stderr tails
the last 2.5 KB of the encoder log for diagnosis.
Dependencies
- ffmpeg ≥ 5.0 with libass, libx264, AAC, xfade, and zoompan support.
- ffprobe from the matching ffmpeg distribution.
- Noto Sans CJK Regular (managed by OpenSquilla; OFL-1.1).
- 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.
- Repository
- TokenRhythm/opensquilla
- Commit
94ac35e
- Last updated
- First committed
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.