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.

Explore the docs · Five-minute proof · 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.

                  review before                    prove after
                       │                                │
input ──> preflight ──> deterministic plan ──> run ──> receipt ──> output
            │                                  │
            └─ fail before mutation            └─ timeout / cancel / cleanup

Install and prove one useful result

Until the first PyPI release is public, install the latest validated source revision in an isolated environment. The full SHA is intentional—no mutable main install is presented as a release:

pipx install git+https://github.com/OthmaneBlial/pyffmpegcore.git@04d1e7051295bbcc4fa137c1214bbf340bf5c4c0
pyffmpegcore doctor
pyffmpegcore smoke-test

doctor identifies the real binaries and indexed capabilities. smoke-test generates synthetic media, performs a complete transform, probes the result, and cleans up—no checkout and no personal media required.

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 occupies the operational layer between intent and evidence. See the factual comparison.

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.

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 project is pre-PyPI until Trusted Publishing succeeds. Source installation is useful for evaluation, but it is not a released artifact. No PyPI badge, download claim, or immutable release claim appears before the public endpoints and cross-platform install gate pass.

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 or one of the labeled good first issues.

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.