# zmwangx/rust-ffmpeg-sys architecture

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

- Interactive diagram: https://gitdiagram.com/zmwangx/rust-ffmpeg-sys
- Repository: https://github.com/zmwangx/rust-ffmpeg-sys

## Overview

##### Project type and purpose
- This is a Rust “sys” crate that provides low-level FFI bindings to the FFmpeg libraries (in this tree we see only the avutil bindings). It is intended to be used by higher-level crates (e.g., ffmpeg-next) or directly by Rust code that needs raw access to FFmpeg’s C API.

##### File structure
- Top-level files
- Cargo.toml (crate metadata, dependencies, feature-flags for different FFmpeg versions)
- build.rs (build script that does compile-time detection of installed FFmpeg versions, header availability, and sets cfg flags)
- channel_layout_fixed.h (a small C header shipped with the crate—used by bindgen or included by build.rs)
- README.md and .github/workflows/build.yml (CI configuration)
- src/
- lib.rs (the crate root: re-exports modules, declares extern “C” blocks, feature flags)
- avutil/ (Rust modules wrapping avutil API)
– error.rs, macros.rs, pixfmt.rs, rational.rs, util.rs, mod.rs

##### README for additional insights
- The crate tracks FFmpeg major/minor versions with feature flags (`ffmpeg_4_2`, `ffmpeg_4_3`, etc.).
- It exposes version and feature detection flags derived from FFmpeg’s C headers (`avcodec_version_greater_than_…`, `ff_api_vaapi`, etc.).
- This is purely a low-level binding crate; it does not implement encoding/decoding logic itself.

##### Main components
a. Rust crate code
– Modules tree under src/avutil (error, util, pixfmt, rational, macros)
– lib.rs connecting them and declaring `extern "C"` blocks
b. Build system
– build.rs script invoking pkg-config or custom C header detection
– channel_layout_fixed.h included at build time
– Cargo feature flags generated by build.rs (e.g. `ffmpeg_4_2`)
c. External dependencies
– FFmpeg C libraries on the host system (`libavutil.so/dylib/…`)
– pkg-config or environment variables (PKG_CONFIG_PATH)
d. Consumers
– Higher-level Rust crates (e.g. ffmpeg-next) or application crates linking against this sys crate

##### Relationships and interactions
- At build time:
- build.rs ↔ pkg-config (or manual header lookup)
- build.rs reads `channel_layout_fixed.h` and the system’s FFmpeg headers
- build.rs emits cfg flags and Cargo instructions (`println!("cargo:rustc-link-lib=avutil")`)
- At compile time:
- rustc compiles src/lib.rs and submodules under the build-time cfg flags
- At link time:
- The final rlib/dylib is linked to the system’s FFmpeg C library
- At runtime:
- Calls from Rust FFI wrappers → native FFmpeg C API

##### Architectural patterns and design principles
- Separation of concerns: Build-time detection logic in build.rs vs. runtime FFI definitions in src/
- Feature-flag driven code paths: using Cargo cfgs to include/exclude deprecated API
- Modularization by FFmpeg sub-library (here: avutil)

##### Final advice
- Be very detailed: include every module group, all major paths (build→compile→link→runtime).
- Don’t overthink: break the system into as many distinct components as makes sense (build script vs. Rust code vs. external).
- Essence: how the crate turns system headers & libraries into Rust FFI bindings for consumer crates.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-time Configuration
    subgraph "Build-time Configuration"
        BS["build.rs & header detection"]:::buildTime
        CL["channel_layout_fixed.h"]:::buildTime
        subgraph "Crate Metadata & CI Configuration"
            CT["Cargo.toml"]:::buildTime
            RD["README.md"]:::buildTime
            CI[".github/workflows/build.yml"]:::buildTime
        end
        pkg["pkg-config / C headers"]:::external
    end

    %% Compile-time Bindings
    subgraph "Compile-time (Rust FFI Bindings)"
        LIB["src/lib.rs"]:::compileTime
        subgraph "avutil modules"
            MOD["src/avutil/mod.rs"]:::compileTime
            ERR["src/avutil/error.rs"]:::compileTime
            MAC["src/avutil/macros.rs"]:::compileTime
            PIX["src/avutil/pixfmt.rs"]:::compileTime
            RAT["src/avutil/rational.rs"]:::compileTime
            UTIL["src/avutil/util.rs"]:::compileTime
        end
    end

    %% Link-time
    subgraph "Link-time"
        rustc["rustc linking"]:::compileTime
        SYS["System FFmpeg libraries\n(libavutil.so, headers)"]:::external
    end

    %% Runtime
    subgraph "Runtime"
        RUN["FFI Callers (Rust code)"]:::runtime
        CAPI["FFmpeg C API"]:::external
    end

    %% Consumers
    subgraph "Consumers"
        HL["High-level Rust crates\n(ffmpeg-next, user code)"]:::consumers
    end

    %% Connections
    BS -->|"includes header"| CL
    BS -->|"invoke pkg-config"| pkg
    BS -->|"emit cfg & link flags"| LIB
    BS -->|"println cargo:rustc-link-lib=avutil"| rustc

    LIB -->|"includes modules"| MOD
    MOD --> ERR
    MOD --> MAC
    MOD --> PIX
    MOD --> RAT
    MOD --> UTIL

    rustc -->|"link to avutil"| SYS

    HL -->|"invoke FFI bindings"| RUN
    RUN -->|"FFI call"| CAPI

    %% Click Events
    click BS "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/build.rs"
    click CL "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/channel_layout_fixed.h"
    click CT "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/Cargo.toml"
    click RD "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/README.md"
    click CI "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/.github/workflows/build.yml"
    click LIB "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/src/lib.rs"
    click MOD "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/src/avutil/mod.rs"
    click ERR "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/src/avutil/error.rs"
    click MAC "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/src/avutil/macros.rs"
    click PIX "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/src/avutil/pixfmt.rs"
    click RAT "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/src/avutil/rational.rs"
    click UTIL "https://github.com/zmwangx/rust-ffmpeg-sys/blob/master/src/avutil/util.rs"

    %% Styles
    classDef buildTime fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef compileTime fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef runtime fill:#e5ffe5,stroke:#333,stroke-width:1px
    classDef consumers fill:#e6e6e6,stroke:#333,stroke-width:1px
```
