# ebu/libear architecture

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

- Interactive diagram: https://gitdiagram.com/ebu/libear
- Repository: https://github.com/ebu/libear

## Overview

##### Project Type & Purpose
- libear is a C++14 library (not a full-blown application) that implements components for rendering ADM content according to Recommendation ITU-R BS.2127. Its purpose is to offer a robust set of gain calculation and audio processing utilities that can be embedded into larger applications.
- The README clarifies that it is meant to be used either as an installed library or as a subproject via CMake, and that key functionalities include gain calculation across several methodologies (direct speakers, HOA, object based) as well as digital signal processing (DSP) components.

##### Analyzing the File Structure
- Top-level Directories:
- "include/ear": Contains all public headers exposing APIs like gain calculators, DSP utilities, conversion functions, and exception handling.
- "src": Implements the actual logic; it further subdivides functionality (e.g., direct_speakers, dsp, hoa, object_based) showing different approaches for computing gains and processing audio.
- "tests": Contains unit tests for validating functionality.
- "docs": Provides documentation files, likely explaining underlying architecture and technical details.
- "cmake", "config", "examples", "tools": These support build configuration (CMakeLists.txt and config files), provide examples of usage, and script-based generation of certain files (layouts and rules).
- "submodules": Houses third-party dependencies (Catch2 for testing, eigen for math, kissfft, and xsimd for performance enhancements).
- Files such as CMakeLists.txt at multiple locations along with .github workflows and CI configurations (e.g., .gitlab-ci.yml, codecov) underline a robust build and continuous integration setup.

##### Key Components
a. Core Library Components:
- API Layer: Public headers in include/ear expose the library’s interfaces.
- Gain Calculators: Separated in subdirectories like direct_speakers, hoa, and object_based which implement distinct algorithms.
- DSP Functionality: Manifest in include/ear/dsp and src/dsp (e.g., block convolver, delay buffer, gain interpolation) responsible for low-level audio processing.
- Conversion & Decorrelate: Modules that handle format conversion and decorrelation methodologies.
- Common Utilities: Helpers, layout functions, and error handling (exceptions and warnings).
b. Build & Configuration:
- CMake Build System: Central CMakeLists.txt files, supporting scripts in the "cmake" and "config" directories.
- External Dependencies: Submodules (Catch2, Eigen, KissFFT, xsimd) are integrated as part of the build process.
c. Testing & Documentation:
- Tests: Extensive test suite in the tests/ directory ensuring reliability.

##### Relationships and Interactions
- The API (include/ear) is consumed internally by source implementations located in src/.
- Different gain calculator variants (direct speakers, Hoa, object based) are realized as separate but related components that reuse common utilities (from include/ear/helpers and src/common).
- The DSP module interacts with gain calculators by processing audio with routines such as convolution, delay, and interpolation.
- The build system (CMake and configuration files) coordinates the integration of all these modules and manages dependency setup using submodules.
- Testing components validate the interactions among these modules, with tests specifically corresponding to each logical component as seen in tests/.

##### Elements
- Clear labels for each component (e.g., “API Layer”, “Direct Speaker Gain Calculator”, “HOA Gain Calculator”, “DSP Block Convolver”, “Build System”, “Testing Suite”).
▸ From API --> Gain Calculators --> DSP Module
▸ From Build System --> External Libraries (submodules)
- Annotations for third-party integrations (Boost, Eigen, etc.) and build flow (CMake configurations and CI integration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    ClientApp["Client Application"]:::client
    API["API Layer"]:::api
    DS["Direct Speakers Gain Calculator"]:::gain
    HOA["HOA Gain Calculator"]:::gain
    OB["Object-Based Gain Calculator"]:::gain
    DSP["DSP Subsystem"]:::dsp
    Conv["Conversion & Decorrelate Modules"]:::conv
    Utils["Common Utilities & Helpers"]:::util
    Build["Build & Integration Layer"]:::build
    External["External Dependencies"]:::external
    Test["Testing Suite"]:::test
    Docs["Documentation"]:::docs

    %% Relationships
    ClientApp -->|"calls"| API
    API -->|"uses"| DS
    API -->|"uses"| HOA
    API -->|"uses"| OB
    DS  -->|"processes"| DSP
    HOA -->|"processes"| DSP
    OB  -->|"processes"| DSP
    API -->|"converts"| Conv
    API -->|"calls"| Utils

    Build -->|"integrates"| API
    Build -->|"builds"| DS
    Build -->|"builds"| HOA
    Build -->|"builds"| OB
    Build -->|"builds"| DSP
    Build -->|"builds"| Conv
    Build -->|"builds"| Utils
    Build -->|"includes"| External

    Test -->|"tests"| API
    Test -->|"tests"| DS
    Test -->|"tests"| DSP

    Docs -->|"documents"| API
    Docs -->|"documents"| DS
    Docs -->|"documents"| DSP

    DSP -->|"results"| ClientApp

    %% Click Events
    click API "https://github.com/ebu/libear/tree/master/include/ear"
    click DS "https://github.com/ebu/libear/blob/master/src/direct_speakers/gain_calculator_direct_speakers.cpp"
    click DS "https://github.com/ebu/libear/blob/master/src/direct_speakers/gain_calculator_direct_speakers.hpp"
    click HOA "https://github.com/ebu/libear/blob/master/src/hoa/gain_calculator_hoa.cpp"
    click HOA "https://github.com/ebu/libear/blob/master/src/hoa/gain_calculator_hoa.hpp"
    click OB "https://github.com/ebu/libear/blob/master/src/object_based/gain_calculator_objects.cpp"
    click OB "https://github.com/ebu/libear/blob/master/src/object_based/gain_calculator_objects.hpp"
    click DSP "https://github.com/ebu/libear/tree/master/include/ear/dsp"
    click DSP "https://github.com/ebu/libear/blob/master/src/dsp/block_convolver.cpp"
    click DSP "https://github.com/ebu/libear/blob/master/src/dsp/delay_buffer_impl.cpp"
    click DSP "https://github.com/ebu/libear/blob/master/src/dsp/variable_block_size_impl.cpp"
    click Conv "https://github.com/ebu/libear/blob/master/include/ear/conversion.hpp"
    click Conv "https://github.com/ebu/libear/blob/master/include/ear/decorrelate.hpp"
    click Conv "https://github.com/ebu/libear/blob/master/src/conversion.cpp"
    click Conv "https://github.com/ebu/libear/blob/master/src/decorrelate.cpp"
    click Utils "https://github.com/ebu/libear/tree/master/include/ear/helpers"
    click Utils "https://github.com/ebu/libear/blob/master/include/ear/layout.hpp"
    click Utils "https://github.com/ebu/libear/tree/master/src/common"
    click Utils "https://github.com/ebu/libear/tree/master/src/common/helpers"
    click Build "https://github.com/ebu/libear/blob/master/CMakeLists.txt"
    click Build "https://github.com/ebu/libear/tree/master/cmake"
    click Build "https://github.com/ebu/libear/tree/master/config"
    click Build "https://github.com/ebu/libear/tree/master/submodules"
    click Test "https://github.com/ebu/libear/tree/master/tests"
    click Docs "https://github.com/ebu/libear/tree/master/docs"
    click External "https://github.com/ebu/libear/tree/master/submodules"

    %% Styles
    classDef client fill:#f4d03f,stroke:#c0392b,stroke-width:2px;
    classDef api fill:#85c1e9,stroke:#2e86c1,stroke-width:2px;
    classDef gain fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef dsp fill:#82e0aa,stroke:#28b463,stroke-width:2px;
    classDef conv fill:#abebc6,stroke:#1abc9c,stroke-width:2px;
    classDef util fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
    classDef build fill:#d5dbdb,stroke:#7f8c8d,stroke-width:2px;
    classDef test fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef docs fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef external fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
```
