Module prelude 

Everything you’ll need to use nice-plug. Import this with use nice_plug::prelude::*;.

Re-exports

pub use crate::wrapper::standalone::nice_export_standalone;

pub use crate::wrapper::standalone::nice_export_standalone_with_args;

pub use crate::wrapper::clap::features::ClapFeature;

pub use crate::wrapper::clap::ClapPlugin;

pub use crate::wrapper::clap::PolyModulationConfig;

pub use crate::wrapper::vst3::Vst3Plugin;

pub use crate::wrapper::vst3::subcategories::Vst3SubCategory;

Modules

control_change

Constants to represent controller change types.

formatters

Convenience functions for formatting and parsing parameter values in various common formats.

util

General conversion functions and utilities.

Macros

nice_dbg

Analogues to the dbg!() macro, but respecting the NICE_LOG environment variable and with all of the same logging features as the other nice_*!() macros. Like the nice_debug_assert*!() macros, this is only shown when compiling in debug mode, but the macro will still return the value in non-debug modes.

nice_debug_assert

A debug_assert!() analogue that prints the error with line number information instead of panicking. During tests this is upgraded to a regular panicking debug_assert!().

nice_debug_assert_eq

A debug_assert_eq!() analogue that prints the error with line number information instead of panicking. See nice_debug_assert!() for more information.

nice_debug_assert_failure

An unconditional debug assertion failure, for if the condition has already been checked elsewhere. See nice_debug_assert!() for more information.

nice_debug_assert_ne

A debug_assert_ne!() analogue that prints the error with line number information instead of panicking. See nice_debug_assert!() for more information.

nice_error

Similar to nice_log!(), but more scream-y. Used for printing fatal errors.

nice_export_clap

Export one or more CLAP plugins from this library using the provided plugin types.

nice_export_vst3

Export one or more VST3 plugins from this library using the provided plugin types. The first plugin’s vendor information is used for the factory’s information.

nice_log

Write something to the logger. This defaults to STDERR unless the user is running Windows and a debugger has been attached, in which case OutputDebugString() will be used instead.

nice_trace

The same as nice_log!(), but with source and thread information. Like the nice_debug_assert*!() macros, this is only shown when compiling in debug mode.

nice_warn

Similar to nice_log!(), but less subtle. Used for printing warnings.

Structs

AsyncExecutor

An way to run background tasks from the plugin’s GUI, equivalent to the ProcessContext::execute_background() and ProcessContext::execute_gui() functions. This is passed directly to Plugin::editor() so the plugin can move it into its editor and use it later.

AtomicF32

A floating point type which can be safely shared between threads.

AudioIOLayout

A description of a plugin’s audio IO configuration. The Plugin defines a list of supported audio IO configs, with the first one acting as the default layout. Depending on the plugin API, the host may pick a different configuration from the list and use that instead. The final chosen configuration is passed as an argument to the Plugin::initialize() function so the plugin can allocate its data structures based on the number of audio channels it needs to process.

AuxiliaryBuffers

Contains auxiliary (sidechain) input and output buffers for a process call.

BoolParam

A simple boolean parameter.

Buffer

The audio buffers used during processing. This contains the output audio output buffers with the inputs already copied to the outputs. You can either use the iterator adapters to conveniently and efficiently iterate over the samples, or you can do your own thing using the raw audio buffers.

BufferConfig

Configuration for (the host’s) audio buffers.

EnumParam

An IntParam-backed categorical parameter that allows convenient conversion to and from a simple enum. This enum must derive the re-exported Enum trait. Check the trait’s documentation for more information on how this works.

FloatParam

A floating point parameter that’s stored unnormalized. The range is used for the normalization process.

IntParam

A discrete integer parameter that’s stored unnormalized. The range is used for the normalization process.

Modifiers

Modifier keys held while a keyboard event was generated, as reported by Editor::on_virtual_key_from_host. Use the standard bitflags API (contains, intersects, is_empty, etc.) to query individual modifiers.

ParamFlags

Flags for controlling a parameter’s behavior.

ParamSetter

A convenience helper for setting parameter values. Any changes made here will be broadcasted to the host and reflected in the plugin’s Params object. These functions should only be called from the main thread.

PluginState

A plugin’s state so it can be restored at a later point. This object can be serialized and deserialized using serde.

PortNames

Contains names for the ports defined in an AudioIOLayout. Setting these is optional, but it makes working with multi-output plugins much more convenient.

Smoother

A smoother, providing a smoothed value for each sample.

Transport

Information about the plugin’s transport. Depending on the plugin API and the host not all fields may be available.

Enums

FloatRange

A distribution for a floating point parameter’s range. All range endpoints are inclusive.

IntRange

A distribution for an integer parameter’s range. All range endpoints are inclusive. Only linear ranges are supported for integers since hosts expect discrete parameters to have a fixed step size.

MidiConfig

Determines which note events a plugin can send and receive.

NoteEvent

Event for (incoming) notes. The set of supported note events depends on the value of [Plugin::MIDI_INPUT. Also check out the util module for convenient conversion functions.

ParamPtr

Internal pointers to parameters. This is an implementation detail used by the wrappers for type erasure.

ParentWindowHandle

A raw window handle for platform and GUI framework agnostic editors. This implements HasRawWindowHandle so it can be used directly with GUI libraries that use the same raw_window_handle version. If the library links against a different version of raw_window_handle, then you’ll need to wrap around this type and implement the trait yourself.

PluginApi

The currently active plugin API. This may be useful to display in an about screen in the plugin’s GUI for debugging purposes.

ProcessMode

The plugin’s current processing mode. Exposed through BufferConfig::process_mode. The host will reinitialize the plugin whenever this changes.

ProcessStatus

Indicates the current situation after the plugin has processed audio.

SmoothingStyle

Controls if and how parameters gets smoothed.

VirtualKeyCode

A non-character key delivered to Editor::on_virtual_key_from_host. Variant names mirror standard keyboard nomenclature; printable ASCII characters never appear here because they flow through the plugin window’s native keyboard path instead.

Traits

Editor

An editor for a Plugin.

Enum

An enum usable with EnumParam. This trait can be derived. Variants are identified either by a stable id (see below), or if those are not set then they are identifier by their declaration order. If you don’t provide IDs then you can freely rename the variant names, but reordering them will break compatibility with existing presets. The variant’s name is used as the display name by default. If you want to override this, for instance, because it needs to contain spaces, then you can use the #[name = "..."] attribute:

GuiContext

Callbacks the plugin can make when the user interacts with its GUI such as updating parameter values. This is passed to the plugin during Editor::spawn(). All of these functions assume they’re being called from the main GUI thread.

InitContext

Callbacks the plugin can make while it is being initialized. This is passed to the plugin during Plugin::initialize().

Param

Describes a single parameter of any type. Most parameter implementations also have a field called value that and a field called smoothed. The former stores the latest unsmoothed value, and the latter can be used to access the smoother. These two fields should be used in DSP code to either get the parameter’s current (smoothed) value. In UI code the getters from this trait should be used instead.

Params

Describes a struct containing parameters and other persistent fields.

Plugin

The main plugin trait covering functionality common across most plugin formats. Most formats also have another trait with more specific data and functionality that needs to be implemented before the plugin can be exported to that format. The wrappers will use this to expose the plugin in a particular plugin format.

ProcessContext

Contains both context data and callbacks the plugin can use during processing. Most notably this is how a plugin sends and receives note events, gets transport information, and accesses sidechain inputs and auxiliary outputs. This is passed to the plugin during as part of Plugin::process().

RemoteControlsContext

A context for defining plugin-specific remote pages for CLAP plugins.

RemoteControlsPage

A page containing references to up to eight parameters. If the number of slots used exceeds eight, then the page is split automatically. In that case the split page will have indices appended to it. For example, the Lengty Params Page defining 16 parameters will become Lengty Params Page 1 and Lengthy Params Page 2.

RemoteControlsSection

A section or group of parameter pages. Empty sections will not be visible when using the plugin.

Smoothable

A type that can be smoothed. This exists just to avoid duplicate explicit implementations for the smoothers.

SysExMessage

A type that can be converted to and from byte buffers containing MIDI SysEx messages.

Functions

new_nonzero_u32

Construct a NonZeroU32 value at compile time. Equivalent to NonZeroU32::new(n).unwrap().

Type Aliases

NonZeroU32

A u32 that is known not to equal zero.

PluginNoteEvent

A plugin-specific note event type.

TaskExecutor

A function that can execute a plugin’s BackgroundTasks. A plugin can dispatch these tasks from the initialize() function, the process() function, or the GUI, so they can be deferred for later to avoid blocking realtime contexts.

Derive Macros

Enum

Derive the Enum trait for simple enum parameters. See EnumParam for more information.

Params

Derive the Params trait for your plugin’s parameters struct. See the Plugin trait.