/nih-plug

Rust VST3 and CLAP plugin framework and plugins - because everything is better when you do it yourself

Primary LanguageRustISC LicenseISC

NIH-plug

Automated builds Tests Docs

This is a work in progress API-agnostic audio plugin framework written in Rust 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 work in progress documentation for some pointers on how to get started.

Table of contents

Plugins

Check each plugin's readme for more details on what the plugin actually does. You can download the development binaries for Linux, Windows and macOS from the automated builds page. Or if you're not signed in on GitHub, then you can also find the latest nightly build here.

Scroll down for more information on the plugin framework.

  • Crisp adds a bright crispy top end to any low bass sound. Inspired by Polarity's Fake Distortion video.
  • Crossover is as boring as it sounds. It splits cleanly splits the signal into two to five bands using a variety of algorithms and outputs those through auxiliary outputs so they can be accessed and processed individually. Meant as an alternative to Bitwig's Multiband FX devices but with cleaner crossovers and a linear-phase option.
  • 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.
  • Loudness War Winner does what it says on the tin. Have you ever wanted to show off your dominance by winning the loudness war? Neither have I. Dissatisfaction guaranteed.
  • 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.
  • Safety Limiter is a simple tool to prevent ear damage. As soon as there is a peak above 0 dBFS or the specified threshold, the plugin will cut over to playing SOS in Morse code, gradually fading out again when the input returns back to safe levels. Made for personal use during plugin development and intense sound design sessions, but maybe you'll find it useful too!

Framework

Current features

  • Supports both VST3 and CLAP by simply adding the corresponding nih_export_<api>!(Foo) macro to your plugin's library.
  • Standalone binaries can be made by calling nih_export_standalone(Foo) from your main() function. Standalones come with a CLI for configuration and full JACK audio, MIDI, and transport support.
  • Declarative parameter handling without any boilerplate.
    • Define parameters for your plugin by adding FloatParam, IntParam, BoolParam, and EnumParam<T> 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<T> 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.
  • Support for CLAP's polyphonic modulation on a per-parameter basis.
  • 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.
  • Support for flexible dynamic buffer configurations, including multiple input and output busses.
  • A plugin bundler accessible through the cargo xtask bundle <package> <build_arguments> 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_<format>!(Foo); macro. The cargo xtask bundle command 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.
  • poly_mod_synth is a simple polyphonic synthesizer with support for polyphonic modulation in supported CLAP hosts. This demonstrates how polyphonic modulation can be used in NIH-plug.
  • 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.