# daft-engineers/vocoder architecture

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

- Interactive diagram: https://gitdiagram.com/daft-engineers/vocoder
- Repository: https://github.com/daft-engineers/vocoder

## Overview

##### Project type and purpose
- It captures voice + synth inputs, applies filtering/envelope-follower + modulation, mixes and outputs audio in real time.

##### File structure
- Top-level build/config: CMakeLists.txt, setup.sh, checks.sh, .github/workflows (CI), Doxyfile.
- /: public headers for each DSP block (amp.hh, filter.hh, rms.hh, mixer.hh, pipe.hh, scheduler_helper.hh, callbacks.hh, audio.hh, alsa_out.hh).
- src/: implementation of main.cc, DSP modules, ALSA I/O.
- unit_tests/: Python linker helper + GoogleTest suites for every DSP block.

##### README for additional insights
- Hardware: Raspberry Pi + Codec Zero (ALSA device).
- Software stack: C++11, CMake, ALSA, GoogleTest, clang-tidy/format, doxygen/graphviz.

##### Main components & data flows
a. Hardware Layer
– Codec Zero analog I/O (mic + synth inputs, headphone/speaker out)
– ALSA kernel driver
b. Audio I/O Layer
– include/alsa_out.hh & src/alsa_out.cc
– audio.hh: defines AudioBuffer, sample formats, device selection
c. Scheduler & Callbacks
– scheduler_helper.hh & callbacks.hh
– Drive the real-time audio loop: register input/output callbacks with ALSA
d. DSP Processing Pipeline
1. pipe.hh: lock-free FIFO buffers for inter-module data passing
2. filter.cc / filter.hh: bank of IIR filters (via Bernd Porr’s iir1)
3. rms.cc / rms.hh: envelope follower to compute RMS of voice
4. amp.cc / amp.hh: apply gain/envelope modulation to synth
5. mixer.cc / mixer.hh: mix modulated synth + original voice (if desired)
e. Application Entry Point
– src/main.cc: parse CLI args (-i, ‑o, ‑g), assemble modules, start scheduler
f. Build/Test/CI
– CMake + Python script to link tests
– checks.sh: clang-tidy/clang-format
– .github/workflows: build, static analysis, unit tests, nightly threaded tests, doxygen deploy

##### Architectural patterns & principles
- Modular DSP blocks with single responsibility (filter, rms, amp, mixer)
- Callback-driven scheduling for real-time processing
- Lock-free circular buffers (pipe.hh) to decouple I/O from DSP
- Clear separation: I/O vs. scheduling vs. DSP vs. CLI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware & OS Layer
    subgraph "Hardware & OS" 
        direction TB
        Codec["Codec Zero (Analog I/O)"]:::hardware
        ALSA_Driver["ALSA Kernel Driver"]:::hardware
    end

    %% Audio I/O Layer
    subgraph "Audio I/O" 
        direction TB
        AlsaOut["ALSA I/O Module\n(alsa_out)"]:::io
        AudioDefs["Audio Definitions\n(audio.hh)"]:::io
    end

    %% Scheduler & Callbacks Layer
    subgraph "Scheduler & Callbacks"
        direction TB
        SchedulerHelper["Scheduler Helper\n(scheduler_helper)"]:::scheduler
        Callbacks["Callback Manager\n(callbacks)"]:::scheduler
    end

    %% DSP Processing Pipeline
    subgraph "DSP Pipeline"
        direction TB
        PipeBuf["Lock-free FIFO Buffers\n(pipe)"]:::dsp
        Filter["IIR Filter Bank\n(filter)"]:::dsp
        RMS["Envelope Follower (RMS)\n(rms)"]:::dsp
        Amp["Amplifier & Modulator\n(amp)"]:::dsp
        Mixer["Mixer\n(mixer)"]:::dsp
    end

    %% Application & CLI
    subgraph "Application Entry Point"
        direction TB
        MainApp["Main Application\n(main.cc)"]:::app
    end

    %% CI/CD Side Lane
    subgraph "CI/CD & Testing"
        direction TB
        CMakeRoot["CMakeLists.txt"]:::cicd
        CMakeSrc["src/CMakeLists.txt"]:::cicd
        Checks["checks.sh"]:::cicd
        Setup["setup.sh"]:::cicd
        Workflow1[".github/workflows/action.yml"]:::cicd
        Workflow2[".github/workflows/nightly.yml"]:::cicd
        UnitTests["unit_tests/"]:::cicd
        Doxy["Doxyfile"]:::cicd
        Clang[".clang-tidy / .clang-format"]:::cicd
    end

    %% Data Flows
    Codec --> ALSA_Driver
    ALSA_Driver -->|"capture callback"| AlsaOut
    AlsaOut -->|"registers IO callbacks"| SchedulerHelper
    SchedulerHelper --> Callbacks
    Callbacks -->|"voice & synth streams"| PipeBuf
    PipeBuf -->|"voice stream"| Filter
    Filter --> RMS
    RMS -->|"envelope data"| Amp
    PipeBuf -->|"synth stream"| Amp
    Amp --> Mixer
    Mixer -->|"playback callback"| Callbacks
    Callbacks --> ALSA_Driver

    %% Application wiring
    MainApp --> AlsaOut
    MainApp --> SchedulerHelper
    MainApp --> PipeBuf
    MainApp --> Filter
    MainApp --> RMS
    MainApp --> Amp
    MainApp --> Mixer

    %% CI/CD relations
    CMakeRoot --> CMakeSrc
    CMakeRoot --> UnitTests
    CMakeRoot --> Checks
    CMakeRoot --> Setup
    CMakeRoot --> Workflow1
    CMakeRoot --> Workflow2
    CMakeRoot --> Doxy
    CMakeRoot --> Clang

    %% Click Events for component mappings
    click AlsaOut "https://github.com/daft-engineers/vocoder/blob/main/src/alsa_out.cc"
    click AudioDefs "https://github.com/daft-engineers/vocoder/blob/main/include/audio.hh"
    click SchedulerHelper "https://github.com/daft-engineers/vocoder/blob/main/include/scheduler_helper.hh"
    click SchedulerHelper "https://github.com/daft-engineers/vocoder/blob/main/src/scheduler_helper.cc"
    click Callbacks "https://github.com/daft-engineers/vocoder/blob/main/include/callbacks.hh"
    click Callbacks "https://github.com/daft-engineers/vocoder/blob/main/src/callbacks.cc"
    click PipeBuf "https://github.com/daft-engineers/vocoder/blob/main/include/pipe.hh"
    click Filter "https://github.com/daft-engineers/vocoder/blob/main/include/filter.hh"
    click Filter "https://github.com/daft-engineers/vocoder/blob/main/src/filter.cc"
    click RMS "https://github.com/daft-engineers/vocoder/blob/main/include/rms.hh"
    click RMS "https://github.com/daft-engineers/vocoder/blob/main/src/rms.cc"
    click Amp "https://github.com/daft-engineers/vocoder/blob/main/include/amp.hh"
    click Amp "https://github.com/daft-engineers/vocoder/blob/main/src/amp.cc"
    click Mixer "https://github.com/daft-engineers/vocoder/blob/main/include/mixer.hh"
    click MainApp "https://github.com/daft-engineers/vocoder/blob/main/src/main.cc"
    click CMakeRoot "https://github.com/daft-engineers/vocoder/blob/main/CMakeLists.txt"
    click CMakeSrc "https://github.com/daft-engineers/vocoder/blob/main/src/CMakeLists.txt"
    click Checks "https://github.com/daft-engineers/vocoder/blob/main/checks.sh"
    click Setup "https://github.com/daft-engineers/vocoder/blob/main/setup.sh"
    click Workflow1 "https://github.com/daft-engineers/vocoder/blob/main/.github/workflows/action.yml"
    click Workflow2 "https://github.com/daft-engineers/vocoder/blob/main/.github/workflows/nightly.yml"
    click UnitTests "https://github.com/daft-engineers/vocoder/tree/main/unit_tests/"
    click Doxy "https://github.com/daft-engineers/vocoder/tree/main/Doxyfile"
    click Clang "https://github.com/daft-engineers/vocoder/blob/main/.clang-tidy"

    %% Styles
    classDef hardware fill:#ccf,stroke:#000
    classDef io fill:#fdb,stroke:#000
    classDef scheduler fill:#fdc,stroke:#000
    classDef dsp fill:#cfc,stroke:#000
    classDef app fill:#dcf,stroke:#000
    classDef cicd fill:#fcf,stroke:#000
```
