# lieff/minimp4 architecture

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

- Interactive diagram: https://gitdiagram.com/lieff/minimp4
- Repository: https://github.com/lieff/minimp4

## Overview

##### Project type and purpose
- This is a small, embeddable C library (“minimp4”) providing MP4 muxing and demuxing functionality.
- It is intended to be #included or linked directly into consumer applications (e.g., media servers, streaming clients, test harnesses).

##### File structure
- Top-level files:
- minimp4.h – the entire public API and implementation (header-only library).
- minimp4_test.c – a small CLI/test harness exercising the API.
- scripts/ – build and test automation for x86 and ARM.
- vectors/ – sample input/output MP4 streams for regression tests.
- .travis.yml – CI build definition.
- No separate “src” or “lib” directories—everything lives at the root (header plus test).
- The library is header-only for maximum embeddability; tests and build scripts surround it.

##### README for additional insights
- Describes three mux modes: default, sequential, and fragmented (fMP4).
- Contains images illustrating byte layout and seek requirements for each mode.
- Mentions bindings (e.g., Rust via minimp4.rs), demonstrating intended extensibility/integration points.

a. Main components
- Consumer Application – your C/Rust/other host that “#include <minimp4.h>” or links against it.
- minimp4 Library – the header-only C implementation, divided internally into modules:
– Mux Manager (switching between default, sequential, fragmented modes)
- Test Harness – minimp4_test.c driving the library using test vectors.
- Sample Vectors – reference .264 and .mp4 files used to validate mux/demux.
- Build & CI – shell scripts and .travis.yml automating builds on ARM/x86 and running tests.
b. Relationships & data flow
1. Consumer App calls minimp4 API →
5. Parsed frames/tracks are returned to Consumer App.
Meanwhile, Test Harness reads vectors → feeds data into demux paths → compares outputs → reports to CI.
c. Architectural patterns & principles
- Header-only C for maximal portability.
- Single-file implementation to simplify embedding.
- Modular separation of parsing vs. writing vs. mode logic.
- Automated cross-platform builds and regression tests to ensure correctness.
d. Key technologies/frameworks
- Language: ISO C99 (header-only style).
- CI: Travis CI (.travis.yml).
- Build scripts: Bash for ARM / x86.
- Test vectors: raw H.264 streams and reference MP4s.

##### Capturing essential elements
- Every module in minimp4.h is represented (parsing, writing, mode control).
- Build scripts invoking the compiler across two targets and registering with Travis CI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Public API Boundary
    subgraph "Public API Boundary"
        direction TB
        API["minimp4.h<br/>(Public API)"]:::public
    end

    %% Internal Modules
    subgraph "Internal Modules"
        direction TB
        Parser["Box Parser"]:::internal
        Mux["Mux Manager"]:::internal
        Writer["Box Writer"]:::internal
    end

    %% Consumer Applications
    subgraph "Consumer Applications"
        direction TB
        CApp["C Application"]:::external
        Rust["Rust Binding"]:::external
    end

    %% Data Flow for Production
    CApp -->|"#include & calls API"| API
    Rust -->|"FFI calls API"| API
    API -->|"demux input"| Parser
    Parser -->|"return frames/tracks"| API
    API -->|"mux frames"| Mux
    Mux -->|"assemble boxes"| Writer
    Writer -->|"output MP4 stream"| CApp

    %% Test & CI Tools
    subgraph "Test & Dev Tooling"
        direction TB
        TestHarness["minimp4_test.c<br/>(Test Harness)"]:::tooling
        BuildARM["build_arm.sh"]:::tooling
        BuildX86["build_x86.sh"]:::tooling
        TestScript["test.sh"]:::tooling
        CI["Travis CI (.travis.yml)"]:::ci
    end

    %% Sample Vectors
    Vectors["Sample Vectors"]:::data

    %% Test Flow
    Vectors -->|"feed input"| TestHarness
    TestHarness -->|"compare outputs"| Vectors
    TestHarness -->|"run tests"| CI
    BuildARM -->|"compile & test"| CI
    BuildX86 -->|"compile & test"| CI
    TestScript -->|"invoke harness"| TestHarness

    %% Documentation & Images
    subgraph "Docs & Assets"
        direction TB
        README["README.md"]:::docs
        LICENSE["LICENSE"]:::docs
        Images["images/"]:::docs
    end

    README --> API
    Images --> README

    %% Click Events
    click API "https://github.com/lieff/minimp4/blob/master/minimp4.h"
    click TestHarness "https://github.com/lieff/minimp4/blob/master/minimp4_test.c"
    click CI "https://github.com/lieff/minimp4/blob/master/.travis.yml"
    click BuildARM "https://github.com/lieff/minimp4/blob/master/scripts/build_arm.sh"
    click BuildX86 "https://github.com/lieff/minimp4/blob/master/scripts/build_x86.sh"
    click TestScript "https://github.com/lieff/minimp4/blob/master/scripts/test.sh"
    click Vectors "https://github.com/lieff/minimp4/blob/master/vectors/foreman.264"
    click README "https://github.com/lieff/minimp4/blob/master/README.md"
    click LICENSE "https://github.com/lieff/minimp4/tree/master/LICENSE"
    click Images "https://github.com/lieff/minimp4/tree/master/images/"

    %% Styles
    classDef public fill:#cce5ff,stroke:#003366,color:#003366;
    classDef internal fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef tooling fill:#ffe5b4,stroke:#cc8400,color:#663c00;
    classDef ci fill:#f0ad4e,stroke:#d58512,color:#fff;
    classDef data fill:#f1f1f1,stroke:#888,color:#555;
    classDef docs fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
