# kcat/openal-soft architecture

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

- Interactive diagram: https://gitdiagram.com/kcat/openal-soft
- Repository: https://github.com/kcat/openal-soft

## Overview

##### Project Type and Purpose
- This is OpenAL Soft, an LGPL-licensed, cross-platform, software implementation of the OpenAL 3D audio API.
- It exposes the standard AL (application-level functions) and ALC (context/device management) interfaces, implements core audio processing (mixing, effects, HRTF, resampling, etc.), and dispatches final PCM data to various backends (ALSA, PulseAudio, WASAPI, CoreAudio, etc.).

##### File-Structure Analysis
- Top-level “al/” directory: AL API implementation (buffer, source, listener, effects, EAX extensions).
- Top-level “alc/” directory: ALC context and device management, plus the “alc/backends/” subdirectory holding platform-specific audio-output drivers.
- “core/”: The audio‐processing engine—mixers, resamplers, filters, effects chains, HRTF, voice management.
- “common/”: Shared utilities—threading, atomic operations, dynamic loading, file I/O, math helpers.
- “router/”: Loader layer that intercepts library entry points, dispatching calls into the real AL/ALC implementations.
- “utils/”: Standalone tool sources (openal-info, config GUI, sofa/HRTF conversions).
- “examples/”: Sample applications showing API usage.
- “configs/” & “presets/” & “hrtf/”: Runtime configuration files, built-in effect/panning presets, HRTF datasets.
- Build files: CMakeLists.txt, config templates, CI scripts.

##### Key Components
a. Public API Layer
- Router (“router/”)—single entry-point that dynamically loads and forwards to AL (“al/”) and ALC (“alc/”) modules.
- AL module—high-level commands: alSource*, alBuffer*, EFX extensions, EAX API.
- ALC module—context and device management.
b. Core Processing Engine (“core/”)
- Context & voice manager
- Mixer (multiple SIMD-optimized variants)
- Resampler, filters, effects pipeline (EAX, EFX, reverb, equalizer, etc.)
- HRTF loader & spatializer
c. Backend Abstraction (“alc/backends/”)
- A set of pluggable drivers: ALSA, PulseAudio, CoreAudio, WASAPI, OpenSL, OSS, JACK, etc.
- Each driver implements device open/close, buffer submission, callback or polling.
d. Shared Utilities (“common/”)
- Threading, locks, atomics
- Dynamic library loading
- Filesystem abstraction, string utilities, vector/matrix math
e. Configuration & Resources
- Config file loader (alsoftrc)
- Presets, HRTF datasets, .ini samples
f. Tools & Examples
- openal-info, config GUI (Qt), sofa converters
- Example apps illustrating API usage

##### Relationships & Data Flows
- Application → Router → AL/ALC API modules
- AL/ALC modules call into Core Engine to:
- Create contexts, allocate voices, queue buffers
- Mixer processes voices per‐frame: resample, filter, apply effects, spatialize (HRTF/panning)
- Core Engine outputs PCM frames → Backend driver → OS audio subsystem → Hardware
- Config/Presets/HRTF files are read at initialization or on‐demand by Core modules
- Common utilities underpin all layers

##### Architectural Patterns & Principles
- Modular layering: clear separation of API, engine, and platform-specific code
- Plugin pattern for backends: each driver conforms to a common interface and is detected/enabled at build/runtime
- Single‐responsibility modules: mixing, effects, loading, threading are decoupled
- SIMD specialization: multiple mixer implementations optimized per-ISA

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Public API & Router Layer
    subgraph "Public API & Router"
        direction TB
        Application["Application"]:::external
        Router["Router"]:::api
        AL["AL Module"]:::api
        ALC["ALC Module"]:::api
    end

    Application -->|"entry point"| Router
    Router -->|"forwards to AL"| AL
    Router -->|"forwards to ALC"| ALC

    %% Core Engine & Common Utilities Layer
    subgraph "Core Engine"
        direction TB
        ContextMgr["Context & Voice Manager"]:::core
        Mixer["Mixer"]:::core
        Effects["Effects Pipeline (EFX/EAX)"]:::core
        Spatializer["HRTF Loader & Spatializer"]:::core
    end

    subgraph "Common Utilities"
        direction TB
        Common["Common Utilities"]:::common
    end

    AL -->|"AL calls"| ContextMgr
    ALC -->|"context/device calls"| ContextMgr
    ContextMgr -->|"voice processing"| Mixer
    Mixer -->|"apply effects"| Effects
    Effects -->|"spatialization"| Spatializer
    Common -->|"underpins all layers"| ContextMgr
    Common --> ContextMgr
    Common --> Mixer
    Common --> Effects
    Common --> Spatializer

    %% Backend Drivers & Resources Layer
    subgraph "Backend Drivers"
        direction TB
        Backends["alc/backends"]:::backend
    end

    subgraph "Resources"
        direction TB
        Configs["configs"]:::resource
        Presets["presets"]:::resource
        HRTF["hrtf"]:::resource
    end

    Spatializer -->|"PCM frames"| Backends
    Backends -->|"OS Audio Subsystem"| Hardware["Hardware"]:::external

    CoreEngineRead -.->|"loads config"| Configs
    CoreEngineRead -.->|"loads presets"| Presets
    CoreEngineRead -.->|"loads HRTF data"| HRTF

    %% Tools & Examples Side Box
    subgraph "Tools & Examples"
        direction TB
        Utils["utils"]:::tools
        Examples["examples"]:::tools
    end

    Utils -->|"standalone tools"| Application
    Examples -->|"sample apps"| Application

    %% Click Events
    click Router "https://github.com/kcat/openal-soft/tree/master/router/"
    click AL "https://github.com/kcat/openal-soft/tree/master/al/"
    click ALC "https://github.com/kcat/openal-soft/tree/master/alc/"
    click Backends "https://github.com/kcat/openal-soft/tree/master/alc/backends/"
    click CoreEngineRead "https://github.com/kcat/openal-soft/tree/master/core/"
    click Common "https://github.com/kcat/openal-soft/tree/master/common/"
    click Configs "https://github.com/kcat/openal-soft/tree/master/configs/"
    click Presets "https://github.com/kcat/openal-soft/tree/master/presets/"
    click HRTF "https://github.com/kcat/openal-soft/tree/master/hrtf/"
    click Utils "https://github.com/kcat/openal-soft/tree/master/utils/"
    click Examples "https://github.com/kcat/openal-soft/tree/master/examples/"

    %% Styles
    classDef api fill:#8ecae6,stroke:#023047,color:#000;
    classDef core fill:#a8dadc,stroke:#023047,color:#000;
    classDef common fill:#dee2e6,stroke:#023047,color:#000;
    classDef backend fill:#ffb703,stroke:#fb8b24,color:#000;
    classDef resource fill:#fb8500,stroke:#b56576,color:#000;
    classDef tools fill:#cbd5e0,stroke:#023047,color:#000;
    classDef external fill:#ffffff,stroke:#000000,color:#000;
```
