# arthenica/libaom architecture

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

- Interactive diagram: https://gitdiagram.com/arthenica/libaom
- Repository: https://github.com/arthenica/libaom

## Overview

##### Project type and purpose
- This is an open-source, cross-platform C/C++ library implementing the AV1 video codec, plus command-line applications (aomenc, aomdec), examples, tools, and tests.
- Key use cases: encode/decode AV1 streams, integrate with other media frameworks (e.g., libwebm, libyuv), cross-compile for various targets.

##### Top-level components
a. Build System (CMake)
- CMakeLists.txt & build/cmake/** – orchestrates configuration, toolchain selection, feature flags, cross-compile support, sanitizer support, build of library, apps, tests, docs.
b. Core Library (libaom)
- aom/ – public API headers, codec entry points, internal dispatch.
- av1/ – AV1-specific encoder and decoder implementations, each subdivided into:
– encoder/ (rate control, motion search, transforms, quantization, threading, syntax, output bitstream)
– decoder/ (parsing OBU, inverse transforms, loopfilter, synthesis, multithread)
– common/ (shared algorithms: transforms, loop-filters, entropy coding, frame buffers, SIMD dispatch)
- aom_dsp/, aom_scale/, aom_mem/, aom_ports/, aom_util/ – modular building blocks for DSP routines, image scaling, memory allocation, platform abstraction (CPU detection, aligned loads, endianness), threading and debug utilities.
c. Applications & Examples
- apps/ (aomenc, aomdec) – CLI front ends that link against libaom APIs to perform real-world encoding/decoding.
- examples/ – sample code illustrating how to invoke the API (e.g., simple encoder/decoder, two-pass, scalable decoding).
d. Third-Party Libraries
- third_party/googletest – unit-testing framework (gtest) used by test/
e. Test Infrastructure
- test/ – unit & integration tests organized by feature; scripts (.sh, CMake targets) to download test data and run shards via gtest.
f. Tools & Scripts
- tools/ – code-generation scripts (Perl, Python, JS), linters, OBU parsers, auto-refactoring utilities, commit-hooks.
g. Documentation
- doc/, usage*.dox, mainpage.dox – design docs, developer guides, algorithm descriptions.

##### Interactions & Data Flow
- Apps/examples → invoke public API in aom/, av1/ → internally call into DSP, scale, mem, ports, util modules → perform encode/decode pipelines → output bitstream or raw frames.
- CMake build system reads CMakeLists.txt, includes toolchain files (build/cmake/toolchains) → compiles modules into static/shared libs → links apps, tests.
- Tests link against built libaom + googletest → load test data (downloaded via testdata target) → exercise API → report pass/fail.
- Third-party code is included via source trees, compiled alongside core modules under unified build.

##### Architectural patterns & design principles
- Layered design: public API layer (aom/), codec algorithm layer (av1/), low-level DSP/port abstraction, platform-specific SIMD backends.
- SIMD dispatch and code-generation: run-time CPU detection (aom_ports) + compile-time dispatch (rtcd) for optimized kernels in aom_dsp, av1/common.
- Plugin-like toolchain files: CMake toolchain architecture supports cross-compiling by injecting target-specific flags.
- Test-driven: gtest integration, automated testdata download, sharded test runs.

- Clear labels for components (e.g., “av1/encoder”, “aom_dsp”, “build/cmake”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    BS["Build System\n(CMakeLists.txt & build/cmake/)"]:::build

    %% Public API
    API["Public API\n(aom/)"]:::api

    %% Codec Core
    subgraph "Codec Core (av1/)"
        ENC["Encoder\n(av1/encoder/)"]:::core
        DEC["Decoder\n(av1/decoder/)"]:::core
        COM["Common\n(av1/common/)"]:::core
    end

    %% DSP & Platform
    subgraph "DSP & Platform"
        DSP["DSP Routines\n(aom_dsp/)"]:::dsp
        SCALE["Image Scaling\n(aom_scale/)"]:::dsp
        MEM["Memory Management\n(aom_mem/)"]:::dsp
        PORTS["Platform Abstraction\n(aom_ports/)"]:::dsp
        UTIL["Utilities\n(aom_util/)"]:::dsp
    end

    %% Apps & Examples
    subgraph "Applications & Examples"
        APPS["Applications\n(apps/)"]:::app
        EX["Examples\n(examples/)"]:::app
    end

    %% Third-Party
    subgraph "Third-Party Integrations"
        GTEST["googletest\n(third_party/googletest/)"]:::third
        LIBWEBM["libwebm\n(third_party/libwebm/)"]:::third
        LIBYUV["libyuv\n(third_party/libyuv/)"]:::third
        FAST["fastfeat\n(third_party/fastfeat/)"]:::third
        VECTOR["vector\n(third_party/vector/)"]:::third
        X86INC["x86inc\n(third_party/x86inc/)"]:::third
    end

    %% Test Infrastructure
    TEST["Test Infrastructure\n(test/)"]:::build

    %% Tools & Scripts
    TOOLS["Tools & Scripts\n(tools/)"]:::scripts

    %% Documentation
    DOC["Documentation\n(doc/)"]:::docs

    %% Connections: Build System compiles modules
    BS --> API
    BS --> ENC
    BS --> DEC
    BS --> COM
    BS --> DSP
    BS --> SCALE
    BS --> MEM
    BS --> PORTS
    BS --> UTIL
    BS --> APPS
    BS --> EX
    BS --> TEST
    BS --> TOOLS
    BS --> DOC

    %% Runtime & API flows
    APPS -->|"invoke"| API
    EX -->|"invoke"| API
    API -->|"uses"| ENC
    API -->|"uses"| DEC
    API -->|"uses"| COM

    %% Core to DSP & Platform
    ENC -->|"calls"| DSP
    DEC -->|"calls"| DSP
    COM -->|"calls"| DSP
    COM -->|"uses"| SCALE
    COM -->|"uses"| MEM
    COM -->|"uses"| PORTS
    COM -->|"uses"| UTIL

    %% Third-party usage
    API -->|"I/O via"| LIBWEBM
    API -->|"color conv via"| LIBYUV

    %% Testing flows
    TEST -->|"tests"| API
    TEST -->|"tests"| ENC
    TEST -->|"tests"| DEC
    TEST -->|"tests"| COM

    %% Tools codegen
    TOOLS -->|"generate dispatch"| DSP
    TOOLS -->|"generate dispatch"| COM

    %% Click events
    click BS "https://github.com/arthenica/libaom/tree/master/CMakeLists.txt & build/cmake/"
    click API "https://github.com/arthenica/libaom/tree/master/aom/"
    click ENC "https://github.com/arthenica/libaom/tree/master/av1/encoder/"
    click DEC "https://github.com/arthenica/libaom/tree/master/av1/decoder/"
    click COM "https://github.com/arthenica/libaom/tree/master/av1/common/"
    click DSP "https://github.com/arthenica/libaom/tree/master/aom_dsp/"
    click SCALE "https://github.com/arthenica/libaom/tree/master/aom_scale/"
    click MEM "https://github.com/arthenica/libaom/tree/master/aom_mem/"
    click PORTS "https://github.com/arthenica/libaom/tree/master/aom_ports/"
    click UTIL "https://github.com/arthenica/libaom/tree/master/aom_util/"
    click APPS "https://github.com/arthenica/libaom/tree/master/apps/"
    click EX "https://github.com/arthenica/libaom/tree/master/examples/"
    click GTEST "https://github.com/arthenica/libaom/tree/master/third_party/googletest/"
    click LIBWEBM "https://github.com/arthenica/libaom/tree/master/third_party/libwebm/"
    click LIBYUV "https://github.com/arthenica/libaom/tree/master/third_party/libyuv/"
    click FAST "https://github.com/arthenica/libaom/tree/master/third_party/fastfeat/"
    click VECTOR "https://github.com/arthenica/libaom/tree/master/third_party/vector/"
    click X86INC "https://github.com/arthenica/libaom/tree/master/third_party/x86inc/"
    click TEST "https://github.com/arthenica/libaom/tree/master/test/"
    click TOOLS "https://github.com/arthenica/libaom/tree/master/tools/"
    click DOC "https://github.com/arthenica/libaom/tree/master/doc/"

    %% Styles
    classDef build fill:#D3D3D3,stroke:#333
    classDef api fill:#ADD8E6,stroke:#333
    classDef core fill:#ADD8E6,stroke:#333
    classDef dsp fill:#98FB98,stroke:#333
    classDef app fill:#FFA500,stroke:#333
    classDef third fill:#DDA0DD,stroke:#333
    classDef scripts fill:#FFE4B5,stroke:#333
    classDef docs fill:#AFEEEE,stroke:#333
```
