# ringbuffer-org/zerr architecture

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

- Interactive diagram: https://gitdiagram.com/ringbuffer-org/zerr
- Repository: https://github.com/ringbuffer-org/zerr

## Overview

##### Project type and purpose
- Zerr* is an open-source, multi-target audio spatialization library.
- Core algorithm (C++ static library) analyzes incoming audio features and redistributes signals across arbitrary speaker arrays.
- Provides front-ends for PureData externals, JACK client, and Max/MSP externals.

##### File structure
- Top-level build & CI: CMakeLists.txt, build.sh, .github/workflows, configs/
- core/: the algorithm engine
- / & src/ subdirectories with features/, modules/, utils/
- builds into a static library (zerr-core) via CMake and Conan
- puredata/: PD externals
- pd-lib-builder integration, headers in include/, sources in src/
- jack/: standalone JACK client (meson.build + main.cpp + scripts/)
- maxmsp/: externals built with CMake and min-devkit, organized under source/projects/
- configs/: YAML definitions for modules, presets, speaker arrays

##### README insights
- Describes algorithm (“Autogenous Spatialization…”), runtime parameter tuning, and supported host targets
- Lists external dependencies: yaml-cpp, fftw3, PureData API, min-devkit for Max/MSP

##### Components
a. Core Engine (C++)
- Feature Extractors (centroid, flux, RMS, etc.)
- Modules (envelope generator, feature bank, speaker manager)
- Utilities (config loader, FFT transformer, ringbuffer, logger)
b. Host Adapters
- PureData externals (pd-lib-builder wrapper)
- JACK client (main.cpp + zerr.cpp)
- Max/MSP externals (min-devkit projects)
c. Configuration subsystem
- YAML files (modules, presets, speakers)
- Configs loaded at runtime via utils/configs.h
d. Build & Packaging
- CMake/Conan orchestrates core + Max/MSP + PureData
- Meson for JACK
- build.sh script automates host-specific builds
e. External Dependencies & Targets
- yaml-cpp, fftw3, PureData API, Max/MSP min-devkit, JACK API

##### Relationships & data flow
- Audio input (PD/JACK/Max → plugin adapter)
- Plugin calls Core Engine API
- Core extracts audio features → computes spatialization → routes multi-channel output
- Engine consults speaker array configs (YAML) via utils
- Output streams back to host for playback

##### Architectural patterns & design principles
- Modular “core vs adapters” separation
- Plugin/host abstraction: one core engine reused across environments
- Config-driven runtime behavior
- Dependency injection via headers and build-time linking

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Adapters
    subgraph "Host Adapters"
        direction TB
        PDAdapter["PureData Adapter"]:::adapter
        JACKAdapter["JACK Client"]:::adapter
        MaxAdapter["Max/MSP Adapter"]:::adapter
    end

    %% Core Engine
    CoreEngine["Core Engine<br/>(zerr-core)"]:::core

    %% Core Subcomponents
    subgraph "Core Subcomponents"
        direction TB
        FeatureExtractors["Feature Extractors"]:::core
        CoreModules["Core Modules"]:::core
        CoreUtilities["Core Utilities"]:::core
        ConfigLoader["Config Loader<br/>(configs.h)"]:::core
    end

    %% Configuration YAML
    subgraph "Configuration Subsystem"
        direction TB
        ModulesYAML["Modules YAML"]:::config
        PresetsYAML["Presets YAML"]:::config
        SpeakersYAML["Speakers YAML"]:::config
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        RootCMake["Root CMakeLists.txt"]:::build
        BuildScript["build.sh"]:::build
        CIWorkflows["CI Workflows"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        YAMLCPP["yaml-cpp"]:::external
        FFTW3["fftw3"]:::external
        PDAPI["PureData API"]:::external
        MinDevKit["Max/MSP min-devkit"]:::external
        JACKAPI["JACK API"]:::external
    end

    %% Data Flow
    PDAdapter -->|"audio in"| CoreEngine
    JACKAdapter -->|"audio in"| CoreEngine
    MaxAdapter -->|"audio in"| CoreEngine

    CoreEngine --> FeatureExtractors
    CoreEngine --> CoreModules
    CoreEngine --> CoreUtilities
    CoreEngine --> ConfigLoader
    ConfigLoader --> ModulesYAML
    ConfigLoader --> PresetsYAML
    ConfigLoader --> SpeakersYAML

    CoreEngine -->|"audio out"| PDAdapter
    CoreEngine -->|"audio out"| JACKAdapter
    CoreEngine -->|"audio out"| MaxAdapter

    %% Build Flow
    RootCMake --> CoreEngine
    RootCMake --> MaxAdapter
    RootCMake --> PDAdapter
    BuildScript --> RootCMake
    CIWorkflows --> RootCMake
    CIWorkflows --> PDAdapter

    %% External Dependencies Linkage
    CoreEngine --> YAMLCPP
    CoreEngine --> FFTW3
    PDAdapter --> PDAPI
    JACKAdapter --> JACKAPI
    MaxAdapter --> MinDevKit

    %% Click Events
    click CoreEngine "https://github.com/ringbuffer-org/zerr/tree/main/core/"
    click FeatureExtractors "https://github.com/ringbuffer-org/zerr/tree/main/core/include/features/"
    click FeatureExtractors "https://github.com/ringbuffer-org/zerr/tree/main/core/src/features/"
    click CoreModules "https://github.com/ringbuffer-org/zerr/tree/main/core/include/modules/"
    click CoreModules "https://github.com/ringbuffer-org/zerr/tree/main/core/src/modules/"
    click CoreUtilities "https://github.com/ringbuffer-org/zerr/tree/main/core/include/utils/"
    click CoreUtilities "https://github.com/ringbuffer-org/zerr/tree/main/core/src/utils/"
    click ConfigLoader "https://github.com/ringbuffer-org/zerr/blob/main/core/include/utils/configs.h"
    click ModulesYAML "https://github.com/ringbuffer-org/zerr/tree/main/configs/modules/"
    click PresetsYAML "https://github.com/ringbuffer-org/zerr/tree/main/configs/presets/"
    click SpeakersYAML "https://github.com/ringbuffer-org/zerr/tree/main/configs/speakers/"
    click PDAdapter "https://github.com/ringbuffer-org/zerr/tree/main/puredata/include/"
    click PDAdapter "https://github.com/ringbuffer-org/zerr/tree/main/puredata/src/"
    click PDAdapter "https://github.com/ringbuffer-org/zerr/tree/main/puredata/Makefile"
    click PDAdapter "https://github.com/ringbuffer-org/zerr/blob/main/puredata/conanfile.txt"
    click JACKAdapter "https://github.com/ringbuffer-org/zerr/blob/main/jack/main.cpp"
    click JACKAdapter "https://github.com/ringbuffer-org/zerr/blob/main/jack/zerr.cpp"
    click JACKAdapter "https://github.com/ringbuffer-org/zerr/blob/main/jack/zerr.h"
    click JACKAdapter "https://github.com/ringbuffer-org/zerr/blob/main/jack/meson.build"
    click JACKAdapter "https://github.com/ringbuffer-org/zerr/tree/main/jack/scripts/"
    click MaxAdapter "https://github.com/ringbuffer-org/zerr/blob/main/maxmsp/CMakeLists.txt"
    click MaxAdapter "https://github.com/ringbuffer-org/zerr/blob/main/maxmsp/conanfile.txt"
    click MaxAdapter "https://github.com/ringbuffer-org/zerr/tree/main/maxmsp/source/projects/"
    click MaxAdapter "https://github.com/ringbuffer-org/zerr/tree/main/maxmsp/source/min-api/"
    click MaxAdapter "https://github.com/ringbuffer-org/zerr/tree/main/maxmsp/source/min-lib/"
    click MaxAdapter "https://github.com/ringbuffer-org/zerr/tree/main/maxmsp/docs/"
    click MaxAdapter "https://github.com/ringbuffer-org/zerr/tree/main/maxmsp/help/"
    click RootCMake "https://github.com/ringbuffer-org/zerr/blob/main/CMakeLists.txt"
    click BuildScript "https://github.com/ringbuffer-org/zerr/blob/main/build.sh"
    click CIWorkflows "https://github.com/ringbuffer-org/zerr/blob/main/.github/workflows/build-zerr-core-static-library.yml"
    click CIWorkflows "https://github.com/ringbuffer-org/zerr/blob/main/.github/workflows/build-puredata-plugins-with-pd-lib-builder.yml"

    %% Styles
    classDef core fill:#ffe4e1,stroke:#d2691e,color:#000
    classDef adapter fill:#e0ffff,stroke:#20b2aa,color:#000
    classDef config fill:#f0fff0,stroke:#32cd32,color:#000
    classDef build fill:#fffacd,stroke:#ffd700,color:#000
    classDef external fill:#ffe4b5,stroke:#ff8c00,color:#000
```
