WAIT — Stale — last commit 2y ago

• 21+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits
• ⚠ Scorecard: marked unmaintained (0/10)
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

ffmpeg-python is a Python bindings library for FFmpeg that specializes in complex filter graph support. It abstracts away FFmpeg's gnarly command-line syntax (like -filter_complex chains) and lets you build signal graphs programmatically in Python, handling arbitrary directed-acyclic filter graphs with fluent or functional APIs. Single-module structure: core logic likely in ffmpeg/ package (inferred from import import ffmpeg in examples), with examples/ containing runnable scripts (facetime.py, get_video_thumbnail.py, notebooks), and doc/ containing Sphinx documentation and generated HTML. Tests are not visible in the top 60 files, suggesting they may be in a tests/ directory or embedded.

Video engineers, data scientists, and developers building video processing pipelines who need to compose complex FFmpeg filters without wrestling with shell command syntax. Users range from those doing simple operations (hflip, trim) to building multi-input signal graphs with overlays, concatenation, and effects.

Actively maintained but not heavily staffed. The repo shows CI/CD via GitHub Actions (.github/workflows/ci.yml) and documentation infrastructure (doc/html, Sphinx setup in doc/src/). Commit recency and test coverage are not visible in the file listing, so direct inspection is needed; however, the project has complex filter support and examples suggesting production-readiness. Single-maintainer risk is present (kkroening is the primary owner).

Moderate risks: dependency on FFmpeg binary availability on the system (not bundled), Python-only wrappers can lag FFmpeg releases, and single-maintainer maintenance model. The dependency list (gevent, graphviz, google-cloud-speech, jupyter, Pillow, tqdm) suggests heavy use of external tools—graphviz for visualization and gevent for async—which adds surface area. No lock file visible in listing, so pinning risks exist.

Unable to determine from file listing alone—no CHANGELOG, recent commit messages, or open PR list is visible. The presence of jupyter notebooks (examples/ffmpeg-numpy.ipynb) and demo GIFs suggests recent documentation work, but activity level requires GitHub repo inspection.

git clone https://github.com/kkroening/ffmpeg-python.git && cd ffmpeg-python && pip install -e . (installs from local setup.py in editable mode, allowing exploration). Requires FFmpeg binary installed separately (brew install ffmpeg on macOS, apt-get install ffmpeg on Linux, or download from ffmpeg.org on Windows).

Daily commands: No traditional 'server' here—it's a library. To run examples: python examples/get_video_thumbnail.py (requires input video file), or explore interactively in Jupyter: jupyter notebook examples/ffmpeg-numpy.ipynb. All operations ultimately call ffmpeg.run(stream) which invokes the ffmpeg binary.

• ffmpeg/__init__.py — Main entry point that exposes the public API (input, output, run, filter functions) that all users interact with.
• ffmpeg/_ffmpeg.py — Core stream and node abstractions that define how filters chain together and represent the computational graph.
• ffmpeg/_run.py — Execution engine that compiles the filter graph into FFmpeg command-line arguments and spawns the subprocess.
• ffmpeg/nodes.py — Node and stream class definitions that form the graph data structure for complex filter operations.
• ffmpeg/_filters.py — Auto-generated or manually curated filter definitions that map FFmpeg filters to Python callable methods.
• ffmpeg/_probe.py — Integration with ffprobe for inspecting media files and extracting stream metadata without execution.
• ffmpeg/dag.py — Directed acyclic graph utilities for topological sorting and validation of filter chains before execution.

• Stream (_ffmpeg.py) (Python metaclass, getattr) — Chainable filter interface; holds references to upstream nodes; provides fluent method syntax
  • Failure mode: Invalid filter names or parameters cause AttributeError or later CLI execution errors
• Node Graph (nodes.py, dag.py) (Graph data structure, cycle detection) — Represents filter chain as DAG; tracks input/output relationships; enables topological sorting
  • Failure mode: Circular dependencies or disconnected nodes cause ValueError during compile; infinite loops in DAG traversal
• Run Engine (_run.py) (subprocess.Popen, shell escaping, argument serialization) — Converts DAG to ffmpeg CLI string; spawns subprocess; handles I/O and exit codes
  • Failure mode: Shell injection vulnerabilities if user input not escaped; subprocess crashes if FFmpeg not installed; output buffering deadlocks on large streams
• Filter Catalog (_filters.py) (Conditional imports, dynamic function generation) — Defines or auto-generates FFmpeg filter function signatures
  • Failure mode: Outdated filter definitions don't match running FFmpeg version; missing filters silently fail at runtime
• Probe (_probe.py) (subprocess, json, regex parsing) — Calls ffprobe and parses JSON output for media inspection
  • Failure mode: JSON parsing fails on malformed ffprobe output; missing required fields cause KeyError; network URLs timeout

• User code → Stream API (ffmpeg.input, .filter, .output) — Imperative or fluent method calls to define filter graph nodes and edges
• Stream API → Node Graph (nodes.py) — Each method call creates or mutates nodes and establishes parent-child relationships
• Node Graph → DAG Compiler (dag.py) — ffmpeg.run() triggers conversion of node tree to topologically sorted list
• DAG Compiler → Run Engine (_run.py) — Sorted nodes passed to command-line argument generator (build_cmd)
• Run Engine → FFmpeg subprocess — Generated CLI string + input file paths passed to ffmpeg binary via subprocess.Popen
• FFmpeg subprocess → Output file / stdout streams —

Add a new FFmpeg filter wrapper

1. Define the filter function in ffmpeg/_filters.py with parameter names matching FFmpeg's filter syntax (ffmpeg/_filters.py)
2. The filter is auto-registered as a method on Stream class via getattr in ffmpeg/_ffmpeg.py (ffmpeg/_ffmpeg.py)
3. Test by chaining the filter in a test case: stream.filter_name(param=value).output(...) (ffmpeg/tests/test_ffmpeg.py)

Build a complex multi-stream filter graph

1. Create input streams using ffmpeg.input() for each source media file (ffmpeg/__init__.py)
2. Chain filters on individual streams and use node-level operations to merge streams (e.g., overlay, concat) (ffmpeg/_ffmpeg.py)
3. Create output stream(s) using ffmpeg.output() on the merged stream (ffmpeg/__init__.py)
4. Call ffmpeg.run(stream) which compiles the DAG to CLI args in ffmpeg/_run.py and executes (ffmpeg/_run.py)

Inspect media and conditionally apply filters

1. Use ffmpeg.probe(filename) from ffmpeg/_probe.py to extract metadata (resolution, codecs, duration) (ffmpeg/_probe.py)
2. Parse the probe output dictionary to check stream properties (ffmpeg/_probe.py)
3. Conditionally chain filters based on probe results before calling ffmpeg.run() (ffmpeg/__init__.py)

• Python subprocess — Enables control of external FFmpeg process lifecycle; allows streaming output and progress monitoring
• Directed Acyclic Graph (DAG) — Models complex multi-stream filter chains; enables topological sorting to generate correct ffmpeg CLI argument order
• Dynamic method binding (getattr) — Allows any FFmpeg filter to be called as a stream method without hardcoding; reduces boilerplate and keeps API in sync with FFmpeg
• ffprobe JSON integration — Non-destructive metadata inspection; enables conditional filter logic based on stream properties without transcoding

• Separate filter compilation step (graph → CLI args) rather than direct FFmpeg C API binding

  • Why: Simplifies installation (no compilation, works across OS); users can customize args; easier to debug
  • Consequence: One-way communication; harder to stream interactive feedback; relies on ffmpeg CLI stability

• Lazy node evaluation (nodes created but not executed until .run() called)

  • Why: Allows inspection and modification of graph before execution; enables visualization
  • Consequence: Errors in filter syntax only caught at execution time; harder to provide IDE autocomplete

• Single-threaded subprocess execution by default

  • Why: Simplicity; avoids concurrency bugs and resource contention
  • Consequence: Multiple concurrent transcodes require manual threading/multiprocessing; no built-in parallelization

• Does not provide real-time interactive control of running FFmpeg processes (e.g., dynamic filter parameter updates)
• Does not wrap the FFmpeg C API directly; relies on CLI invocation only
• Does not handle authentication or remote media sources beyond what FFmpeg's URL protocols support
• Does not manage subtitle encoding, metadata tagging, or advanced container options beyond filter graphs

FFmpeg binary must be installed on the system separately (not bundled in pip install); library only provides Python bindings. Stream output format and codec selection are implicit and depend on FFmpeg's defaults—custom codec/preset tuning requires knowledge of FFmpeg flags. Complex filter graphs with many inputs can become memory/CPU-intensive during compilation phase. Synchronization issues can occur with asynchronous gevent usage in examples. The graphviz dependency is optional but required for filter graph visualization features.

• Directed Acyclic Graph (DAG) filter chains — ffmpeg-python's core strength is representing complex FFmpeg filter graphs as DAGs; understanding how nodes (inputs, filters, outputs) and edges form a graph helps you design and debug multi-stage pipelines.
• FFmpeg filter_complex syntax — The abstraction ffmpeg-python solves is reducing FFmpeg's cryptic -filter_complex '[0]trim=...[v0];[v0][v1]concat=...' syntax to Python; learning what filter_complex does under the hood helps you understand what the library generates.
• Fluent Interface / Method Chaining — ffmpeg-python supports both functional (ffmpeg.hflip(stream)) and fluent (stream.hflip()) APIs; understanding fluent patterns helps you write readable, composable code.
• Process subprocess communication — ffmpeg-python ultimately shells out to the FFmpeg binary via Python's subprocess module; understanding stdin/stdout/stderr handling and piping is essential for debugging and capturing output.
• Signal flow and media streams — The library abstracts video/audio signals as Stream objects; understanding signal flow (input → filter → filter → output) is fundamental to composing non-trivial media processing graphs.
• Codec and container formats (MP4, PNG, etc.) — ffmpeg-python lets you specify output files but often delegates codec selection to FFmpeg defaults; knowing basic codec/container pairs (H.264 in MP4, PNG for images) helps avoid silent failures.
• Lazy evaluation and expression trees — ffmpeg-python likely builds an expression tree of filters without immediately invoking FFmpeg; only when run() is called does the tree compile to command-line arguments. Understanding lazy evaluation prevents confusion about when operations actually execute.

• fluent-ffmpeg/node-fluent-ffmpeg — JavaScript equivalent providing similar fluent filter graph API for Node.js; shows cross-language pattern for wrapping FFmpeg.
• imageio/imageio-ffmpeg — Python library bundling FFmpeg binaries (solving the 'separate FFmpeg install' problem) and offering simpler I/O; complementary to ffmpeg-python for users wanting batteries-included.
• kkroening/ffmpeg-python-examples — Dedicated examples repo (if it exists) or related work by the same maintainer showing real-world use cases.
• jiaaro/pydub — High-level audio processing in Python using FFmpeg under the hood; shows a different (audio-focused) abstraction over the same underlying tool.
• tornadoweb/tornado — Not directly related but gevent and async patterns used in examples suggest asynchronous I/O patterns—Tornado is an alternative async framework context.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for ffmpeg/_filters.py

The repo lacks visible test files for the filter generation system, which is a core feature advertised in the README ('complex filter support'). The _filters.py module dynamically generates filter methods but has no corresponding test coverage. This is critical since filter composition is the main differentiator of this library.

• [ ] Create tests/test_filters.py with unit tests for common filters (hflip, vflip, scale, etc.)
• [ ] Add tests for filter chaining and complex graph construction
• [ ] Test filter parameter validation and edge cases
• [ ] Add tests to CI workflow (.github/workflows/ci.yml) to run pytest on test suite

Add type hints and mypy validation to core modules

The codebase (ffmpeg/init.py, ffmpeg/_ffmpeg.py, ffmpeg/_run.py) lacks type annotations, making it harder for users and contributors to understand the API contracts. Adding type hints would improve IDE support, catch bugs early, and serve as living documentation for the complex filter graph API.

• [ ] Add type hints to ffmpeg/_ffmpeg.py Stream class methods and return types
• [ ] Add type hints to ffmpeg/_run.py run() function signature
• [ ] Add type hints to ffmpeg/_probe.py probe() function signature
• [ ] Integrate mypy into CI workflow (.github/workflows/ci.yml) with strict mode

Create integration tests for examples directory with CI automation

The examples/ directory contains practical use cases (get_video_thumbnail.py, video_info.py, split_silence.py) but no automated tests verify they still work. This creates silent breakage risk. Adding integration tests with a small sample video would catch regressions in both the library and examples.

• [ ] Create tests/test_examples.py with integration tests for each example script
• [ ] Add a small test video file (examples/test_input.mp4) to repo or download during CI
• [ ] Test video_info.py, get_video_thumbnail.py, and show_progress.py with real video input
• [ ] Add integration test job to .github/workflows/ci.yml that runs before release

• Add unit tests for examples/get_video_thumbnail.py and examples/facetime.py—check if test/ directory exists and add pytest-based tests covering basic input/filter/output patterns with mock FFmpeg calls.
• Create a beginner-friendly Jupyter notebook in examples/ that walks through 5 common operations (trim, concat, overlay, hflip, scale) with inline visualizations using graphviz, building on ffmpeg-numpy.ipynb structure.
• Audit and document all required environment variables and FFmpeg minimum version in README.md and doc/src/index.rst; add a setup-check script (examples/check_ffmpeg_setup.py) that validates FFmpeg installation and prints version.

The ffmpeg-python library has moderate security concerns, primarily around command injection risks, path traversal vulnerabilities, and uncontrolled subprocess execution. The main attack surface is the construction and execution of FFmpeg commands from user-supplied inputs without apparent comprehensive validation. While the library is not inherently malicious, applications using it must implement strict input validation and sanitization to prevent exploitation. Dependency management also lacks version pinning, which could allow installation of vulnerable package versions. The lack of resource limits on FFmpeg execution could enable denial of service attacks.

• High · Command Injection Risk in FFmpeg Execution — ffmpeg/_run.py, ffmpeg/_ffmpeg.py. The ffmpeg-python library executes FFmpeg commands through subprocess calls. The _run.py module likely constructs shell commands from user-provided input (file paths, filter arguments). Improper sanitization could allow arbitrary command execution if user input is not properly escaped, especially when constructing complex filter graphs. Fix: Ensure all subprocess calls use argument lists (not shell=True) and validate/sanitize all user inputs. Use shlex.quote() for any dynamic path construction. Implement whitelist validation for filter parameters.
• Medium · Unsafe Deserialization Risk — ffmpeg/_probe.py. The _probe.py module likely uses json.load() or similar to parse FFmpeg probe output. While JSON is safer than pickle, untrusted FFmpeg probe data could potentially be exploited if not properly validated, especially if the library processes probes from untrusted sources. Fix: Validate and sanitize all output from external FFmpeg commands. Implement schema validation for probe output. Consider using strict JSON parsing with type checking.
• Medium · Potential Path Traversal Vulnerability — ffmpeg/_ffmpeg.py, ffmpeg/_run.py. File paths provided as input/output arguments are passed directly to FFmpeg without apparent validation. An attacker could use path traversal sequences (e.g., '../../../etc/passwd') or absolute paths to read/write arbitrary files on the system. Fix: Implement strict path validation: use os.path.abspath() and verify paths are within expected directories. Reject relative paths with '..'. Use pathlib.Path for safer path handling.
• Medium · Uncontrolled External Process Execution — ffmpeg/_run.py. The library executes arbitrary FFmpeg commands which could consume excessive system resources (CPU, memory, disk I/O), leading to denial of service. No apparent timeout or resource limits are enforced. Fix: Implement configurable timeouts on subprocess execution. Add resource limits (memory, CPU time) via subprocess timeout and system-level limits. Consider implementing request queuing.
• Low · Potential Information Disclosure via Error Messages — ffmpeg/_run.py. FFmpeg error output may contain sensitive information such as full file paths, system information, or internal error details. These are likely exposed to users without filtering. Fix: Filter and sanitize error messages before exposing them to users. Log detailed errors internally but return generic messages to API consumers.
• Low · Missing Input Validation for Filter Parameters — ffmpeg/_filters.py. Complex filter graphs constructed from user input in _filters.py may not properly validate filter parameters, potentially allowing injection of malicious filter arguments. Fix: Implement parameter validation for all filter arguments. Maintain a whitelist of allowed filters and parameters. Validate parameter types and ranges.
• Low · Dependency Vulnerabilities - Outdated Package Versions — requirements.txt, setup.py. Dependencies like Pillow, graphviz, and jupyter may have known vulnerabilities if pinned to older versions. The requirements.txt does not show version pinning, risking installation of vulnerable versions. Fix: Pin all dependencies to specific tested versions. Regularly update and audit dependencies using tools like pip-audit, safety, or Dependabot. Use a lock file (poetry.lock, Pipfile.lock).

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kkroening/ffmpeg-python shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kkroening/ffmpeg-python repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kkroening/ffmpeg-python.

What it runs against: a local clone of kkroening/ffmpeg-python — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kkroening/ffmpeg-python | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 679 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kkroening/ffmpeg-python. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kkroening/ffmpeg-python.git
#   cd ffmpeg-python
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kkroening/ffmpeg-python and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kkroening/ffmpeg-python(\\.git)?\\b" \\
  && ok "origin remote is kkroening/ffmpeg-python" \\
  || miss "origin remote is not kkroening/ffmpeg-python (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "ffmpeg/__init__.py" \\
  && ok "ffmpeg/__init__.py" \\
  || miss "missing critical file: ffmpeg/__init__.py"
test -f "ffmpeg/_ffmpeg.py" \\
  && ok "ffmpeg/_ffmpeg.py" \\
  || miss "missing critical file: ffmpeg/_ffmpeg.py"
test -f "ffmpeg/_run.py" \\
  && ok "ffmpeg/_run.py" \\
  || miss "missing critical file: ffmpeg/_run.py"
test -f "ffmpeg/nodes.py" \\
  && ok "ffmpeg/nodes.py" \\
  || miss "missing critical file: ffmpeg/nodes.py"
test -f "ffmpeg/_filters.py" \\
  && ok "ffmpeg/_filters.py" \\
  || miss "missing critical file: ffmpeg/_filters.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 679 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~649d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kkroening/ffmpeg-python"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.