How ebu/libear works
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).