NIH-plug
![Docs](https://github.com/robbert-vdh/nih-plug/actions/workflows/docs.yml/badge.svg?branch=master)
NIH-plug is an API-agnostic audio plugin framework written in Rust, as well as a
small collection of plugins. The idea is to have a stateful yet simple plugin
API that gets rid of as much unnecessary ceremony wherever possible, while also
keeping the amount of magic to minimum and making it easy to experiment with
different approaches to things. See the current features
section for more information on the project's current status.
Check out the documentation, or use
the cookiecutter template to
quickly get started with NIH-plug.
Table of contents
Plugins
Check each plugin's readme file 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. You
may need to disable Gatekeeper on macOS to be able to use
the plugins.
Scroll down for more information on the underlying plugin framework.
- Buffr Glitch is the plugin for you if you enjoy
the sound of a CD player skipping This plugin is essentially a MIDI triggered
buffer repeat plugin. When you play a note, the plugin will sample the period
corresponding to that note's frequency and use that as a single waveform
cycle. This can end up sounding like an in-tune glitch when used sparingly, or
like a weird synthesizer when used less subtly.
- 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 cleanly
splits the signal into two to five bands using a variety of algorithms. Those
bands are then sent to 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!
- Soft Vacuum is a straightforward port of
Airwindows' Hard Vacuum plugin
with parameter smoothing and up to 16x linear-phase oversampling, because I
liked the distortion and just wished it had oversampling. All credit goes to
Chris from Airwindows. I just wanted to share this in case anyone else finds
it useful.
- Spectral Compressor can squash anything
into pink noise, apply simultaneous upwards and downwards compressor to
dynamically match the sidechain signal's spectrum and morph one sound into
another, and lots more. Have you ever wondered what a 16384 band OTT would
sound like? Neither have I.
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.
- Rich declarative parameter system 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"]
.
- Optional support for state migrations, for handling breaking changes in
plugin parameters.
- Group your parameters into logical groups by nesting
Params
objects using
the #[nested(group = "...")]
attribute.
- The
#[nested]
attribute also enables you to use multiple copies of the
same parameter, either as regular object fields or through arrays.
- When needed, you can also provide your own implementation for the
Params
trait to enable compile time generated parameters and other bespoke
functionality.
- Stateful. Behaves mostly like JUCE, just without all of the boilerplate.
- Comes with a simple yet powerful way to asynchronously run background tasks
from a plugin that's both type-safe and realtime-safe.
- 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
.
- Optional support for compressing the human readable JSON state files using
Zstandard.
- 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.
- MIDI SysEx is also supported. Plugins can define their own structs or sum
types to wrap around those messages so they don't need to interact with raw
byte buffers in the process function.
- Support for flexible dynamic buffer configurations, including variable numbers
of input and output ports.
- First-class support several more exotic CLAP features:
- Both monophonic and polyphonic parameter modulation are supported.
- Plugins can declaratively define pages of remote controls that DAWs can bind
to hardware controllers.
- 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 functionality 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.
- sysex is a simple example of how to send and
receive SysEx messages by defining custom message types.
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.