# ableton/audioperflab architecture

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

- Interactive diagram: https://gitdiagram.com/ableton/audioperflab
- Repository: https://github.com/ableton/audioperflab

## Overview

##### Project type and purpose
- This is a single‐product iOS application (“AudioPerfLab”) for real‐time audio performance exploration on iPhone and iPad.

##### File structure
- Top‐level Xcode project (`AudioPerfLab.xcodeproj`) with an iOS app target.
- `AudioPerfLab/` contains Swift UI code (`ViewController.swift`, storyboards, Swift view subclasses) plus mixed C++/Objective‐C++ engine (`Engine.hpp/.mm`, `ParallelSineBank.cpp`, etc.) bridged via `AudioPerfLab-Bridging-Header.h`.
- `Base/` is a C++ utility library (threading primitives, queues, semaphores, workgroup support) shared by the engine.
- CI config (`.travis.yml`), formatting, and license files.

##### README for additional insights
- CoreAudio I/O is driven by a “driver thread” with configurable modes.
- Worker threads process sine‐wave “partials” in parallel, using either OS workgroups (iOS 14+) or private APIs (iOS 13).
- Busy threads run low‐priority loops to manipulate the performance controller.
- UI allows toggling presets, buffer sizes, thread counts, work interval, busy‐thread parameters, and visualizations of load, cores, work distribution, and energy.

##### Main components and relationships
a. Components
- UI Layer (Swift + Storyboards + View subclasses)
- Audio Engine (Engine.mm, ParallelSineBank, Partial.cpp)
- Base Library (threading, synchronization, queueing, workgroup support)
- CoreAudio / Workgroup API (external iOS frameworks)
- Busy Threads subsystem
- Visualizations (data collectors + drawing code in Swift)
- User settings / Controls (PresetChooser, Sliders)
b. Interactions
1. User taps UI controls → Swift controllers update Engine configuration (buffer size, thread counts, presets).
2. Engine initializes CoreAudio I/O (AudioHost in Base) → driver thread callback fires each buffer period.
3. Driver thread delegates processing tasks to worker threads, managed by Base’s thread and queue classes.
4. Worker threads execute DSP (ParallelSineBank → Partial computations) and report timing metrics back to Engine.
5. Busy Threads run independently, calling Base primitives to modulate CPU load/energy.
6. Engine collects metrics (per‐thread timing, core scheduling, energy estimates) and forwards them to Swift UI.
7. UI renders visualizations (load graph, cores, energy, distribution) based on data stream.
c. Architectural patterns & principles
- Separation of concerns: Swift UI vs. C++ DSP vs. threading/OS integration.
- Producer‐consumer pattern: driver thread publishes tasks to a lock‐free queue (Base::FixedSPSCQueue), worker threads consume.
- Bridge pattern: Objective‐C++ bridging between Swift and C++.
- Strategy for managing real‐time threads: configurable driver mode, work interval vs. busy threads.
d. Key technologies
- Swift + UIKit/Storyboards for UI
- Objective‐C++ and C++17 for DSP/engine (`.mm` files, Standard Library)
- CoreAudio / AudioToolbox for audio I/O
- Custom Base library (threads, semaphores, work intervals)
- iOS Workgroup API (AudioToolbox workgroup_management) or private API fallback
- Low‐level synchronization (condition variables, semaphores)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraphs for layers
    subgraph "UI Layer"
        direction TB
        AV["ActivityView.swift"]:::ui
        AD["AppDelegate.swift"]:::ui
        CTVH["CollapsibleTableViewHeader.swift"]:::ui
        DIV["DisclosureIndicatorView.swift"]:::ui
        PC["PresetChooser.swift"]:::ui
        SWV["SliderWithValue.swift"]:::ui
        VOS["VisualizationsOnSwitch.swift"]:::ui
        VC["ViewController.swift"]:::ui
        MV["MeterView.swift"]:::ui
        MS["MeterSmoother.swift"]:::ui
        ASSETS["Assets.xcassets"]:::ui
        STORY1["Base.lproj/Main.storyboard"]:::ui
        STORY2["Base.lproj/LaunchScreen.storyboard"]:::ui
    end

    subgraph "Engine Layer"
        direction TB
        EHH["Engine.hpp"]:::audio
        EMM["Engine.mm"]:::audio
        PSH["ParallelSineBank.hpp"]:::audio
        PSC["ParallelSineBank.cpp"]:::audio
        PAH["Partial.hpp"]:::audio
        PAC["Partial.cpp"]:::audio
        CH["Constants.hpp"]:::audio
        Driver["Engine: Driver Thread"]:::audio
        Workers["DSP Workers (ParallelSineBank)"]:::audio
        Metrics["Metric Aggregator"]:::audio
    end

    subgraph "Base Library"   
        direction TB
        TH["Thread.hpp"]:::util
        TC["Thread.cpp"]:::util
        SH["Semaphore.hpp"]:::util
        SC["Semaphore.cpp"]:::util
        QH["FixedSPSCQueue.hpp"]:::util
        DH["Driver.hpp"]:::util
        DM["Driver.mm"]:::util
        AH["AudioHost.hpp"]:::util
        AC["AudioHost.cpp"]:::util
        AWH["AudioWorkgroup.hpp"]:::util
        AWM["AudioWorkgroup.mm"]:::util
        BH["BusyThreads.hpp"]:::util
        BC["BusyThreads.cpp"]:::util
    end

    subgraph "OS / External Services"
        direction TB
        CoreAudio["CoreAudio I/O"]:::ext
        WorkgroupAPI["iOS Workgroup API"]:::ext
        Scheduler["iOS Scheduler / Perf Controller"]:::ext
    end

    %% Connections
    PC -->|"configures"| EHH
    SWV -->|"configures"| EHH
    CTVH -->|"configures"| EHH
    DIV -->|"configures"| EHH
    AV -->|"visualizes metrics"| Metrics
    MV -->|"renders metrics"| Metrics
    MS -->|"smooths data"| Metrics
    VOS -->|"toggles viz"| Metrics
    EMM -->|"register callback"| AH
    AH -->|"uses"| CoreAudio
    AH -->|"manages workgroups"| AWH
    Driver -->|"spawns"| Workers
    Workers -->|"enqueue tasks on"| QH
    QH -->|"synchronizes"| TH
    BH -->|"loads CPU via"| Scheduler
    Metrics -->|"forwards metrics to"| VC
    CoreAudio -->|"drives callback to"| Driver

    %% Click Events
    click AV "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/ActivityView.swift"
    click AD "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/AppDelegate.swift"
    click CTVH "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/CollapsibleTableViewHeader.swift"
    click DIV "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/DisclosureIndicatorView.swift"
    click PC "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/PresetChooser.swift"
    click SWV "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/SliderWithValue.swift"
    click VOS "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/VisualizationsOnSwitch.swift"
    click VC "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/ViewController.swift"
    click MV "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/MeterView.swift"
    click MS "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/MeterSmoother.swift"
    click ASSETS "https://github.com/ableton/audioperflab/tree/main/AudioPerfLab/Assets.xcassets/"
    click STORY1 "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/Base.lproj/Main.storyboard"
    click STORY2 "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/Base.lproj/LaunchScreen.storyboard"
    click EHH "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/Engine.hpp"
    click EMM "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/Engine.mm"
    click PSH "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/ParallelSineBank.hpp"
    click PSC "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/ParallelSineBank.cpp"
    click PAH "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/Partial.hpp"
    click PAC "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/Partial.cpp"
    click CH "https://github.com/ableton/audioperflab/blob/main/AudioPerfLab/Constants.hpp"
    click TH "https://github.com/ableton/audioperflab/blob/main/Base/Thread.hpp"
    click TC "https://github.com/ableton/audioperflab/blob/main/Base/Thread.cpp"
    click SH "https://github.com/ableton/audioperflab/blob/main/Base/Semaphore.hpp"
    click SC "https://github.com/ableton/audioperflab/blob/main/Base/Semaphore.cpp"
    click QH "https://github.com/ableton/audioperflab/blob/main/Base/FixedSPSCQueue.hpp"
    click DH "https://github.com/ableton/audioperflab/blob/main/Base/Driver.hpp"
    click DM "https://github.com/ableton/audioperflab/blob/main/Base/Driver.mm"
    click AH "https://github.com/ableton/audioperflab/blob/main/Base/AudioHost.hpp"
    click AC "https://github.com/ableton/audioperflab/blob/main/Base/AudioHost.cpp"
    click AWH "https://github.com/ableton/audioperflab/blob/main/Base/AudioWorkgroup.hpp"
    click AWM "https://github.com/ableton/audioperflab/blob/main/Base/AudioWorkgroup.mm"
    click BH "https://github.com/ableton/audioperflab/blob/main/Base/BusyThreads.hpp"
    click BC "https://github.com/ableton/audioperflab/blob/main/Base/BusyThreads.cpp"

    %% Styles
    classDef ui fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef audio fill:#ffcdd2,stroke:#e53935,color:#b71c1c
    classDef util fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef ext fill:#e0e0e0,stroke:#757575,color:#424242
```
