# leomccormack/spatial_audio_framework architecture

> Architecture diagram of the GitHub repository leomccormack/spatial_audio_framework, 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/leomccormack/spatial_audio_framework
- Repository: https://github.com/leomccormack/spatial_audio_framework

## Overview

##### Project type and purpose
- This is an open-source, cross-platform C/C++ **framework/library** for spatial audio processing (the “Spatial Audio Framework” or SAF).
- It is organized as a **modular audio DSP library** (core modules + optional modules), with **example applications**, **language bindings (MATLAB/Python/MEX/Wwise)**, **unit tests**, and **documentation**.

##### File structure
- Top-level directories:
- framework/      → core and optional spatial-audio modules + public headers
- framework/resources/ → 3rd-party helper libraries (kissFFT, zlib, etc.)
- examples/       → sample console/VST/LV2 apps demonstrating each module
- extras/         → MATLAB scripts (safmatlab), MEX wrappers (safmex), Python wrappers (safpy), Wwise integration (safwwise)
- test/           → unit tests with Unity, Visual Studio and Xcode projects
- docs/           → high-level framework description + Doxygen config and templates
- scripts/        → install/build helper scripts for external libs (IPP, MKL)
- .github/        → CI workflows (CMake build, Doxygen generation)
- CMakeLists.txt  → build orchestration and option flags
- Configuration/build files:
- CMakeLists.txt + module CMake files define build targets, options (performance library, SIMD, modules)
- GitHub Actions YAMLs drive continuous build and documentation generation

##### README highlights
- Core modules: saf_hoa, saf_sh, saf_vbap, saf_cdf4sap, saf_hrir, saf_reverb, saf_utilities
- Optional modules (enabled via CMake flags): saf_sofa_reader, saf_tracker, saf_hades
- Dependencies: CBLAS/LAPACK, optional IPP/FFTW, SIMD intrinsics
- Examples showing command-line DSP apps and audio plug-ins under SPARTA
- Extras for MATLAB/Python/Wwise integration
- Unit testing harness using Unity, build/test via CMake

##### Main components & relationships
a. Core Framework Layer
- **Public API** (framework/include)
- **Core Modules** (framework/modules/*)
- **Resource Libraries** (framework/resources/*)
b. Build & Configuration Layer
- **CMake** (root + per-module CMakeLists)
- **Scripts** (scripts/install-*.sh/.bat)
- **CI/CD** (.github/workflows)
c. Consumers
- **Examples** (examples/src + include) – link to public API & modules
- **Extras** (MATLAB, Python, MEX, Wwise) – wrappers invoke public API
- **Unit Tests** (test/src) – test core modules via Unity test harness
- CBLAS/LAPACK (MKL, OpenBLAS, Apple Accelerate, ATLAS)
- IPP, FFTW, SIMD
e. Documentation
- **Doxygen** (docs/doxygen) with custom theme → published site

##### Relationships / interactions
- **Consumers** (Examples / Extras / Tests) → call → **Public API** → dispatch → **Core Modules** (which may call) → **Resource Libraries** → use → **External Dependencies**
- **CMake** → configures & builds → all layers (Framework, Resources, Examples, Extras, Tests)
- **CI/CD workflows** → trigger → CMake build + run tests + generate docs

##### Architectural patterns & principles
- **Modular design**: each algorithm lives in its own module
- **Layered architecture**: public API layer, implementation layer (modules), resource layer, consumer layer
- **Dependency injection via CMake flags**: performance libs, optional modules, SIMD
- **Separation of concerns**:
- DSP code ≠ build code ≠ examples ≠ docs ≠ CI

##### Final advice
- **build configuration** influencing which modules and resource libs are compiled.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    subgraph "External Dependencies"
        CBLAS["CBLAS/LAPACK"]:::external
        IPP["IPP"]:::external
        FFTW["FFTW"]:::external
        SIMD["SIMD Intrinsics"]:::external
    end

    %% Framework Core
    subgraph "Framework Core"
        subgraph "Public API"
            API1["saf.h"]:::core
            API2["saf_externals.h"]:::core
        end
        subgraph "Core Modules"
            HOA["saf_hoa"]:::core
            SH["saf_sh"]:::core
            VBAP["saf_vbap"]:::core
            CDF4["saf_cdf4sap"]:::core
            HRIR["saf_hrir"]:::core
            REVERB["saf_reverb"]:::core
            UTIL["saf_utilities"]:::core
        end
        subgraph "Optional Modules"
            SOFA["saf_sofa_reader"]:::optional
            TRACKER["saf_tracker"]:::optional
            HADES["saf_hades"]:::optional
        end
        subgraph "Resource Libraries"
            KISS["kissFFT"]:::core
            ZLIB["zlib"]:::core
            SPEEX["speex_resampler"]:::core
            AFSTFT["afSTFT"]:::core
            CONVHULL["convhull_3d"]:::core
            MDMALLOC["md_malloc"]:::core
        end
    end

    %% Consumers
    subgraph "Consumers"
        EXAMPLES["Examples"]:::consumers
        EXTRAS["Extras (MATLAB/Python/Wwise)"]:::consumers
        TESTS["Unit Tests"]:::consumers
    end

    %% Build & Config
    subgraph "Build & Config"
        CMAKE["CMake"]:::build
        SCRIPTS["Scripts"]:::build
    end

    %% CI/CD
    subgraph "CI/CD"
        CFA["CI Build/Test"]:::build
        DOXYCI["Doxygen CI"]:::build
    end

    %% Documentation
    subgraph "Documentation"
        DOCS1["FRAMEWORK_STRUCTURE.md"]:::docs
        DOCS2["PERFORMANCE_LIBRARY_INSTRUCTIONS.md"]:::docs
        DOCS3["CustomDoxygen.css"]:::docs
        DOCS4["DoxygenLayout.xml"]:::docs
    end

    %% Runtime & Build Relationships
    EXAMPLES -->|"call API"| API1
    EXTRAS -->|"call API"| API1
    TESTS -->|"test via API"| API1

    API1 -->|"dispatch"| HOA
    API1 -->|"dispatch"| SH
    API1 -->|"dispatch"| VBAP
    API1 -->|"dispatch"| CDF4
    API1 -->|"dispatch"| HRIR
    API1 -->|"dispatch"| REVERB
    API1 -->|"dispatch"| UTIL
    API1 -->|"dispatch optional"| SOFA
    API1 -->|"dispatch optional"| TRACKER
    API1 -->|"dispatch optional"| HADES

    HOA -->|"use"| KISS
    SH -->|"use"| ZLIB
    VBAP -->|"use"| SPEEX
    CDF4 -->|"use"| AFSTFT
    HRIR -->|"use"| CONVHULL
    REVERB -->|"use"| MDMALLOC

    KISS -->|"link"| CBLAS
    ZLIB -->|"link"| CBLAS
    SPEEX -->|"link"| FFTW
    AFSTFT -->|"link"| FFTW
    CONVHULL -->|"link"| CBLAS
    MDMALLOC -->|"link"| CBLAS

    CMAKE -->|"builds"| EXAMPLES
    CMAKE -->|"builds"| EXTRAS
    CMAKE -->|"builds"| TESTS
    CMAKE -->|"builds"| HOA
    CMAKE -->|"builds"| SH
    CMAKE -->|"builds"| VBAP
    CMAKE -->|"builds"| CDF4
    CMAKE -->|"builds"| HRIR
    CMAKE -->|"builds"| REVERB
    CMAKE -->|"builds"| UTIL
    CMAKE -->|"builds optional"| SOFA
    CMAKE -->|"builds optional"| TRACKER
    CMAKE -->|"builds optional"| HADES
    CMAKE -->|"builds"| KISS
    CMAKE -->|"builds"| ZLIB
    CMAKE -->|"builds"| SPEEX
    CMAKE -->|"builds"| AFSTFT
    CMAKE -->|"builds"| CONVHULL
    CMAKE -->|"builds"| MDMALLOC

    SCRIPTS -->|"install deps"| CMAKE
    CFA -->|"trigger"| CMAKE
    CFA -->|"run tests"| TESTS
    DOXYCI -->|"generate docs"| DOCS1
    DOXYCI -->|"generate docs"| DOCS3
    DOXYCI -->|"generate docs"| DOCS4

    %% Click Events
    click API1 "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/include/saf.h"
    click API2 "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/include/saf_externals.h"
    click HOA "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_hoa/saf_hoa.c"
    click SH "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_sh/saf_sh.c"
    click VBAP "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_vbap/saf_vbap.c"
    click CDF4 "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_cdf4sap/saf_cdf4sap.c"
    click HRIR "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_hrir/saf_hrir.c"
    click REVERB "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_reverb/saf_reverb.c"
    click UTIL "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_utilities/saf_utilities.h"
    click SOFA "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_sofa_reader/saf_sofa_reader.c"
    click TRACKER "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_tracker/saf_tracker.c"
    click HADES "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/modules/saf_hades/saf_hades_analysis.c"
    click KISS "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/resources/kissFFT/kiss_fft.c"
    click ZLIB "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/resources/zlib/deflate.c"
    click SPEEX "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/resources/speex_resampler/resample.c"
    click AFSTFT "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/resources/afSTFT/afSTFTlib.c"
    click CONVHULL "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/resources/convhull_3d/convhull_3d.c"
    click MDMALLOC "https://github.com/leomccormack/spatial_audio_framework/blob/master/framework/resources/md_malloc/md_malloc.c"
    click CMAKE "https://github.com/leomccormack/spatial_audio_framework/blob/master/CMakeLists.txt"
    click SCRIPTS "https://github.com/leomccormack/spatial_audio_framework/blob/master/scripts/install-safmkl.sh"
    click EXAMPLES "https://github.com/leomccormack/spatial_audio_framework/blob/master/examples/CMakeLists.txt"
    click EXTRAS "https://github.com/leomccormack/spatial_audio_framework/blob/master/extras/CMakeLists.txt"
    click TESTS "https://github.com/leomccormack/spatial_audio_framework/blob/master/test/CMakeLists.txt"
    click CFA "https://github.com/leomccormack/spatial_audio_framework/blob/master/.github/workflows/cmake.yml"
    click DOXYCI "https://github.com/leomccormack/spatial_audio_framework/blob/master/.github/workflows/doxygen.yml"
    click DOCS1 "https://github.com/leomccormack/spatial_audio_framework/blob/master/docs/FRAMEWORK_STRUCTURE.md"
    click DOCS2 "https://github.com/leomccormack/spatial_audio_framework/blob/master/docs/PERFORMANCE_LIBRARY_INSTRUCTIONS.md"
    click DOCS3 "https://github.com/leomccormack/spatial_audio_framework/blob/master/docs/doxygen/CustomDoxygen.css"
    click DOCS4 "https://github.com/leomccormack/spatial_audio_framework/blob/master/docs/doxygen/DoxygenLayout.xml"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef optional fill:#fff3cd,stroke:#856404,color:#856404,stroke-dasharray: 5 5
    classDef consumers fill:#d4edda,stroke:#155724,color:#155724
    classDef build fill:#e2e3e5,stroke:#383d41,color:#383d41
    classDef docs fill:#ffe5cc,stroke:#7f4f01,color:#7f4f01
    classDef external fill:#f0f0f0,stroke:#6c757d,color:#6c757d,stroke-dasharray: 2 2
```
