nimplug

Audio plugin development in Nim.

nimplug is an early-stage Nim audio plugin library built on CPLUG (C99), enabling developers to write VST3, CLAP, and AUv2 plugins in pure Nim with no C++ dependency.

Status: Early development. APIs are subject to change. Not recommended for production use. DSP components have not been independently verified for numerical correctness — validate thoroughly for your use case.

Features

• Unified Plugin Wrapper: Generates VST3, CLAP, AUv2, and standalone formats from a single code definition via a robust CPLUG integration.
• Type-Safe Parameters: Declarative defParams macro generates per-field atomic storage (ParamStore[N]) and host automation bridges.
• Modern DSP & Audio Library:
  • Allocation-free, sample-rate-aware components: oscillators, biquad and ZDF SVF filters, ADSR envelopes, polyblep-corrected waveforms, FFT, dynamics, distortion, oversampling, delay lines.
  • SIMD acceleration via nimsimd (AVX2 on amd64, NEON on arm64).
  • Sample-accurate MIDI event tracking with in-place buffer mutation.
  • Streaming audio file I/O (WAV / MP3 / FLAC) with a dedicated reader thread.
• Hierarchical State:
  • JUCE-inspired ValueTree with property listeners and parent / child traversal.
  • Bounded UndoManager with action coalescing.
  • PresetManager with a dual JSON / binary (flatty + zippy) format, both gzip-compressed via zippy.
• Real-Time Safe Concurrency:
  • Wait-free Sipsic SPSC queues, coalescing AsyncUpdater, and TimerManager.
  • PluginTaskpool (backed by nim-taskpools) for finite background work.
  • The withAudioThread template that flips a thread-local flag the sandbox relay checks.
• Two GUI Backends (selectable at compile time with -d:feature.nimplug.uirelaysgui or -d:feature.nimplug.figdrawgui):
  • uirelays: immediate-mode, custom-painted widgets. GPU-accelerated rendering via the figdraw driver.
  • figdraw: retained-mode, component tree with CSS Flexbox / Grid layout. Hardware-accelerated rendering.
• Compile-time Features: Optional capabilities enabled via -d:feature.nimplug.* flags — SIMD (feature.nimplug.simd), FFT (feature.nimplug.fft), audio file I/O (feature.nimplug.audioio), background task pool (feature.nimplug.taskpool), binary presets (feature.nimplug.binarypresets), and GPU shaders (feature.nimplug.shader).
• SVG, Image, and Vector Asset Pipeline: load SVGs, PNGs, JPEGs, GIFs, and WebP images; draw bezier curves, elliptical arcs, and polygon paths; radial, angular, and linear gradients with multiple color stops; rich text spans with individual font/color per span.
• Image Operations: blur, drop shadow, resize, flip, and rotate on pixel images.
• Relay Layer: a decoupled boundary between Nimplug and CPLUG that makes the user-facing API testable without a DAW.

Quick Start

Prerequisites

• Nim >= 2.0.0 — nim-lang.org
• C compiler — clang (macOS), gcc / clang (Linux), clang on Windows
• Atlas — for dependency management: atlas.nim
• macOS frameworks — Cocoa, Metal, MetalKit (for macOS GUI builds)

Install

atlas init
atlas install

Build a plugin

cd examples/gain/gain
nim buildClap

The CLAP bundle is now in build/gain.clap. Move it to your DAW's plugin directory (~/Library/Audio/Plug-Ins/CLAP/ on macOS, %LOCALAPPDATA%\Programs\Common\CLAP\ on Windows, ~/.clap/ on Linux) to install.

Write your own

Start with the Getting Started tutorial and progress through the rest of the tutorials. The architecture docs are for contributors and people extending the framework.

Documentation

Tutorials

1. Getting Started
2. DSP and Parameters
3. uirelays GUI
4. Figdraw Custom GUI
5. MIDI Processing
6. Audio File I/O
7. State Management
8. Concurrency
9. Relay Testing
10. SVG Assets

Architecture

• Overview
• Core Plugin Macro
• Plugin Lifecycle
• Parameters
• Relays
• DSP Components
• Animation
• MIDI
• State Management
• State I/O and Serialization
• Concurrency
• Real-Time Safety
• GUI Architecture
• uirelays GUI
• Datatypes and Memory
• Formats and I/O
• External Libraries
• Build System
• Contributing

Contributing

See the Contributing Guide for module layout, how to add a new relay / DSP component / widget / example, the test conventions, and the per-example README template. For AI assistants, see AGENTS.md.

License

MIT. See LICENSE for terms.