API-agnostic audio plugin framework written in Rust

Overview

NIH-plug

Automated builds Tests Docs

This is a work in progress API-agnostic audio plugin framework written in Rust to do some experiments with, as well as a small collection of plugins. The idea is to have a statefull but simple plugin API that gets rid of as much unnecessary ceremony wherever possible, while also keeping the amount of magic to minimum. Since this is not quite meant for general use just yet, the plugin API surface is currently limited to the functionality that I either needed myself or that was requested by others. See the current features section for more information on the project's current status.

Come join us on the Rust Audio Discord, or check out the documentation (work in progress).

Table of contents

Plugins

Check each plugin's readme for more details on what the plugin actually does and for download links.

  • Crisp adds a bright crispy top end to any low bass sound. Inspired by Polarity's Fake Distortion video.
  • Diopser is a totally original phase rotation plugin. Useful for oomphing up kickdrums and basses, transforming synths into their evil phase-y cousin, and making everything sound like a cheap Sci-Fi laser beam.
  • Puberty Simulator is that patent pending One Weird Plugin that simulates the male voice change during puberty! If it was not already obvious from that sentence, this plugin is a joke, but it might actually be useful (or at least interesting) in some situations. This plugin pitches the signal down an octave, but it also has the side effect of causing things to sound like a cracking voice or to make them sound slightly out of tune.

Framework

Current features

  • Supports both VST3 and CLAP by simply adding the corresponding nih_export_!(Foo) macro to your plugin's library.
  • Standalone binaries can be made by calling nih_export_standalone(Foo) from your main() function.
  • Declarative parameter handling without any boilerplate.
    • Define parameters for your plugin by adding FloatParam, IntParam, BoolParam, and EnumParam fields to your parameter struct, assign stable IDs to them with the #[id = "foobar"], and a #[derive(Params)] does all of the boring work for you.
    • Parameters can have complex value distributions and the parameter objects come with built-in smoothers and callbacks.
    • Use simple enums deriving the Enum trait with the EnumParam parameter type for parameters that allow the user to choose between multiple discrete options. That way you can use regular Rust pattern matching when working with these values without having to do any conversions yourself.
    • Store additional non-parameter state for your plugin by adding any field that can be serialized with Serde to your plugin's Params object and annotating them with #[persist = "key"].
    • Group your parameters into logical groups by nesting Params objects using the #[nested = "Group Name"]attribute.
    • When needed, you can also provide your own implementation for the Params trait to enable dynamically generated parameters and arrays of if mostly identical parameter objects.
  • Stateful. Behaves mostly like JUCE, just without all of the boilerplate.
  • Does not make any assumptions on how you want to process audio, but does come with utilities and adapters to help with common access patterns.
    • Efficiently iterate over an audio buffer either per-sample per-channel, per-block per-channel, or even per-block per-sample-per-channel with the option to manually index the buffer or get access to a channel slice at any time.
    • Easily leverage per-channel SIMD using the SIMD adapters on the buffer and block iterators.
    • Comes with bring-your-own-FFT adapters for common (inverse) short-time Fourier Transform operations. More to come.
  • Optional sample accurate automation support for VST3 and CLAP that can be enabled by setting the Plugin::SAMPLE_ACCURATE_AUTOMATION constant to true.
  • Comes with adapters for popular Rust GUI frameworks as well as some basic widgets for them that integrate with NIH-plug's parameter system. Currently there's support for egui, iced and VIZIA.
    • A simple and safe API for state saving and restoring from the editor is provided by the framework if you want to do your own internal preset management.
  • Full support for receiving and outputting both modern polyphonic note expression events as well as MIDI CCs, channel pressure, and pitch bend for CLAP and VST3.
  • A plugin bundler accessible through the cargo xtask bundle command that automatically detects which plugin targets your plugin exposes and creates the correct plugin bundles for your target operating system and architecture, with cross-compilation support. The cargo subcommand can easily be added to your own project as an alias or globally as a regular cargo subcommand.
  • Tested on Linux and Windows, with limited testing on macOS. Windows support has mostly been tested through Wine with yabridge.
  • See the Plugin trait's documentation for an incomplete list of the functionlaity that has currently not yet been implemented.

Building

NIH-plug works with the latest stable Rust compiler.

After installing Rust, you can compile any of the plugins in the plugins directory in the following way, replacing gain with the name of the plugin:

cargo xtask bundle gain --release

Plugin formats

NIH-plug can currently export VST3 and CLAP plugins. Exporting a specific plugin format for a plugin is as simple as calling the nih_export_!(Foo); macro. The cargo xtask bundle commane will detect which plugin formats your plugin supports and create the appropriate bundles accordingly, even when cross compiling.

Example plugins

The best way to get an idea for what the API looks like is to look at the examples.

  • gain is a simple smoothed gain plugin that shows off a couple other parts of the API, like support for storing arbitrary serializable state.
  • gain-gui is the same plugin as gain, but with a GUI to control the parameter and a digital peak meter. Comes in three exciting flavors: egui, iced, and VIZIA.
  • midi-inverter takes note/MIDI events and flips around the note, channel, expression, pressure, and CC values. This example demonstrates how to receive and output those events.
  • sine is a simple test tone generator plugin with frequency smoothing that can also make use of MIDI input instead of generating a static signal based on the plugin's parameters.
  • stft shows off some of NIH-plug's other optional higher level helper features, such as an adapter to process audio with a short-term Fourier transform using the overlap-add method, all using the compositional Buffer interfaces.

Licensing

The framework, its libraries, and the example plugins in plugins/examples/ are all licensed under the ISC license. However, the VST3 bindings used by nih_export_vst3!() are licensed under the GPLv3 license. This means that unless you replace these bindings with your own bindings made from scratch, any VST3 plugins built with NIH-plug need to be able to comply with the terms of the GPLv3 license.

The other plugins in the plugins/ directory may be licensed under the GPLv3 license. Check the plugin's Cargo.toml file for more information.

Comments
  • Implementing the Param trait

    Implementing the Param trait

    Use case + Background info

    I have recently come upon a few use cases where I found that the Param implementations included with nih-plug are not super well-suited, so I wanted to implement a custom Param.

    However, I found a few things that I did not expect: The as_ptr method requires me to construct a ParamPtr instance, which is not possible for fully custom implementations since the possible types of parameters are hard-coded in nih-plug. Still, as I was delegating a bit of my Params basic functionality to an IntParam anyway, I could return something like self.inner.as_ptr() here.

    Next, I found that a few methods from my Param implementation were never called (normalized_value_to_string, string_to_normalized_value). As far as I see, these are only ever called through ParamPtr - so even though I have to provide these functions, they are never used. For my concrete case, I could also hack around this by customizing my underlying IntParam using with_value_to_string and with_string_to_value.

    The actual questions

    Implementing Param out-of-tree seems rather unergonomic to me. Am I missing some obvious alternative here? Is this currently an intended use of Param at all?

    opened by sleiner 8
  • Smoothing code is quite expensive

    Smoothing code is quite expensive

    Looking through the code, it appears that this if statement is executed every single frame for every single parameter:

    https://github.com/robbert-vdh/nih-plug/blob/master/src/param/smoothing.rs#L198

    It would be better if somehow this if statement is only executed once per parameter per process cycle.

    I still vouch for baseplug's method which is to fill a buffer with smoothed values for each parameter beforehand. I can help you with it if you want.

    https://github.com/wrl/baseplug/blob/trunk/src/smooth.rs#L47

    opened by BillyDM 8
  • plug_xtask: Fixup update of existing package bundle for MacOS

    plug_xtask: Fixup update of existing package bundle for MacOS

    It seems that MacOS is caching the old executable when we attempt to replace the binary. It looks like it requires the whole .app be deleted and replaced in order to run a new compilation.

    opened by spwilson2 7
  • Translate db_to_gain before smoothing the parameter

    Translate db_to_gain before smoothing the parameter

    You should definitely add the ability for a parameter to translate its value using util::db_to_gain before smoothing it.

    The current gain example is woefully inefficient since it is converting from db to gain every single sample:

    for channel_samples in buffer.iter_samples() {
        // Smoothing is optionally built into the parameters themselves
        let gain = self.params.gain.smoothed.next();
    
        for sample in channel_samples {
            *sample *= util::db_to_gain(gain);
        }
    }
    

    This is how baseplug implements this: https://github.com/wrl/baseplug/blob/trunk/src/parameter.rs#L116

    opened by BillyDM 6
  • VST3 not recognized in Ableton on Mac M1

    VST3 not recognized in Ableton on Mac M1

    Hi, thank you for making free plugins, I'd like to try them. I found a link from a youtube video and tried to install on my MacBook Pro M1 with Ableton Live 11 and Ableton Live 10 and neither one showed the plugins in Ableton's browser. I followed Ableton's help instructions and none of them worked, do you know what might be wrong? Thanks

    help wanted 
    opened by goggledefogger 6
  • "Typo" in documentation for range of midi channel

    This is a bit of a smart ass "issue" but in "https://github.com/robbert-vdh/nih-plug/blob/master/src/midi.rs" the channel of NoteEvent (For messages that have a channel) is declared as:

        /// The note's channel, from 0 to 16.
        channel: u8,
    

    It should probably read 0 to 15 (4-Bit) if it is zero based or 1-16. From my experience it is zero based.

    https://www.cs.cmu.edu/~music/cmsip/readings/MIDI%20tutorial%20for%20programmers.html

    opened by soerensen3 5
  • [Question] How to add logging to a plugin?

    [Question] How to add logging to a plugin?

    What's the best way to add logging (to a log file) to a plugin? I tried the following, which works with rust vst2 (adapted from https://github.com/DGriffin91/egui_baseview_test_vst2). It creates the log file, but doesn't log anything to it:

    use simplelog::{Config};
    
    pub(crate) fn init(name: String, version: i32) {
        if let Some(local_dir) = dirs::data_local_dir() {
            // check if clockwork-vst folder exists, if not create it
            let mut path = local_dir.clone();
            path.push("clockwork-vst");
            path.push("logs");
            if !path.exists() {
                std::fs::create_dir_all(&path).ok();
            }
    
            let logging_dir = path.clone();
            if logging_dir.exists() {
                let filename = format!("{name}-{version}-log.txt");
                let log_file_path = logging_dir.join(filename);
    
                if let Ok(log_file) = std::fs::OpenOptions::new()
                    .append(true)
                    .create(true)
                    .open(&log_file_path)
                {
                    simplelog::WriteLogger::init(simplelog::LevelFilter::Info, Config::default(), log_file)
                        .ok();
                    log_panics::init();
                    log::info!("Starting VST");
    
                } else {
                    panic!("Could not open log file");
                }
            }
        }
    }
    
    opened by AlexW00 5
  • [macOS] [gain_gui] Wrong Cursor Position

    [macOS] [gain_gui] Wrong Cursor Position

    OS: macOS 12.2.1 DAW: REAPER 6.49

    First of all, thank you for building this framework. It looks very cool.

    I wanted to try out gain_gui, so I built it using cargo xtask bundle gain_gui --release --bundle-vst3, then copied target/gain_gui.vst3 to /Library/Audio/Plug-Ins/VST3.

    While the plugin works, the cursor position appears to be off. This is most obvious with the slider, which isn't draggable unless I drag on a specific spot below the handle. Maybe a scaling issue?

    https://user-images.githubusercontent.com/4495237/155819619-16238ac4-b580-4ccf-827a-3e09e10bee58.mov

    I understand that this stuff hasn't been tested on macOS, so feel free to close this issue if it's not actionable :)

    opened by apalm 5
  • Make skew_factor functions const

    Make skew_factor functions const

    The skew_factor functions inside of FloatRange are not currently const. This means they can't be used when creating FloatRange's in a const context, meaning they can't be used for FloatRange::Reversed.

    Minimum reproduction:

    use nih_plug::prelude::*;
    use std::sync::Arc;
    
    static RATIO_RANGE: FloatRange = FloatRange::Skewed {
        min: 0.0,
        max: 1.0,
        factor: FloatRange::skew_factor(-1.0),
    };
    
    #[derive(Params)]
    struct PluginParams {
        pub param: FloatParam,
    }
    
    impl Default for PluginParams {
        fn default() -> Self {
            Self {
                param: FloatParam::new(
                    "param",
                    1.0,
                    FloatRange::Reversed(&RATIO_RANGE),
                )
            }
        }
    }
    
    opened by BSFishy 4
  • Preserve the order of non-grouped nested parameters

    Preserve the order of non-grouped nested parameters

    This resolves issue #43. Nested parameters that are not grouped are now inserted to the parameter list according to definition order. Grouped parameters remain at the bottom of the parameter list.

    opened by sleiner 4
  • Parameter order: Nested parameters are always behind non-nested parameters

    Parameter order: Nested parameters are always behind non-nested parameters

    How to reproduce

    Have a plugin where the parameter struct contains "non-nested" parameters aft`r nested ones:

    #[derive(Params)]
    struct PluginParams {
        #[id = "one"]
        pub one: FloatParam,
    
        #[nested(group = "inner")]
        pub two_and_three: InnerParams,
    
        #[id = "four"]
        pub four: FloatParam,
    }
    
    #[derive(Params)]
    struct InnerParams {
        #[id = "two"]
        pub two: FloatParam,
    
        #[id = "three"]
        pub three: FloatParam,
    }
    

    See also: minimal example plugin

    Expected behavior

    When opening the plugin in the host, the parameters are displayed in this order:

    1. One
    2. Two
    3. Three
    4. Four

    Actual Behavior

    The nested parameters from InnerParams are displayed after all non-nested parameters:

    1. One
    2. Four
    3. Two
    4. Three

    See, for example, Bitwig: Screenshot_2022-11-07_22-18-03

    opened by sleiner 4
  • Not sure how to use the `timing` of emitted midi events

    Not sure how to use the `timing` of emitted midi events

    First, great work ! I could get a vst3+clap plugin going in 5 minutes.

    I'm trying to make a simple midi arpeggiator - one note in, multiple notes out. How would I emit a NoteOn midi event, let's say, one quarter noter later than the initial note received ? I'd love a quick sample.

    Thanks !

    opened by theor 2
  • [Feature] flake.nix/dockerfile for simple cross compilation

    [Feature] flake.nix/dockerfile for simple cross compilation

    I want to be able to enter an environment and be able to build for all targets with no extra setup.

    Currently cross compiling isn't smooth, and setting up an environment with the correct development dependencies is not always straight forward.

    Nix Flakes are great for this, but a Dockerfile (where I have started) works too, albeit not as nice to work with as Flakes.

    It's taken me a few days to figure out the linux/linux and linux/windows build environments. Not sure how far I'll get with osx pipeline.

    I also want to thank you so much for putting all this together. I've been dreaming of making a VST for about 10 years and now I feel I'm able to. Besides setting up the environment, you've made it a straight forward process <3.

    # Can build linux and windows, gain_gui_iced
    FROM rust
    
    RUN apt-get update  \
        && \
        apt-get install -y \
        libasound2-dev \
        libgl-dev \ 
        libjack-dev \
        libxcb1-dev \
        libxcb-icccm4-dev \
        libxcursor-dev \
        libxkbcommon-dev \
        libxcb-shape0-dev \
        libxcb-xfixes0-dev \
        libx11-xcb-dev \
        libxcb-dri2-0-dev \
        curl \
        python3 \
        cmake \
        clang \
        gcc \
        g++ \
        zlib1g-dev \
        libmpc-dev \
        libmpfr-dev \
        libgmp-dev \
        gcc-mingw-w64 \
        && \
        rustup target add \
        x86_64-pc-windows-gnu \
        x86_64-apple-darwin \
        && \
        cargo install cross 
    
    
    RUN git clone https://github.com/tpoechtrager/osxcross /usr/local/osxcross &&\
        cd /usr/local/osxcross && \ 
        wget -nc https://s3.dockerproject.org/darwin/v2/MacOSX10.10.sdk.tar.xz && \
        mv MacOSX10.10.sdk.tar.xz tarballs/ && \
        UNATTENDED=yes OSX_VERSION_MIN=10.7 ./build.sh 
    
    
    ENV PATH "$(pwd)/osxcross/target/bin:$PATH"
    
    WORKDIR /home/local/project
    
    ENTRYPOINT ["/bin/bash"]
    
    opened by waynevanson 2
  • Fork assert_no_alloc to add logging support and backtraces for the assert_process_allocs feature

    Fork assert_no_alloc to add logging support and backtraces for the assert_process_allocs feature

    The assert_process_allocs feature is very useful you'll immediately know whether or not you're allocating in your process function. The problem is that while this does work, it can be tricky to know what is causing those allocations. We could improve this by having it use the logger instead of printing directly to STDERR, and to have it print a backtrace in addition to the allocation size.

    enhancement 
    opened by robbert-vdh 1
Owner
Robbert van der Helm
Robbert van der Helm
Simple examples to demonstrate full-stack Rust audio plugin dev with baseplug and iced_audio

iced baseplug examples Simple examples to demonstrate full-stack Rust audio plugin dev with baseplug and iced_audio WIP (The GUI knobs do nothing curr

Billy Messenger 10 Sep 12, 2022
A low-level windowing system geared towards making audio plugin UIs.

baseview A low-level windowing system geared towards making audio plugin UIs. baseview abstracts the platform-specific windowing APIs (winapi, cocoa,

null 155 Dec 30, 2022
A simple GUI audio player written in Rust with egui. Inspired by foobar2000.

Music Player A simple GUI music player inspired by foobar2000 written in Rust using egui. The goal of this project is to learn about making gui/ nativ

Ryan Blecher 5 Sep 16, 2022
Cross-platform audio I/O library in pure Rust

CPAL - Cross-Platform Audio Library Low-level library for audio input and output in pure Rust. This library currently supports the following: Enumerat

null 1.8k Jan 8, 2023
Rust audio playback library

Audio playback library Rust playback library. Playback is handled by cpal. MP3 decoding is handled by minimp3. WAV decoding is handled by hound. Vorbi

null 1.2k Jan 1, 2023
Rust bindings for the soloud audio engine library

soloud-rs A crossplatform Rust bindings for the soloud audio engine library. Supported formats: wav, mp3, ogg, flac. The library also comes with a spe

Mohammed Alyousef 38 Dec 8, 2022
Implements the free and open audio codec Opus in Rust.

opus-native Overview Implements the free and open audio codec Opus in Rust. Status This crate is under heavy development. Most functionality is not wo

Nils Hasenbanck 9 Nov 28, 2022
Symphonia is a pure Rust audio decoding and media demuxing library supporting AAC, FLAC, MP3, MP4, OGG, Vorbis, and WAV.

Pure Rust multimedia format demuxing, tag reading, and audio decoding library

Philip Deljanov 1k Jan 2, 2023
Rust - Augmented Audio Libraries

Augmented Audio Libraries In this repository I'll push some experiments trying to use Rust for audio programming. Goals Goal 1: Learn & have fun This

Pedro Tacla Yamada 116 Dec 18, 2022
CLI Rust Audio Visualizer

crav Console-based Rust Audio Visualizer It can run in the terminal but also has a 3D accelerated backend implemented in wgpu. demo compatibility The

null 20 Oct 16, 2022
simple-eq is a crate that implements a simple audio equalizer in Rust.

simple-eq A Simple Audio Equalizer simple-eq is a crate that implements a simple audio equalizer in Rust. It supports a maximum of 32 filter bands. Us

Mike Hilgendorf 11 Sep 17, 2022
Rust Audio Player Daemon

Rust Audio Player Daemon Cause mpd was annoying What rapd trys to do Rapd is not a spotify client, or an advanced music player. Its an audio/music dae

ash 3 Nov 1, 2022
Cross-platform audio for Rust

quad-snd High-level, light-weight, and opinionated audio library. Web: WebAudio Android: OpenSLES Linux: Alsa macOS: CoreAudio Windows: Wasapi iOS: Co

Fedor Logachev 86 Nov 7, 2022
DSP real time audio synthesis, effect algorithms and utilities for Rust

synfx-dsp synfx-dsp DSP real time audio synthesis, effect algorithms and utilities for Rust Most of the algorithms and implementations in this library

Weird Constructor 8 Nov 23, 2022
Quite OK Audio format in Rust.

QOA - The Quite Ok Audio Format This is a pure Rust (zero dependency) implementation of the QOA audio format. This code is based off the reference C i

Rafael Carício 10 Apr 16, 2023
A low-overhead and adaptable audio playback library for Rust

Awedio   A low-overhead and adaptable audio playback library for Rust. Examples Play a single sound file: let (mut manager, backend) = awedio::start()

10 Buttons 20 May 25, 2023
Capture system output audio in rust.

RUHear A simple crate that allows you to capture system output audio (what aRe yoU HEARing). Dependencies On windows and linux: cpal On macos: screenc

Charles 3 Feb 7, 2024
Rust-crate with functions and helpers for working with music / audio, inspired by computer music languages.

music-math This crate contains common functions and helpers for working with music / audio in Rust. Most of these are inspired by similar functions fo

Mads Kjeldgaard 3 Apr 10, 2024
A collection of filters for real-time audio processing

Audio Filters A collection of filters for real-time audio processing Feature Progress #![no_std] (via libm) f32 & f64 capable (via num-traits) SIMD Do

null 42 Nov 5, 2022