# googlechrome/omnitone architecture

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

- Interactive diagram: https://gitdiagram.com/googlechrome/omnitone
- Repository: https://github.com/googlechrome/omnitone

## Overview

##### Main Components
- Audio Input: Represent the initial source(s) of audio (HTMLMediaElement or AudioBufferSourceNode) that feed the sample into the library.
- Audio Context: Show the creation of the Web Audio API’s AudioContext that acts as the central hub for all audio operations.
- Renderers:
- FOARenderer: Responsible for first-order (4-channel) ambisonic decoding and binaural rendering.
- HOARenderer: Responsible for higher-order ambisonic decoding (2nd order with 9 channels and 3rd order with 16 channels).
- Processing Pipeline: Within each renderer, include components like:
- Convolver Nodes: For applying binaural filter responses.
- Rotator/Router Modules: (e.g., foa-rotator, foa-router, hoa-rotator) which apply rotation matrices to the sound field.
- Gain Nodes: To manage volume or other dynamic processing.
- Auxiliary Components: Modules such as the hrir-manager (for handling head-related impulse response data) and polyfills for cross-browser support.
- Output: The final output that connects to the AudioContext’s destination (speakers or headphones).
- External Dependencies: Indicate that the library is built on the Web Audio API along with specific rendering techniques (such as using Convolver and Gain nodes).

##### Relationships and Interactions
- Within the Renderer components, illustrate how the audio passes through processing modules (rotation, convolving, and channel routing) before merging into an output stream.
- External communication: For instance, how user interactions (e.g., sensor data or UI controls) can dynamically update rotation matrices via method calls like setRotationMatrix3 / setRotationMatrix4.
- Configuration and mode control: Indicate the use of methods (like setRenderingMode) to switch between ambisonic, bypass, or off modes within the processing pipeline.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize that the project is organized into distinct modules (as seen in the “src” folder—each renderer, router, and utility is self-contained).
- Separation of Concerns: Audio input, processing, and output are clearly separated, and further subdivided into FOA and HOA branches.
- Layering: Present the library as a layered system—beginning with lower-level Web Audio API nodes, moving upward to specialized ambisonic processing and high-level renderer interfaces.

##### Relevant Technologies/Frameworks
- Web Audio API: The backbone for the audio processing chain.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    A["Audio Input"]:::external
    AC["AudioContext"]:::context
    OP["Audio Output (Destination)"]:::output
    UC["User Controls"]:::control
    HRIR["HRIR Manager"]:::auxiliary
    PF["Polyfill"]:::auxiliary

    %% External Flow
    A -->|"feeds"| AC
    PF --o|"provides"| AC

    %% FOA Processing Pipeline
    subgraph "FOA Processing Pipeline"
        FRenderer["FOARenderer"]:::renderer
        FRotator["FOA Rotator"]:::processing
        FRouter["FOA Router"]:::processing
        FConvolver["FOA Convolver Node"]:::processing
    end

    %% HOA Processing Pipeline
    subgraph "HOA Processing Pipeline"
        HRenderer["HOARenderer"]:::renderer
        HRotator["HOA Rotator"]:::processing
        HConvolver["HOA Convolver Node"]:::processing
    end

    %% Connections for FOA branch
    AC -->|"routes to"| FRenderer
    FRenderer -->|"applies"| FRotator
    FRenderer -->|"applies"| FRouter
    FRotator -->|"processes"| FConvolver
    FRouter -->|"routes to"| FConvolver
    FConvolver -->|"outputs"| OP

    %% Connections for HOA branch
    AC -->|"routes to"| HRenderer
    HRenderer -->|"applies"| HRotator
    HRotator -->|"processes"| HConvolver
    HConvolver -->|"outputs"| OP

    %% Auxiliary Connections
    HRIR -->|"supplies IR data to"| FConvolver
    HRIR -->|"supplies IR data to"| HConvolver

    %% External Controls
    UC -->|"updates"| FRotator
    UC -->|"updates"| HRotator

    %% Click Events
    click AC "https://github.com/googlechrome/omnitone/blob/master/src/omnitone.js"
    click FRenderer "https://github.com/googlechrome/omnitone/blob/master/src/foa-renderer.js"
    click HRenderer "https://github.com/googlechrome/omnitone/blob/master/src/hoa-renderer.js"
    click FConvolver "https://github.com/googlechrome/omnitone/blob/master/src/foa-convolver.js"
    click HConvolver "https://github.com/googlechrome/omnitone/blob/master/src/hoa-convolver.js"
    click FRotator "https://github.com/googlechrome/omnitone/blob/master/src/foa-rotator.js"
    click FRouter "https://github.com/googlechrome/omnitone/blob/master/src/foa-router.js"
    click HRotator "https://github.com/googlechrome/omnitone/blob/master/src/hoa-rotator.js"
    click HRIR "https://github.com/googlechrome/omnitone/blob/master/src/hrir-manager.js"
    click PF "https://github.com/googlechrome/omnitone/blob/master/src/polyfill.js"

    %% Styles
    classDef external fill:#FFCCCC,stroke:#D62728,stroke-width:2px;
    classDef context fill:#CCFFCC,stroke:#2CA02C,stroke-width:2px;
    classDef renderer fill:#CCCCFF,stroke:#1F77B4,stroke-width:2px;
    classDef processing fill:#FFFFCC,stroke:#FF7F0E,stroke-width:2px;
    classDef auxiliary fill:#FFCCFF,stroke:#9467BD,stroke-width:2px;
    classDef control fill:#CCE5FF,stroke:#17BECF,stroke-width:2px;
    classDef output fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
```
