PyFFmpegCore

The safe, explainable FFmpeg task runner for the terminal, Python, and CI.
Diagnose the machine. Preview the exact plan. Run a maintained workflow. Keep a privacy-redacted receipt.

Current docs · Live documentation site · Five-minute proof · 63.5-second 0.3.0 public run · Task-first recipes · Measured evidence · Security

PyFFmpegCore is for developers and technical creators who want repeatable local media automation without owning a growing pile of fragile FFmpeg strings. It supports Python 3.10–3.14 on Linux, macOS, and Windows; ffmpeg and ffprobe remain explicit system dependencies. Start with pipx install "pyffmpegcore==0.3.1", then run pyffmpegcore smoke-test to produce and verify synthetic media.

Archive: the 0.2.2 install, plan, and result

These frames were rendered from the validated, unedited 0.2.2 terminal recording made on 19 September 2026. It installed the public PyPI wheel on macOS arm64 with Python 3.14.6 and FFmpeg 9.0.1, then used generated media. The images crop the actual terminal screen; they do not add command output.

The planned job selects H.264/AAC and checks the required encoder and muxer before writing. Open the plan image at full resolution or read the full transcript.

The 60-second synthetic input produced a 2.5 MB MP4 and a schema 1.0 receipt. The fixture is a functional demonstration, not a compression or quality claim. Open the result image at full resolution.

Install and prove one useful result

Install the exact public beta from PyPI in an isolated environment:

pipx install "pyffmpegcore==0.3.1"
pyffmpegcore doctor
pyffmpegcore smoke-test --keep-dir pyffmpegcore-demo
pyffmpegcore profile run web/mp4-compatible --input pyffmpegcore-demo/synthetic-input.mp4 --output pyffmpegcore-demo/web.mp4 --explain
pyffmpegcore profile run web/mp4-compatible --input pyffmpegcore-demo/synthetic-input.mp4 --output pyffmpegcore-demo/web.mp4 --receipt pyffmpegcore-demo/web.receipt.json
pyffmpegcore probe --input pyffmpegcore-demo/web.mp4 --json
pyffmpegcore receipt validate pyffmpegcore-demo/web.receipt.json --json

These commands work in Bash, zsh, and PowerShell. They diagnose the installed FFmpeg, generate a synthetic clip, preview the plan without writing the MP4, create a web-compatible H.264/AAC file, inspect its streams, and validate the receipt. No checkout or personal media is required. See the five-minute guide for prerequisites and cleanup.

Archive: the 0.2.2 terminal run

This is a validated terminal recording, not edited sample output. It installs 0.2.2 from public PyPI, runs doctor, creates synthetic media, explains the exact plan, shows structured progress, probes the output, and validates the privacy-redacted receipt.

• Download the asciicast
• Read the accessible transcript
• Open the annotated proof page

Now turn a camera/editor MOV into a conservative web MP4. Inspect first; write only when the plan is acceptable:

pyffmpegcore profile run web/mp4-compatible \
  --input input.mov \
  --output web.mp4 \
  --explain

pyffmpegcore profile run web/mp4-compatible \
  --input input.mov \
  --output web.mp4 \
  --receipt web.receipt.json

A successful run reports output facts—not just process exit zero:

Output: web.mp4
Container: mov,mp4,m4a,3gp,3g2,mj2
Duration: 6.00 seconds
Size: 542.1 KB
Video: h264 640x360
Receipt: web.receipt.json

Those numbers come from the deterministic proof fixture. Your duration and size will reflect your input.

What it owns

Raw FFmpeg remains right when you already own and review the complete command. Graph builders fit arbitrary filter graphs. PyAV fits packet/frame access. PyFFmpegCore packages a maintained path from preflight to a validated receipt. The dated, task-based comparison shows that path on a reproduced VP9-to-MP4 job, including its larger output and links to each neighboring project's own documentation.

Proof, not promises

These runs were made on 2026-08-25 with generated first-party fixtures. The repository publishes the commands, input/output probes, redacted receipts, and receipt checksums.

A 19 September replay shows the size tradeoff: a VP9 WebM grew 78.2% when converted to a more widely playable H.264/AAC MP4. The web profile targets compatibility, not guaranteed compression.

Inspect the complete evidence or read the real-media test methodology, including fixture generation, capability skips, failure contracts, and artifact validation.

Pick an outcome

Ship a portable web video

pyffmpegcore profile run web/mp4-compatible \
  --input source.mov --output web.mp4 --receipt web.receipt.json

Input contract, plan, and verification →

Hit an upload limit

pyffmpegcore compress \
  --input upload.mp4 --output upload-small.mp4 \
  --target-size 24MiB --two-pass --receipt upload.receipt.json

Feasibility, quality floor, and measured proof →

Preserve every track while remuxing

pyffmpegcore convert \
  --input multilingual.mkv --output preserved.mkv \
  --preserve-all-streams --receipt preserved.receipt.json

Stream-selection contract and verification →

Normalize spoken-word audio

pyffmpegcore normalize-audio \
  --input episode.wav --output episode.mp3 \
  --method loudnorm --receipt episode.receipt.json

Loudness targets and listening checks →

More tested recipes cover audio extraction, subtitles, thumbnails, and image batches. Every CLI surface is generated into the command reference.

Build repeatable media pipelines

Compose existing typed workflows in strict JSON or TOML—never raw shell strings—then validate, visualize, dry-run, execute, resume, or cache the DAG:

pyffmpegcore pipeline validate pipelines/web-publish.json
pyffmpegcore pipeline graph pipelines/web-publish.json --format mermaid
pyffmpegcore pipeline run pipelines/web-publish.json \
  --receipt-dir receipts \
  --state pipeline-state.json \
  --events events.jsonl

source ──> web_video ──> poster
   └─────> captions ────┘
              │
              └─ resume state + redacted receipts + JSONL progress

CI users can adopt the digest-pinned GitHub Action. Container users get public linux/amd64 and linux/arm64 images with a non-root runtime, SBOM, provenance, Sigstore attestation, and a scan that blocks fixed high/critical vulnerabilities. The verified digest lives in the container guide.

Python API

The CLI and Python layer share the same typed planner, preflight, runner, and result model:

from pyffmpegcore import WorkflowEngine

engine = WorkflowEngine()
plan = engine.planner.extract_audio("video.mp4", "audio.mp3")
prepared = engine.prepare(plan)

if not prepared.preflight.ok:
    raise RuntimeError(prepared.preflight.render())

result = engine.run(plan).items[0].result
print(result.status, result.elapsed_seconds, result.outputs)

Public types, exceptions, and stability rules are documented in the Python API reference.

The support contract

The compatibility policy separates tested cells from combinations merely expected to work. Preflight can still reject missing encoders, filters, muxers, protocols, streams, writable destinations, or disk requirements before mutation.

Trust is part of the product

• Current CI and exact-artifact matrix
• Compatibility matrix
• Security policy and private reporting
• Command-execution threat model
• Release, provenance, and recovery procedure
• Contribution ladder and test tiers
• Support and triage expectations
• Changelog

The public 0.3.1 beta was built once from a protected SSH-signed tag, tested as the exact wheel on Linux, macOS, and Windows, published without a long-lived PyPI token, and reinstalled from the public index before the matching GitHub Release was created. The workflow produced the same wheel and source archive whose checksums appear on PyPI and the release page.

• PyPI package and files
• Signed GitHub Release, checksums, and artifact report
• Release workflow evidence
• Wheel Trusted Publisher attestation
• Source distribution Trusted Publisher attestation

The earlier 0.3.0 beta release is retained as historical evidence.

Help make media automation less fragile

Good first contributions include a missing capability diagnostic, a real-media fixture edge case, a task-first recipe, or a new compatibility observation. Start with the contribution ladder. The labeled good first issue queue is currently empty; if you find a reproducible gap, open a focused issue with the expected behavior and your platform/FFmpeg version.

If PyFFmpegCore replaces one command string you no longer want to maintain, star the repository so the next person searching for a safer FFmpeg layer can find the proof.