# robbert-vdh/nih-plug architecture

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

- Interactive diagram: https://gitdiagram.com/robbert-vdh/nih-plug
- Repository: https://github.com/robbert-vdh/nih-plug

## Overview

##### Project type and purpose
This is a multi-crate Rust “monorepo” that provides:
– An API-agnostic audio plugin framework (core library)
– A derive-macro crate for declarative parameter definitions
– Adapters for Rust GUI toolkits (egui, iced, VIZIA)
– A cargo subcommand (xtask) for building/bundling plugins
– A collection of example and production audio plugins
It targets both DAWs (via VST3 and CLAP) and standalone executables (JACK, CPAL).

##### File structure
– Top-level crates:
- src/                     → core framework (audio processing, params, wrappers)
- nih_plug_derive/         → proc-macro crate generating Params trait impls
- nih_plug_egui/, _iced/, _vizia/ → GUI adapter crates for each toolkit
- cargo_nih_plug/          → cargo subcommand plugin installer
- nih_plug_xtask/          → “xtask” CLI for bundling and cross-compiling
- plugins/                 → real and example plugin crates
– Build & CI: .github/workflows, Cargo.toml workspace, bundler.toml
– Wrappers: under src/wrapper, split by target (clap, vst3, standalone backends)

##### README for insights
– Core features (VST3/CLAP export macros, standalone binary CLI, param system, background-tasks)
– Supported toolkits (egui, iced, VIZIA)
– Build instructions (cargo xtask bundle)
– Example plugins to learn from

1. Cargo Workspace & Build System
2. Core Framework Crate (“nih_plug” library)
- Audio processing modules (buffer iterators, FFT adapters)
- Parameter system (Params trait, smoothers, persistence)
- Background-task runner
- MIDI & note-expression handling
- Wrapper layer(s) for VST3 / CLAP / standalone (CPAL, JACK, dummy)
3. Proc-Macro Crate (nih_plug_derive)
4. GUI Adapter Crates
- nih_plug_egui → Egui widgets & editor glue
- nih_plug_iced → Iced widgets & editor glue
- nih_plug_vizia → VIZIA widgets & styling
5. XTask Bundler & Cargo Subcommand
- cargo_nih_plug → installs as `cargo nih-plug`
- nih_plug_xtask → `cargo xtask bundle` logic, detects formats & targets
6. Plugin Crates
- plugins/examples/...
- plugins/[buffr_glitch, crisp, ...]
7. External Systems
- Host DAWs (via VST3, CLAP)
- Audio backends (JACK, CPAL)
- Filesystem / CLI

– Plugin Crates → depend on → Core Framework Crate & Proc-Macro Crate
– Proc-Macro Crate → code-generation → Core Framework & Plugin Crates
– Plugin Crates + GUI Adapter Crates → optional UI panels → Core Framework
– XTask Bundler → reads Cargo.toml + plugin targets → drives → build system → outputs plugin bundles
– Core Framework Wrappers → expose C ABI → consumed by → DAW hosts (VST3/CLAP)
– Standalone Wrapper → links CPAL/JACK → runs as CLI binary

c. Architectural patterns & design principles
– Modular, layered architecture: macro layer, core library layer, adapter layer, application layer
– Plugin-pattern: user code implements `Plugin` trait, exported via `nih_export_<api>!` macros
– Proc-macros for zero-boilerplate parameter derivation
– Separation of concerns: audio processing vs. GUI vs. hosting vs. bundling

d. Technologies & frameworks
– Rust & Cargo workspace
– Proc-macro (nih_plug_derive)
– VST3-sys (GPLv3), CLAP
– CPAL, JACK (standalone)
– GUI: egui, iced, VIZIA
– CLI: structopt or clap (in xtask)

## Diagram (Mermaid)

```mermaid
flowchart TD
    title["NIH-plug Architecture Overview"]

    %% Build Tools & Workspace
    subgraph "Build Tools & Workspace"
        Workspace["Cargo Workspace & Build System"]:::purple
    end

    %% Macro & Framework
    subgraph "Macro & Framework"
        Macro["Proc-Macro Crate\n(nih_plug_derive)"]:::blue
        Framework["Core Framework Crate\n(nih_plug)"]:::blue
    end

    %% Wrapper Modules
    subgraph "Wrapper Modules"
        WrapperCore["Wrapper Modules"]:::green
    end

    %% GUI Adapters
    subgraph "GUI Adapter Crates"
        Egui["nih_plug_egui"]:::green
        Iced["nih_plug_iced"]:::green
        Vizia["nih_plug_vizia"]:::green
    end

    %% Plugin Crates
    subgraph "Plugin Crates"
        Plugins["Plugin Crates\n(examples & production)"]:::orange
    end

    %% XTask & Cargo Subcommand
    subgraph "XTask & Cargo Subcommand"
        CargoCmd["cargo_nih_plug\n(Cargo subcommand)"]:::purple
        XTask["nih_plug_xtask\n(xtask bundler)"]:::purple
    end

    %% External Systems
    subgraph "External Systems"
        DAW["Host DAWs\n(VST3/CLAP)"]:::gray
        Backend["Audio Backends\n(CPAL, JACK)"]:::gray
    end

    %% Relationships
    Macro -->|"generates code for"| Framework
    Macro -->|"generates macros for"| Plugins
    Plugins -->|"depends on"| Framework
    Plugins -->|"uses derive macros"| Macro

    Plugins -->|"optional UI panels"| Egui
    Plugins -->|"optional UI panels"| Iced
    Plugins -->|"optional UI panels"| Vizia

    Framework -->|"provides core APIs"| WrapperCore
    WrapperCore -->|"exports C ABI"| DAW
    WrapperCore -->|"links to backends"| Backend

    CargoCmd -->|"installs as cargo plugin"| Workspace
    XTask -->|"reads workspace manifest"| Workspace
    XTask -->|"bundles plugins"| Plugins
    XTask -->|"drives build pipeline"| Framework

    %% Click Events
    click Workspace "https://github.com/robbert-vdh/nih-plug/blob/master/Cargo.toml"
    click Macro "https://github.com/robbert-vdh/nih-plug/blob/master/nih_plug_derive/src/lib.rs"
    click Framework "https://github.com/robbert-vdh/nih-plug/blob/master/src/lib.rs"
    click WrapperCore "https://github.com/robbert-vdh/nih-plug/blob/master/src/wrapper.rs"
    click Egui "https://github.com/robbert-vdh/nih-plug/blob/master/nih_plug_egui/src/lib.rs"
    click Iced "https://github.com/robbert-vdh/nih-plug/blob/master/nih_plug_iced/src/lib.rs"
    click Vizia "https://github.com/robbert-vdh/nih-plug/blob/master/nih_plug_vizia/src/lib.rs"
    click CargoCmd "https://github.com/robbert-vdh/nih-plug/blob/master/cargo_nih_plug/src/main.rs"
    click XTask "https://github.com/robbert-vdh/nih-plug/blob/master/nih_plug_xtask/src/lib.rs"

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#005B9A,color:#003F6B
    classDef green fill:#DFF5D6,stroke:#2E7D32,color:#1B5E20
    classDef orange fill:#FFE0B2,stroke:#F57C00,color:#E65100
    classDef purple fill:#E1BEE7,stroke:#6A1B9A,color:#4A148C
    classDef gray fill:#F5F5F5,stroke:#9E9E9E,color:#424242
```
