# kkroening/ffmpeg-python architecture

> Architecture diagram of the GitHub repository kkroening/ffmpeg-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kkroening/ffmpeg-python
- Repository: https://github.com/kkroening/ffmpeg-python

## Overview

##### Project type and purpose
- ffmpeg-python is an open-source, client-side Python library.
- It wraps and generates FFmpeg command‐line invocations, exposing a fluent API to build directed‐acyclic filter graphs.

##### File structure
- Top‐level packaging and config:
- setup.py / setup.cfg / pyproject.toml / requirements.txt / tox.ini / pytest.ini / .github/ci.yml
- Documentation (doc/) and Examples (examples/) show usage and website generation.
- Core package (ffmpeg/):
- _ffmpeg.py          → low‐level FFmpeg executable interface (input/output/run)
- _filters.py         → Python definitions of standard FFmpeg filters
- _probe.py           → FFmpeg “probe” wrapper to inspect media
- _run.py             → orchestration of subprocess invocation
- _utils.py           → argument/dictionary helpers, type coercion
- _view.py            → probably “viewing” CLI arguments or debugging
- nodes.py            → Graph node definitions and helpers
- ffmpeg/tests/       → unit tests driving core behavior

##### README and infer architecture
- Python‐side API builds an in‐memory DAG of streams and filters.
- The DAG is compiled to a sequence of FFmpeg command‐line arguments.
- A subprocess is spawned to call the ffmpeg binary (external dependency).
- The library is extensible: any filter not in _filters.py can be accessed via .filter or .filter_multi_output.

##### Main components
A. Client Code (Users / Examples / Tests)
- Invokes `import ffmpeg`
- Calls API methods: input(), filter(), concat(), output(), run()
B. API Layer (ffmpeg/\_*.py)
- Input/Output abstractions (`_ffmpeg.py`)
- Filter definitions (`_filters.py`)
- Generic filter operator (`.filter`, `.filter_multi_output`)
- DAG builder (`dag.py`, `nodes.py`)
C. Command Compiler
- Traverses the DAG, serializes nodes to FFmpeg command‐line arguments (`.compile()`, `.get_args()`)
D. Subprocess Launcher (`_run.py`)
- Spawns the external ffmpeg executable with the compiled args
- Handles stdout/stderr, progress reporting
E. External FFmpeg Binary
- The actual media‐processing engine
F. Auxiliary Services
- Probe (`_probe.py`) for metadata inspection
- Utils (`_utils.py`) for argument translation
G. Documentation & CI
- doc/ for Sphinx site generation
- .github/ci.yml for continuous integration
H. Packaging & Testing
- setup.py, pyproject.toml for publishing
- pytest.ini, tests/ for automated tests

##### Relationships and data flow
1. User code → calls API Layer → builds in‐memory DAG
2. DAG → compiled by Command Compiler → yields list of CLI tokens
3. Command tokens + ffmpeg binary path → passed to Subprocess Launcher
4. Subprocess → executes ffmpeg → produces media output (file/stdout)
5. Probe module can be used before/after to inspect media (optional side‐channel)
6. Utilities support steps 1–4 (argument mapping, special flags)

##### Architectural patterns and principles
- Fluent API / Builder pattern (chainable operations)
- Graph abstraction (directed acyclic graph of filter nodes)
- Separation of concerns:
- API (user-facing) vs Graph representation vs Execution
- Extensibility via generic filter operator
- External dependency isolation: no bundling of FFmpeg, just calls a subprocess

##### Essential details—don’t omit
- The DAG layer (`dag.py`, `nodes.py`) as its own component.
- The dual nature of filters: predefined vs generic.
- The subprocess interface (`_run.py` + ffmpeg binary).
- How examples/tests drive the API and verify behavior.
- CI pipeline for building docs and running tests.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Artifacts
    subgraph "User Artifacts"
        direction TB
        Examples["Examples"]:::user
        Tests["Tests"]:::user
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        FFmpegPy["_ffmpeg.py"]:::python
        PredefFilters["_filters.py"]:::python
    end

    %% DAG Builder
    subgraph "DAG Builder"
        direction TB
        DAG["dag.py"]:::python
        Nodes["nodes.py"]:::python
    end

    %% Command Compiler
    CommandCompiler["Command Compiler\n(compile(), get_args())"]:::python

    %% Runner
    Runner["_run.py"]:::python

    %% External Binary
    FFmpegBinary["FFmpeg Binary"]:::external

    %% Auxiliary Modules
    subgraph "Auxiliary Modules"
        direction TB
        Probe["_probe.py"]:::python
        Utils["_utils.py"]:::python
        View["_view.py"]:::python
    end

    %% Tooling & Documentation
    subgraph "Tooling & Documentation"
        direction TB
        Doc["doc/"]:::tooling
        CI[".github/workflows/ci.yml"]:::tooling
        Packaging["setup.py\nsetup.cfg\npyproject.toml\nrequirements.txt"]:::tooling
        TestConfig["pytest.ini"]:::tooling
    end

    %% Data Flow
    Examples -->|"import & invoke API"| FFmpegPy
    Tests -->|"import & invoke API"| FFmpegPy
    FFmpegPy -->|"calls filter()/filter_multi_output"| PredefFilters
    FFmpegPy -->|"build DAG"| DAG
    PredefFilters -->|"define filters"| DAG
    DAG -->|"create nodes"| Nodes
    DAG -->|"compile args"| CommandCompiler
    Nodes -->|"get_args()"| CommandCompiler
    CommandCompiler -->|"spawn subprocess"| Runner
    Runner -->|"executes command"| FFmpegBinary
    FFmpegBinary -->|"stdout/stderr"| Runner

    %% Auxiliary interactions
    FFmpegPy -->|"probe metadata (optional)"| Probe
    DAG -->|"use utils"| Utils
    Runner -->|"use utils"| Utils
    FFmpegPy -->|"view args/debug"| View

    %% Tooling interactions
    Doc ---|generates docs for| FFmpegPy
    CI ---|tests & lint| Tests
    CI ---|builds docs| Doc
    Packaging ---|packages| FFmpegPy
    TestConfig ---|configures pytest| Tests

    %% Click Events
    click Examples "https://github.com/kkroening/ffmpeg-python/tree/master/examples/"
    click Tests "https://github.com/kkroening/ffmpeg-python/tree/master/ffmpeg/tests/"
    click FFmpegPy "https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_ffmpeg.py"
    click PredefFilters "https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_filters.py"
    click DAG "https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/dag.py"
    click Nodes "https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/nodes.py"
    click Runner "https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_run.py"
    click Probe "https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_probe.py"
    click Utils "https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_utils.py"
    click View "https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_view.py"
    click Doc "https://github.com/kkroening/ffmpeg-python/tree/master/doc/"
    click CI "https://github.com/kkroening/ffmpeg-python/blob/master/.github/workflows/ci.yml"
    click Packaging "https://github.com/kkroening/ffmpeg-python/blob/master/setup.py"
    click TestConfig "https://github.com/kkroening/ffmpeg-python/blob/master/pytest.ini"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef user fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef tooling fill:#D3D3D3,stroke:#000,stroke-width:1px
```
