mcpField
F
ffmpeg-python-integration-reference

ffmpeg-python-integration-reference

github.com/josiahsiegelDevelopment5976 installsUpdated 19w ago
Repository

About ffmpeg-python-integration-reference

A reference skill for developers building FFmpeg commands and media pipelines in Python. It focuses on types, time units, color formats, and stream mapping to help prevent integration errors.

Key features

  1. 01ffmpeg-python and subprocess usage
  2. 02FFmpeg parameter type and range checks
  3. 03Color and time-unit conversion
  4. 04Audio and subtitle stream mapping
  5. 05Raw-frame pipe handling guidance

Use cases

  1. 01Build FFmpeg video filter commands
  2. 02Debug subtitle color or timing issues
  3. 03Pipe raw frames through NumPy or OpenCV

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill ffmpeg-python-integration-reference

After installing, type/ffmpeg-python-integration-referencein Claude Code to confirm it loaded.

Bundled filesreferences/python-ffmpeg-reference.md

Details

From the project README

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-python stream graphs and filter arguments
  • Python subprocess calls 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

  1. Validate types before passing parameters. fontsize and crf are integers; bitrates are strings with units such as 5M or 192k; FFmpeg expressions are strings.
  2. Quote FFmpeg expressions in Python. Use x="(w-tw)/2", not Python variables named w or tw.
  3. Handle audio explicitly. In ffmpeg-python, a video filter chain usually drops audio unless you map input_file.audio into the output.
  4. Know the color context. FFmpeg drawtext colors are RGB/named strings; OpenCV arrays are BGR; ASS colors are &HAABBGGRR.
  5. Know the time context. FFmpeg filters use seconds; ASS karaoke tags use centiseconds; ASS animation tags use milliseconds.

Quick Reference

FFmpeg / ASS parameterPython typeFormat / rangeCommon failure
-crfint or strH.264/H.265 0-51passing 18.5
-b:v, -b:astr5M, 1000k, 192kraw integer without unit
fontsizeintpractical 12-200passing '24'
fontcolorstrwhite, #FFFFFF, 0xFFFFFFRGB tuple/list
ASS colourstr&HAABBGGRRusing RGB byte order
x, y, alpha, enablestr for expressions'(w-tw)/2, between(t,1,5)unquoted expression

Core Workflow

  1. Probe the input or metadata source so you know width, height, fps, duration, and stream availability.
  2. Choose the integration layer: ffmpeg-python for command graphs, subprocess for full CLI parity and pipes, PyAV for frame-level library access.
  3. Normalize color and time units at the Python boundary.
  4. Validate parameters and ranges before building a command.
  5. Map audio/subtitle streams intentionally.
  6. 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-python examples, subprocess pipe patterns, pitfalls, validation helpers, full working examples.

Related Skills

  • ffmpeg-opencv-integration - OpenCV/NumPy frame pipelines and BGR/RGB handoff
  • ffmpeg-pyav-integration - PyAV frame-level API patterns
  • ffmpeg-captions-subtitles - Subtitle extraction, burn-in, and styling
  • ffmpeg-animation-timing-reference - Timing units, readability, easing, and sync

Comments

Markdown supported