Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill ffmpeg-captions-subtitlesAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
CRITICAL GUIDELINES
Windows File Path Requirements
MANDATORY: Always Use Backslashes on Windows for File Paths
When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).
Documentation Guidelines
NEVER create new documentation files unless explicitly requested by the user.
Quick Reference
| Task | Command |
|---|---|
| Burn SRT | ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4 |
| Burn ASS | ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4 |
| Add soft sub | ffmpeg -i video.mp4 -i subs.srt -c copy -c:s mov_text output.mp4 |
| Extract sub | ffmpeg -i video.mkv -map 0:s:0 output.srt |
| Style subs | -vf "subtitles=s.srt:force_style='FontSize=24,PrimaryColour=&HFFFFFF'" |
| Text overlay | -vf "drawtext=text='Hello':x=10:y=10:fontsize=24:fontcolor=white" |
| Format | Extension | Best For |
|---|---|---|
| SRT | .srt | Simple, universal |
| ASS | .ass | Styled, animated, anime |
| VTT | .vtt | Web/HTML5 video |
When to Use This Skill
Use for subtitle and caption operations:
- Hardcoding (burning) subtitles into video
- Adding soft subtitle tracks to containers
- Extracting subtitles from MKV/MP4
- Styling captions (font, color, position)
- Dynamic text overlays
FFmpeg Captions and Subtitles (2025)
Complete guide to working with subtitles, closed captions, and text overlays using FFmpeg.
Subtitle Format Reference
Supported Formats
| Format | Extension | Features | Use Case |
|---|---|---|---|
| SubRip | .srt | Simple timing + text | Universal, web |
| Advanced SubStation Alpha | .ass/.ssa | Rich styling, positioning, effects | Anime, styled subs |
| WebVTT | .vtt | Web standard, cues, styling | HTML5 video |
| TTML/DFXP | .ttml/.dfxp | Broadcast, accessibility | Streaming services |
| MOV Text | .mov (embedded) | QuickTime native | Apple ecosystem |
| DVB Subtitle | (embedded) | Bitmap-based | European broadcast |
| PGS | .sup | Blu-ray bitmap subtitles | Blu-ray |
| CEA-608/708 | (embedded) | Closed captions | US broadcast, streaming |
Format Characteristics
bash
SRT (SubRip):
- Simple text-based format
- Supports basic HTML tags (<b>, <i>, <u>)
- Widely compatible
- No positioning or advanced styling
ASS/SSA:
- Advanced styling (fonts, colors, outlines)
- Precise positioning anywhere on screen
- Animation and effects support
- Karaoke timing
WebVTT:
- HTML5 standard format
- CSS-like styling
- Cue settings for positioning
- Speaker identificationBurning Subtitles (Hardcoding)
Basic Subtitle Burn-in
bash
# Burn SRT subtitles
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4
# Burn ASS/SSA subtitles (preserves styling)
ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4
# Burn subtitles from MKV container
ffmpeg -i video.mkv -vf "subtitles=video.mkv" output.mp4
# Burn specific subtitle track (index 0)
ffmpeg -i video.mkv -vf "subtitles=video.mkv:si=0" output.mp4
# Burn subtitles with stream index
ffmpeg -i video.mkv -vf "subtitles=video.mkv:stream_index=1" output.mp4Styled Subtitle Burn-in
bash
# Force style (overrides subtitle styling)
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='FontName=Arial,FontSize=24,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,Outline=2,Shadow=1'" \
output.mp4
# Yellow subtitles with black outline
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='FontSize=28,PrimaryColour=&H00FFFF,OutlineColour=&H000000,Outline=3'" \
output.mp4
# Larger font for accessibility
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='FontSize=36,Bold=1'" \
output.mp4ASS Style Parameters
| Parameter | Description | Example |
|---|---|---|
| FontName | Font family | FontName=Arial |
| FontSize | Size in points | FontSize=24 |
| PrimaryColour | Text color (AABBGGRR) | PrimaryColour=&HFFFFFF |
| SecondaryColour | Karaoke color | SecondaryColour=&H00FFFF |
| OutlineColour | Outline/border color | OutlineColour=&H000000 |
| BackColour | Shadow/background color | BackColour=&H80000000 |
| Bold | Bold text (0/1) | Bold=1 |
| Italic | Italic text (0/1) | Italic=1 |
| Underline | Underlined text (0/1) | Underline=1 |
| Outline | Outline width | Outline=2 |
| Shadow | Shadow depth | Shadow=1 |
| Alignment | Position (numpad style) | Alignment=2 |
| MarginL/R/V | Margins in pixels | MarginV=50 |
Color Format (ASS)
text
ASS uses &HAABBGGRR format (Alpha, Blue, Green, Red):
- White: &HFFFFFF or &H00FFFFFF
- Black: &H000000 or &H00000000
- Yellow: &H00FFFF (00-Blue, FF-Green, FF-Red)
- Red: &H0000FF
- Blue: &HFF0000
- 50% transparent black: &H80000000Adding Subtitle Tracks (Soft Subs)
Embed SRT as Track
bash
# Add SRT to MP4 (MOV text)
ffmpeg -i video.mp4 -i subs.srt \
-c copy -c:s mov_text \
output.mp4
# Add SRT to MKV
ffmpeg -i video.mp4 -i subs.srt \
-c copy -c:s srt \
output.mkv
# Add SRT to WebM (WebVTT)
ffmpeg -i video.webm -i subs.srt \
-c copy -c:s webvtt \
output.webmMultiple Subtitle Tracks
bash
# Add multiple languages
ffmpeg -i video.mp4 -i subs_en.srt -i subs_es.srt -i subs_fr.srt \
-map 0:v -map 0:a -map 1 -map 2 -map 3 \
-c copy -c:s mov_text \
-metadata:s:s:0 language=eng -metadata:s:s:0 title="English" \
-metadata:s:s:1 language=spa -metadata:s:s:1 title="Spanish" \
-metadata:s:s:2 language=fra -metadata:s:s:2 title="French" \
output.mp4
# Add ASS subtitles to MKV (preserves styling)
ffmpeg -i video.mp4 -i styled.ass \
-map 0 -map 1 \
-c copy -c:s ass \
output.mkvSet Default Subtitle Track
bash
# Set subtitle as default
ffmpeg -i video.mp4 -i subs.srt \
-c copy -c:s mov_text \
-disposition:s:0 default \
output.mp4
# Set forced subtitles (always display)
ffmpeg -i video.mp4 -i forced.srt \
-c copy -c:s mov_text \
-disposition:s:0 forced \
output.mp4Extracting Subtitles
Extract to External File
bash
# Extract first subtitle track to SRT
ffmpeg -i video.mkv -map 0:s:0 output.srt
# Extract specific subtitle stream
ffmpeg -i video.mkv -map 0:s:1 output.srt
# Extract to ASS format
ffmpeg -i video.mkv -map 0:s:0 output.ass
# Extract to WebVTT
ffmpeg -i video.mkv -map 0:s:0 output.vtt
# Extract all subtitle tracks
ffmpeg -i video.mkv -map 0:s subs_%d.srtList Available Subtitle Tracks
bash
# Show all streams including subtitles
ffprobe -v error -show_entries stream=index,codec_name,codec_type:stream_tags=language,title \
-of csv=p=0 video.mkv
# Show only subtitle streams
ffprobe -v error -select_streams s \
-show_entries stream=index,codec_name:stream_tags=language,title \
-of csv=p=0 video.mkvConvert Subtitle Formats
bash
# SRT to ASS
ffmpeg -i subs.srt subs.ass
# ASS to SRT (loses styling)
ffmpeg -i subs.ass subs.srt
# SRT to WebVTT
ffmpeg -i subs.srt subs.vtt
# WebVTT to SRT
ffmpeg -i subs.vtt subs.srtdrawtext Overlays and Whisper AI Integration
Detailed examples for drawtext overlays (fonts, positioning, escaping, time expressions, boxes, outlines, animated text) and Whisper AI transcription / subtitle generation workflows live in references/drawtext-and-whisper.md. Load that reference when creating burned-in text graphics or generating subtitles from speech.
CEA-608/708 Closed Captions
Extract Closed Captions
bash
# Extract CEA-608 captions from ATSC stream
ffmpeg -f lavfi -i "movie=broadcast.ts[out0+subcc]" -map 0:1 captions.srt
# Extract from video with embedded CC
ffmpeg -i video_with_cc.mp4 \
-filter_complex "[0:v]format=yuv420p[v];[0:v]crop=1:1:0:0[c]" \
-map "[c]" -c:v libx264 -f null - 2>&1 | grep -A 1 "Closed caption"Add CEA-608 Captions
bash
# Embed CEA-608 captions (requires eia608 line)
ffmpeg -i video.mp4 -i captions.scc \
-c:v libx264 -c:a copy \
-vf "movie=captions.scc[captions];[0:v][captions]overlay" \
output.mp4Subtitle Positioning
ASS Alignment Values
text
7 (top-left) 8 (top-center) 9 (top-right)
4 (mid-left) 5 (mid-center) 6 (mid-right)
1 (bottom-left) 2 (bottom-center) 3 (bottom-right)Position Examples
bash
# Top center subtitles
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='Alignment=8,MarginV=20'" \
output.mp4
# Left-aligned subtitles
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='Alignment=1,MarginL=50,MarginV=30'" \
output.mp4
# Right side for speaker identification
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='Alignment=3,MarginR=50'" \
output.mp4Multiple Subtitle Positions
bash
# Two subtitle tracks at different positions
ffmpeg -i video.mp4 \
-vf "[in]subtitles=speaker1.srt:force_style='Alignment=1,MarginL=50'[tmp];\
[tmp]subtitles=speaker2.srt:force_style='Alignment=3,MarginR=50'" \
output.mp4Batch Processing
Burn Subtitles to Multiple Videos
bash
#!/bin/bash
# burn_subs_batch.sh
for video in *.mp4; do
base="${video%.mp4}"
if [ -f "${base}.srt" ]; then
ffmpeg -i "$video" \
-vf "subtitles=${base}.srt:force_style='FontSize=24,Outline=2'" \
-c:a copy \
"output/${base}_subbed.mp4"
fi
doneConvert Subtitle Format Batch
bash
#!/bin/bash
# convert_subs.sh
for srt in *.srt; do
base="${srt%.srt}"
ffmpeg -i "$srt" "${base}.vtt"
doneTroubleshooting
Common Issues
"Unable to find a suitable output format"
bash
# Specify output format explicitly
ffmpeg -i video.mkv -map 0:s:0 -f srt output.srtGarbled characters in subtitles
bash
# Force UTF-8 encoding
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:charenc=UTF-8" \
output.mp4Font not found
bash
# Specify fonts directory
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:fontsdir=/path/to/fonts" \
output.mp4
# List available fonts
fc-list : family | sort | uniqSubtitle timing offset
bash
# Delay subtitles by 2 seconds
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:itsoffset=2" \
output.mp4
# Or use setpts to adjust
ffmpeg -i subs.srt -itsoffset 2 delayed.srtSubtitle not showing on high-res video
bash
# Scale subtitle rendering to video resolution
ffmpeg -i video_4k.mp4 \
-vf "subtitles=subs.srt:force_style='FontSize=48,Outline=3'" \
output.mp4Verification Commands
bash
# Check if subtitles are present
ffprobe -v error -select_streams s -show_entries stream=codec_name -of default=nw=1 video.mp4
# Count subtitle lines
grep -c "^[0-9]" subs.srt
# Validate SRT format
ffmpeg -i subs.srt -f null -Best Practices
Accessibility
- Use high contrast colors (white on dark, yellow on dark)
- Minimum font size of 24pt for standard video
- Include speaker identification for multiple speakers
- Position subtitles to avoid obscuring important visual content
- Keep lines short (42 characters max per line)
- Display duration: minimum 1 second, maximum 7 seconds per caption
Quality
- Use ASS format for styled subtitles (anime, music videos)
- Use SRT for simple dialogue
- Use WebVTT for web delivery
- Preserve original styling when possible
- Test on target devices before distribution
Performance
- Burn subtitles only when necessary (streaming, compatibility)
- Prefer soft subs for archival and flexibility
- Use hardware encoding when burning subtitles to large files
- Process in parallel for batch operations
This guide covers FFmpeg subtitle and caption operations. For text overlays with shapes and graphics, see the shapes-graphics skill.
