skills.rest
opensquilla
opensquillaOFFICIAL
Explore all skills by this author →
WebsiteGitHub

subtitle-burner

Burn SRT subtitles into MP4 videos using ffmpeg's libass subtitles filter.

6.8k|540|Updated May 6, 2026
Search Tags:#subtitles#FFmpeg#SRT#video encoding#MP4#cjk fonts#libass
One-click install
npx skills add https://github.com/opensquilla/opensquilla --skill subtitle-burner
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: subtitle-burner
Source: https://github.com/opensquilla/opensquilla/tree/main/src/opensquilla/skills/bundled/subtitle-burner
Command: npx skills add https://github.com/opensquilla/opensquilla --skill subtitle-burner

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Hardcoding subtitles into video files requires careful ffmpeg filter configuration, font handling for CJK characters, and path escaping that differs across operating systems. This Skill handles the full burn-in pipeline so an SRT file becomes a subtitled MP4 without manual ffmpeg command construction.

Core Features & Use Cases

  • Single-pass subtitle burn-in: Re-encodes video to H.264 with faststart while copying audio untouched, rendering SRT cues through libass with configurable font, size, outline, and margin.
  • CJK font support: Uses a managed Noto Sans CJK font directory so Chinese, Japanese, and Korean subtitles render correctly, with automatic PlayRes probing so font size and margins map to source-video pixels.
  • Safe output handling: Stages output in a temporary file, validates it with ffprobe for a decodable positive-duration stream, and atomically replaces the destination only after validation; empty SRT files are treated as a valid no-subtitle pass-through.
  • Use Case: As the final step of a short-drama pipeline, take the merged final.mp4 and a translated drama.srt, then produce final_subtitled.mp4 with bottom-centered white subtitles ready for publishing.

Quick Start

Burn the subtitles from drama.srt into final.mp4 and save the result as final_subtitled.mp4 using the default Noto Sans CJK font.

Frequently Asked Questions about subtitle-burner

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I burn SRT subtitles into an MP4 with ffmpeg?▼

Use ffmpeg's subtitles filter, which renders SRT cues through libass during a single-pass re-encode. This Skill runs that command for you: video is re-encoded to H.264 with faststart while audio is copied unchanged, and the output path is printed on success.

How to render Chinese or Japanese subtitles in ffmpeg without missing glyphs?▼

Point libass at a font directory containing a pan-CJK font such as Noto Sans CJK via the fontsdir filter option. This Skill uses a managed Noto Sans CJK font directory supplied through the OPENSQUILLA_MEDIA_FONTS_DIR environment variable or the fonts_dir parameter.

Why does the ffmpeg subtitles filter fail on Windows paths?▼

libass is picky about Windows paths: drive-letter colons must be backslash-escaped, forward slashes must be used, and single quotes need escaping. The script applies these escaping rules automatically so callers can pass normal paths.

What happens if the SRT subtitle file is empty?▼

An empty or whitespace-only SRT is treated as a valid no-subtitle request. The input video is probed, copied to the output path, validated with ffprobe, and reported as SUBTITLES_SKIPPED: empty without invoking libass.

Can I change subtitle font size, color, and position when burning subtitles?▼

Yes. The force_style options expose font family, font size, primary and outline colors, outline thickness, alignment, and bottom margin. With play_res set to auto, font size and margin values map directly to source-video pixels.

Related Skills

Explore More Content & Communication Skills→
MagicWifiMoneyMagicWifiMoney

video-subtitles

Generates subtitle files and burns them onto videos for multiple audiences.

Community
Advanced
tpotttpott

add-subtitles

Embed SRT subtitles into WEBM, MP4, or MKV videos using ffmpeg.

Community
Basic
akrindevakrindev

youtube-downloader

Download YouTube videos and playlists with audio, subtitles, and metadata.

Community
Intermediate
JosiahSiegelJosiahSiegel
51

ffmpeg-karaoke-animated-text

Generate karaoke subtitles and animated text effects with FFmpeg.

Community
Advanced