subtitle-burner

Burned-in styled captions for short-form video (TikTok, Instagram Reels, YouTube Shorts — 9:16 vertical).

Note on Original Tool

The original jurczykpawel/subtitle-burner GitHub repo has been renamed and merged into jurczykpawel/reelstack — a full video pipeline app requiring Docker + Postgres + Redis + multiple API keys. That tool is too heavy for caption-only use.

Our implementation achieves the same karaoke-style caption output using two widely available tools: OpenAI Whisper (CLI) + ffmpeg. Neither requires Docker, Postgres, Redis, or API keys.

Stack

• Transcription: whisper CLI (OpenAI Whisper). Detect the install with command -v whisper — the exact path varies by platform and package manager (Homebrew, pip, apt, etc.), so don't hardcode it. If command -v whisper returns nothing, install with pip install -U openai-whisper or brew install openai-whisper.
• Caption burn: ffmpeg with ASS subtitle filter for styled open captions. Any recent ffmpeg (4.x+) supports the subtitles/ass filters used below — no specific version is required.
• Alternative: video-use Whisper transcription for pipeline integration

Short-Form Workflow (TikTok / Reels / Shorts — 9:16)

Step 1: Transcribe to SRT

whisper input.mp4 \
  --model base \
  --output_format srt \
  --output_dir /tmp/captions/ \
  --language en

Output: /tmp/captions/input.srt

For better accuracy on AI/technical content:

whisper input.mp4 --model medium --output_format srt --output_dir /tmp/captions/

Step 2: Burn Captions (short-form style)

Standard short-form (bold white + black outline, bottom-third):

ffmpeg -i input.mp4 \
  -vf "subtitles=/tmp/captions/input.srt:force_style='FontName=Arial,Bold=1,FontSize=18,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,Outline=2,Alignment=2,MarginV=60'" \
  -c:v libx264 -crf 20 -c:a copy \
  output_captioned.mp4

Karaoke-style (word highlight — requires ASS format):

1. Convert SRT to ASS first:

ffmpeg -i /tmp/captions/input.srt /tmp/captions/input.ass

2. Edit the ASS file's [Script Info] style to add karaoke tags (each word highlighted in yellow):

Style: Default,Arial,18,&H00FFFF00,&H00FFFFFF,&H00000000,&H00000000,-1,0,0,0,100,100,0,0,1,2,0,2,10,10,60,0

3. Burn:

ffmpeg -i input.mp4 \
  -vf "ass=/tmp/captions/input.ass" \
  -c:v libx264 -crf 20 -c:a copy \
  output_captioned_karaoke.mp4

Caption Style Standards (Short-Form)

Property	Value
Font	Arial Bold
Font size	18-22 (ASS units, scales to ~6% of frame height)
Text color	White (#FFFFFF)
Outline	Black, 2px
Alignment	Bottom center (Alignment=2)
Margin V	60px from bottom
Max chars/line	42
Max lines	2

Long-Form Workflow (YouTube — 16:9)

Long-form: use Whisper for transcription → export .srt → upload to YouTube as closed captions (do NOT burn in for horizontal video — YouTube's auto-CC is better for SEO).

whisper input.mp4 --model medium --output_format srt --output_dir ./captions/
# Upload ./captions/input.srt to YouTube Studio manually or via API

Integration with the captioning role

The captioning role (general-purpose + /subtitle-burner, /ffmpeg; role file: {agency-root}/agents-archive/generalist-2026-10-06/video-studio/vs-captioning-specialist.md) defaults to this workflow. For short-form:

1. Whisper transcription (base model for speed, medium for quality)
2. Manual correction of proper nouns, brand names, technical terms
3. ffmpeg burn with short-form style above
4. Output: captioned MP4 + source .srt file

When to Use vs. Alternatives

Scenario	Tool	Reason
Short-form vertical 9:16 (TikTok/Reels)	This skill (Whisper + ffmpeg)	Fast, offline, no API cost
YouTube long-form	Whisper → .srt upload	Don't burn in, use YT's CC system
Live video / broadcast	Whisper real-time	Out of scope for this skill
Vietnamese content	video-use + vietnamese-language agent	Specialized pipeline

Follow-Up Needed (operator action)

The ReelStack hosted demo at https://reelstack.techskills.academy includes a karaoke mode. Worth checking once for comparison. No install required — just upload a video.