How leomccormack/spatial_audio_framework works
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.