Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Python-FFmpeg Integration Reference
Use this skill when Python code is constructing FFmpeg commands, filters, ASS subtitles, or raw-frame pipes and the risk is a type, unit, color, or stream-mapping bug. This SKILL is a lean orchestrator; detailed tables and full code examples live in references/python-ffmpeg-reference.md.
When to Use
ffmpeg-pythonstream graphs and filter arguments- Python
subprocesscalls to FFmpeg drawtext, ASS/SSA, karaoke, and animated caption parameter mapping- RGB/BGR/ASS color conversion bugs
- Seconds vs centiseconds vs milliseconds confusion
- Raw frame pipe I/O with NumPy/OpenCV
- Range/type validation before command execution
Critical Rules
- Validate types before passing parameters.
fontsizeandcrfare integers; bitrates are strings with units such as5Mor192k; FFmpeg expressions are strings. - Quote FFmpeg expressions in Python. Use
x="(w-tw)/2", not Python variables namedwortw. - Handle audio explicitly. In
ffmpeg-python, a video filter chain usually drops audio unless you mapinput_file.audiointo the output. - Know the color context. FFmpeg drawtext colors are RGB/named strings; OpenCV arrays are BGR; ASS colors are
&HAABBGGRR. - Know the time context. FFmpeg filters use seconds; ASS karaoke tags use centiseconds; ASS animation tags use milliseconds.
Quick Reference
| FFmpeg / ASS parameter | Python type | Format / range | Common failure |
|---|---|---|---|
-crf | int or str | H.264/H.265 0-51 | passing 18.5 |
-b:v, -b:a | str | 5M, 1000k, 192k | raw integer without unit |
fontsize | int | practical 12-200 | passing '24' |
fontcolor | str | white, #FFFFFF, 0xFFFFFF | RGB tuple/list |
| ASS colour | str | &HAABBGGRR | using RGB byte order |
x, y, alpha, enable | str for expressions | '(w-tw)/2, between(t,1,5) | unquoted expression |
Core Workflow
- Probe the input or metadata source so you know width, height, fps, duration, and stream availability.
- Choose the integration layer:
ffmpeg-pythonfor command graphs,subprocessfor full CLI parity and pipes, PyAV for frame-level library access. - Normalize color and time units at the Python boundary.
- Validate parameters and ranges before building a command.
- Map audio/subtitle streams intentionally.
- Run on a short sample first; capture stderr for actionable FFmpeg errors.
Reference Map
references/python-ffmpeg-reference.md- Full preserved reference: color conversion functions, ASS style structures, karaoke/animation helpers, drawtext parameter tables,ffmpeg-pythonexamples, subprocess pipe patterns, pitfalls, validation helpers, full working examples.
Related Skills
ffmpeg-opencv-integration- OpenCV/NumPy frame pipelines and BGR/RGB handoffffmpeg-pyav-integration- PyAV frame-level API patternsffmpeg-captions-subtitles- Subtitle extraction, burn-in, and stylingffmpeg-animation-timing-reference- Timing units, readability, easing, and sync
