Standard Library

std.audio_data

namespace std

The std namespace is the root for all the built-in Cmajor library code.
It contains various child namespaces that group tasks into various sub-categories.

namespace std::audio_datacode

These structures are useful for representing chunks of audio data with a known sample-rate. They're useful types when you're declaring an external variable which is going to hold audio file data or generated waveform data.
Note that duck-typing is used for the types of externals which contain audio data, so you can use your own classes as long as they contain a couple of fields which can hold the frame data and a sample rate. If you need a struct for audio data with more than 2 channels, you can just declare your own type using an appropriately-sized vector for the frames.

Structs

struct Mono

Represents a chunk of mono floating-point audio data.

Type	Member
float32[]	frames
float64	sampleRate

struct Stereo

Represents a chunk of stereo, interleaved floating-point audio data.

Type	Member
float32<2>[]	frames
float64	sampleRate

processor std::audio_data::SamplePlayer

processor std::audio_data::SamplePlayer (using SampleContent)

This processor will play chunks of audio sample data with a speed ratio applied.
It provides input events to set the audio data, speed ratio and other properties to control playback.
The SampleContent type must be a struct containing a 'frames' member, which is an array of audio frames, and a 'sampleRate' member with the original rate of the audio data.

Endpoints

output stream out (SampleContent::frames.elementType)

input event content (SampleContent)

input event speedRatio (float32)

input event shouldLoop (bool)

input event position (float32)

Variables

Type	Variable	Constant
SampleContent	currentContent
float32	currentSpeed	1.0f
float64	currentIndex
float64	indexDelta
bool	isLooping	false

Functions

content

event content (SampleContent newContent)

speedRatio

event speedRatio (float32 newSpeed)

position

event position (float32 newPosition)

shouldLoop

event shouldLoop (bool shouldLoop)

main

void main()

std.envelopes

namespace std::envelopescode

Utilities for calculating and applying static and dynamic gain levels.

processor std::envelopes::FixedASR

processor std::envelopes::FixedASR (float32 attackSeconds,
                                    float32 releaseSeconds)

A very minimal, fixed-length, attack-sustain-release envelope generator.
This has fixed-length attach and release times. Given input events of NoteOn and NoteOff objects, it will emit a stream of output gain levels that can be used to attenuate a voice.

Endpoints

output stream gainOut (float32)

input event eventIn (std::notes::NoteOn, std::notes::NoteOff)

Variables

Type	Variable
float32	keyDownVelocity
float32	currentLevel

Functions

eventIn

event eventIn (std::notes::NoteOn noteOn)

eventIn

event eventIn (std::notes::NoteOff noteOff)

main

void main()

std.filters

namespace std::filterscode

namespace std::filters (using FrameType = float32,
                        using CoefficientType = float32,
                        int32 framesPerParameterUpdate = 32)

The std::filters namespace is parameterised, allowing both the FrameType and the CoefficientType to be modified. By default the filters are float32, and hence use 32 bit precision, and filter frames of a single channel. FrameType can be specified as a vector to support more channels (e.g. float<2> for a stereo filter).
For efficiency reasons, modulated parameters are not applied every frame, and the framesPerParameterUpdate parameter can be used to tune the frequency of updates.
Each filter type is provided as both a Processor, which can be included in graphs, and as an Implementation structure, suitable for being composed into a user processor.
The filter processors are parameterised with these parameters setting the initial state of the filter. Parameter modulation is provided by input events.
The filter Implementation structure provides the following functions:

create() functions which construct an Implementation with the specified initial properties - this is the typical way that the structs are constructed
process() which generates an output frame from an input frame
setFrequency()/setMode() functions for filter parameters to allow the filter to be modified post construction.
reset() which clears out any internal state, returning it to the state post creation

Constants

Default values if not specified

Type	Variable	Constant
float32	defaultFrequency	1000.0f
float32	defaultQ	0.707107f
int32	defaultGain	0

namespace std::filters::tpt

These filters are based on the designs outlined in The Art of VA Filter Design by Vadim Zavalishin, with help from Will Pirkle in Virtual Analog Filter Implementation. The topology-preserving transform approach leads to designs where parameter modulation can be applied with minimal instability.
Parameter changes are applied at a lower rate than processor.frequency to reduce computational cost, and the frames between updates can be altered using the framesPerParameterUpdate, smaller numbers causing more frequent updates.

namespace std::filters::tpt::onepole

One pole filter implementation providing low and high pass options. The frequency and mode can be updated at a frequency determined by framesPerParameterUpdate.

Structs

struct Implementation

Type	Member
CoefficientType	b
FrameType	z1
int32	mode

Functions

create

Implementation create (int32 mode, float64 processorFrequency, float64 filterFrequency)

setFrequency

void setFrequency (
         Implementation& this, float64 processorFrequency, float64 filterFrequency)

reset

void reset (
         Implementation& this)

setMode

void setMode (
         Implementation& this, int32 mode)

process

FrameType process (
         Implementation& this, FrameType x)

processor std::filters::tpt::onepole::Processor

processor std::filters::tpt::onepole::Processor (int32 initialMode = Mode::lowPass,
                                                 float32 initialFrequency = defaultFrequency)

Endpoints

output stream out (FrameType)

input stream in (FrameType)

input event mode (int32)

input event frequency (float32)

Variables

Type	Variable	Constant
	filter
bool	updateFilter	false
float32	filterFrequency
int32	filterMode

Functions

mode

event mode (int32 m)

frequency

event frequency (float32 f)

main

void main()

reset

void reset()

namespace std::filters::tpt::onepole::Mode

Constants

Type	Variable	Constant
int32	lowPass	0
int32	highpass	1

namespace std::filters::tpt::svf

State variable filter implementation, suitable for modulation.

Structs

struct Implementation

Type	Member
CoefficientType	d
CoefficientType	a
CoefficientType	g1
FrameType[2]	z
int32	mode

Functions

create

Implementation create (int32 mode, float64 processorFrequency, float64 filterFrequency, float64 Q)

setFrequency

void setFrequency (
         Implementation& this, float64 processorFrequency, float64 filterFrequency, float64 Q)

reset

void reset (
         Implementation& this)

setMode

void setMode (
         Implementation& this, int32 mode)

processMultimode

FrameType[3] processMultimode (
         Implementation& this, FrameType x)

process

FrameType process (
         Implementation& this, FrameType x)

processor std::filters::tpt::svf::Processor

processor std::filters::tpt::svf::Processor (int32 initialMode = Mode::lowPass,
                                             float32 initialFrequency = defaultFrequency,
                                             float32 initialQ = defaultQ)

Endpoints

output stream out (FrameType)

input stream in (FrameType)

input event mode (int32)

input event frequency (float32)

input event q (float32)

Variables

Type	Variable	Constant
	filter
bool	updateFilter	false
float32	filterFrequency
int32	filterMode
float32	filterQ

Functions

mode

event mode (int32 m)

frequency

event frequency (float32 f)

q

event q (float32 q)

main

void main()

reset

void reset()

processor std::filters::tpt::svf::MultimodeProcessor

processor std::filters::tpt::svf::MultimodeProcessor (float32 initialFrequency = defaultFrequency,
                                                      float32 initialQ = defaultQ)

Endpoints

output stream lowOut (FrameType)

output stream highOut (FrameType)

output stream bandOut (FrameType)

input stream in (FrameType)

input event frequency (float32)

input event q (float32)

Variables

Type	Variable	Constant
	filter
bool	updateFilter	true
float32	filterFrequency
float32	filterQ

Functions

frequency

event frequency (float32 f)

q

event q (float32 q)

main

void main()

reset

void reset()

namespace std::filters::tpt::svf::Mode

Constants

Type	Variable	Constant
int32	lowPass	0
int32	highPass	1
int32	bandPass	2

namespace std::filters::dcblocker

Highpass filter for blocking DC. An implementation of https://ccrma.stanford.edu/~jos/fp/DC_Blocker.html
The DC blocker is a small recursive filter specified by the difference equation:

y(n) = x(n) - x(n-1) + Ry(n-1)

..where R is a parameter that is typically somewhere between 0.9 and 1

Structs

struct Implementation

Type	Member
FrameType	x1
FrameType	y1

Functions

create

Implementation create()

reset

void reset (
         Implementation& this)

process

FrameType process (
         Implementation& this, FrameType x)

processor std::filters::dcblocker::Processor

Endpoints

output stream out (FrameType)

input stream in (FrameType)

Variables

Type	Variable	Constant
	filter

Functions

main

void main()

reset

void reset()

namespace std::filters::butterworth

namespace std::filters::butterworth (int32 order = 2)

Butterworth filter, built from cascaded tpt filters.
The order is set at compile time, but the type and frequency can be modulated at runtime.

Structs

struct Implementation

Type	Member
tpt::onepole::Implementation	onePole
tpt::svf::Implementation[order / 2]	twoPole

Functions

create

Implementation create (int32 mode, float64 processorFrequency, float64 filterFrequency)

setMode

void setMode (
         Implementation& this, int32 mode)

setFrequency

void setFrequency (
         Implementation& this, float64 processorFrequency, float64 filterFrequency)

reset

void reset (
         Implementation& this)

process

FrameType process (
         Implementation& this, FrameType x)

processor std::filters::butterworth::Processor

processor std::filters::butterworth::Processor (int32 initialMode = Mode::lowPass,
                                                float32 initialFrequency = defaultFrequency)

Endpoints

output stream out (FrameType)

input stream in (FrameType)

input event mode (int32)

input event frequency (float32)

Variables

Type	Variable	Constant
	filter
bool	updateFilter	true
float32	filterFrequency
int32	filterMode

Functions

mode

event mode (int32 m)

frequency

event frequency (float32 f)

main

void main()

reset

void reset()

namespace std::filters::butterworth::Mode

Constants

Type	Variable	Constant
int32	lowPass	0
int32	highPass	1

namespace std::filters::crossover

4th Order two band crossover filter
This filter is implemented using the StateVariableFilter and outputs two streams which can be summed to produce a flat response. The crossover frequency can be modulated.

Structs

struct Implementation

Type	Member
tpt::svf::Implementation[2]	filters

Functions

create

Implementation create (float64 processorFrequency, float64 filterFrequency)

setFrequency

void setFrequency (
         Implementation& this, float64 processorFrequency, float64 filterFrequency)

reset

void reset (
         Implementation& this)

process

FrameType[2] process (
         Implementation& this, FrameType x)

processor std::filters::crossover::Processor

processor std::filters::crossover::Processor (float32 initialFrequency = defaultFrequency)

Endpoints

output stream lowOut (FrameType)

output stream highOut (FrameType)

input stream in (FrameType)

input event frequency (float32)

Variables

Type	Variable	Constant
	filter
bool	updateFilter	true
float32	filterFrequency

Functions

frequency

event frequency (float32 f)

main

void main()

reset

void reset()

namespace std::filters::simper

Simper filter
This filter is based on the design by Andy Simper, and is an implementation of the State Variable filter providing many different operational modes. It is documented here: https://cytomic.com/files/dsp/SvfLinearTrapOptimised2.pdf

Structs

struct Implementation

Type	Member
FrameType	ic1eq
FrameType	ic2eq
CoefficientType	a1
CoefficientType	a2
CoefficientType	a3
CoefficientType	f0
CoefficientType	f1
CoefficientType	f2
int32	mode

Functions

create

Implementation create (int32 mode, float64 processorFrequency, float64 filterFrequency, float64 Q, float64 gain)

setMode

void setMode (
         Implementation& this, int32 m)

reset

void reset (
         Implementation& this)

setFrequency

void setFrequency (
         Implementation& this, float64 processorFrequency, float64 filterFrequency, float64 Q, float64 gain)

process

FrameType process (
         Implementation& this, FrameType v0)

processor std::filters::simper::Processor

processor std::filters::simper::Processor (int32 initialMode = Mode::lowPass,
                                           float32 initialFrequency = defaultFrequency,
                                           float32 initialQ = defaultQ,
                                           float32 initialGain = defaultGain)

Endpoints

output stream out (FrameType)

input stream in (FrameType)

input event mode (int32)

input event frequency (float32)

input event q (float32)

input event gain (float32)

Variables

Type	Variable	Constant
	filter
bool	updateFilter	false
float32	filterFrequency
int32	filterMode
float32	filterQ
float32	filterGain

Functions

mode

event mode (int32 m)

frequency

event frequency (float32 f)

q

event q (float32 q)

gain

event gain (float32 f)

main

void main()

reset

void reset()

namespace std::filters::simper::Mode

Constants

Type	Variable	Constant
int32	lowPass	0
int32	highPass	1
int32	bandPass	2
int32	notchPass	3
int32	peakPass	4
int32	allPass	5
int32	lowShelf	6
int32	highShelf	7
int32	bell	8

std.frequency

namespace std::frequencycode

Contains DFT implementations for complex and real numbers
The buffers can be either float32 or float64 (or complex32/complex64). Buffer sizes must be a power of 2.

Functions

realOnlyForwardFFT

Performs a forward DFT. The parameters must be power-of-2 sized arrays of floats. The input parameter takes the real components, and the output array receives the real and imaginary components.

void realOnlyForwardFFT<FloatArray> (const FloatArray& inputData, FloatArray& outputData)

realOnlyInverseFFT

Performs an inverse FFT. The parameters must be power-of-2 sized arrays of floats. The input parameter takes the real and imaginary components, and the output array receives the real components.

void realOnlyInverseFFT<FloatArray> (const FloatArray& inputData, FloatArray& outputData)

complexFFT

Performs an in-place forward FFT on complex data.

void complexFFT<ComplexArray> (ComplexArray& data)

complexIFFT

Performs an in-place inverse FFT on complex data.

void complexIFFT<ComplexArray> (ComplexArray& data)

std.intrinsics

namespace std::intrinsicscode

This namespace contains placeholders and reference implementations of basic functions.
The compiler treats the intrinsics namespace as a special-case, allowing its functions to act as if they're in the global namespace.
When running code, the JIT engines are free to replace the implementation of intrinsic functions with optimised alternatives if possible, although many of the functions in here also provide reference implementations to be used as a fallback when no native version is available.

Functions

max

Compares two scalar or vector values and returns the maximum. For vector operands, this returns a vector of results for each element.

T max<T> (T v1, T v2)

min

Compares two scalar or vector values and returns the minimum. For vector operands, this returns a vector of results for each element.

T min<T> (T v1, T v2)

select

Uses a boolean vector to determine which elements from two other vectors should be combined into the result.

T select<T> (bool<T.size> mask, T trueValues, T falseValues)

clamp

Returns a value which has been clamped to fit within the given range (inclusive of the top).

T clamp<T> (T value, T minimum, T maximum)

wrap

Wraps a value to fit within a range, using a negative-aware modulo operation, and returning zero if the size is zero.

T wrap<T> (T value, T size)

wrap

Wraps a value to fit within a range, using a negative-aware modulo operation, and returning zero if the size is zero.

int32 wrap (int32 value, int32 size)

addModulo2Pi

Adds two floating-point values together, returning the result modulo 2*Pi. This is a common operation for tasks like incrementing the phase of an oscillator.

T addModulo2Pi<T> (T startValue, T valueToAdd)

abs

Returns the absolute value of a scalar or vector value.

T abs<T> (T n)

floor

Returns the largest integer not greater than the argument. This follows the same rules as the standard C/C++ std::floor() function.

T floor<T> (T n)

ceil

Returns the smallest integer not less than the argument. This follows the same rules as the standard C/C++ std::ceil() function.

T ceil<T> (T n)

rint

Rounds the argument to an integer value. This follows the same rules as the standard C/C++ std::rint() function.

T rint<T> (T n)

fmod

Returns the floating point modulo operation of its arguments. This follows the same rules as the standard C/C++ std::fmod() function.

T fmod<T> (T x, T y)

remainder

Returns the floating remainder of its arguments. This follows the same rules as the standard C/C++ std::remainder() function.

T remainder<T> (T x, T y)

lerp

Performs a linear-interpolation between a pair of scalar values.

T lerp<T> (T value1, T value2, float32 proportion)

roundToInt

Returns the nearest integer to a floating point value.

int32 roundToInt (float32 value)

roundToInt

Returns the nearest integer to a floating point value.

int64 roundToInt (float64 value)

sqrt

Returns the square root of its argument.

T sqrt<T> (T n)

pow

Raises a value to the given power.

T pow<T> (T a, T b)

exp

Returns the exponent of a scalar floating-point argument.

T exp<T> (T n)

exp

Returns the exponent of a complex number.

complex32 exp (complex32 n)

exp

Returns the exponent of a complex number.

complex64 exp (complex64 n)

log

Returns the natural log of a scalar floating point argument.

T log<T> (T n)

log10

Returns the base-10 log of a scalar floating point argument.

T log10<T> (T n)

isinf

Checks whether the supplied argument is a floating point INF.

bool isinf<FloatType> (FloatType value)

isnan

Checks whether the supplied argument is a floating point NaN.

bool isnan<FloatType> (FloatType value)

reinterpretFloatToInt

Reinterprets the raw bits of a 32-bit float as an integer.

int32 reinterpretFloatToInt (float32 value)

reinterpretFloatToInt

Reinterprets the raw bits of a 64-bit float as an integer.

int64 reinterpretFloatToInt (float64 value)

reinterpretIntToFloat

Reinterprets the bits of a 32-bit integer as a float32.

float32 reinterpretIntToFloat (int32 value)

reinterpretIntToFloat

Reinterprets the bits of a 64-bit integer as a float64.

float64 reinterpretIntToFloat (int64 value)

sum

Calculates the sum of the elements in a vector or array.

ArrayType.elementType sum<ArrayType> (ArrayType array)

product

Multiplies all the elements of an array or vector of scalar values.

ArrayType.elementType product<ArrayType> (ArrayType array)

read

Returns an element from an array. The index is a generic parameter, and can be either an integer or a float value. If you provide a float index, then it'll round it down to the nearest integer and use that. If the index lies beyond the range of the array, it will be wrapped.

Array.elementType read<Array, IndexType> (const Array& array, IndexType index)

readLinearInterpolated

Linearly-interpolates a value at a position in an array. The first argument must be an array of floating point (or vector float) values, and the index provided should be a floating point value. This will interpolate between adjacent elements in the array to calculate the return value. If the index lies beyond the range of the array, it will be wrapped.

Array.elementType readLinearInterpolated<Array, IndexType> (const Array& array, IndexType index)

anyTrue

Takes a vector or array of bools, and returns true if any of its elements are true.

bool anyTrue<BoolArray> (BoolArray boolArray)

allTrue

Takes a vector or array of bools, and returns true if all of its elements are true.

bool allTrue<BoolArray> (BoolArray boolArray)

allEqual

Takes two array or vector arguments, and returns true if all of their corresponding elements are equal.

bool allEqual<Array1, Array2> (const Array1& array1, const Array2& array2)

swap

Swaps the contents of two assignable values.

void swap<Type> (Type& value1, Type& value2)

sin

Sine of an angle.

T sin<T> (T n)

cos

Cosine of an angle.

T cos<T> (T n)

tan

Tangent of an angle.

T tan<T> (T n)

atan

Arc tangent (inverse tangent) of x.

T atan<T> (T n)

sinh

Hyperbolic sine of an angle.

T sinh<T> (T n)

cosh

Hyperbolic cosine of an angle.

T cosh<T> (T n)

tanh

Hyperbolic tangent of an angle.

T tanh<T> (T n)

atanh

Arc hyperbolic tangent.

T atanh<T> (T n)

asin

Arc sine (inverse sine) of an angle.

T asin<T> (T n)

acos

Arc cosine (inverse cosine) of an angle.

T acos<T> (T n)

asinh

Arc hyperbolic sine.

T asinh<T> (T n)

acosh

Arc hyperbolic cosine.

T acosh<T> (T n)

atan2

Arc tangent of y/x.

T atan2<T> (T y, T x)

std.levels

namespace std::smoothingcode

namespace std::smoothing (using FrameType = float32)

Utilities for calculating and applying smoothing ramps and gain levels. The std::smoothing namespace is parameterised. FrameType defaults to float32, but can be specified to allow support for different precision types (e.g. float64) as well as smoothed values for multi-channel use (e.g. float32<2>)

Structs

struct SmoothedValue

Utilities for smoothing non-audio signals, such as control parameters. Holds a float value and is given a target to move towards over a given time. Call setTarget() to tell the object where to go and how many steps to take to get there, then repeatedly call getNext() to iterate to the target.

Type	Member
FrameType	value
FrameType	target
FrameType	increment
int32	remainingSteps

Functions

reset

Immediately resets the value to the given argument

void reset (
         SmoothedValue& this, FrameType newValue)

setTarget

Gives the object a target value and the number of steps it should take to reach it.

void setTarget (
         SmoothedValue& this, FrameType targetValue, int32 stepsToReachTarget)

getNext

Returns the current value and increments it towards the current target.

FrameType getNext (
         SmoothedValue& this)

currentValue

FrameType currentValue (
         SmoothedValue& this)

processor std::smoothing::SmoothedValueStream

processor std::smoothing::SmoothedValueStream (float32 smoothingTimeSeconds = 0.2f,
                                               FrameType initialValue = 0.0f)

Takes an input that receives floating point events, and produces a continuous output stream of floats which are smoothed by a specified amount. This is handy for smoothing plugin parameters

Endpoints

output stream out (FrameType)

input event in (FrameType)

Variables

Type	Variable
SmoothedValue	smoothedValue

Functions

in

event in (FrameType newTarget)

main

void main()

init

void init()

namespace std::levelscode

Functions

dBtoGain

Converts a relative gain in decibels to a gain.

T dBtoGain<T> (T decibels)

gainTodB

Converts a gain to a relative number of decibels.

T gainTodB<T> (T gainFactor)

graph std::levels::ConstantGain

graph std::levels::ConstantGain (using FrameType,
                                 float32 gain)

This helper processor simply passes its input through to its output with a constant gain applied. The FrameType parameter could be a float, or a vector of floats. See: DynamicGain, SmoothedGain

Endpoints

output stream out (FrameType)

input stream in (FrameType)

Connections

connection in * gain -> out

graph std::levels::DynamicGain

graph std::levels::DynamicGain (using FrameType)

This helper processor takes two input streams - one for data and the other for a gain level, and emits the input signal with the gain applied. The FrameType parameter could be a float, or a vector of floats. See: ConstantGain, SmoothedGain

Endpoints

output stream out (FrameType)

input stream gain (float32)

input stream in (FrameType)

Connections

connection in * gain -> out

graph std::levels::SmoothedGain

graph std::levels::SmoothedGain (using FrameType,
                                 float32 smoothingTimeSeconds = 0.2f)

Takes an input stream of the given FrameType, and passes it through using a SmoothedGainParameter processor to apply a smoothed gain to it. The gain level is exposed via the 'volume' input.

Endpoints

output stream out (FrameType)

input stream volume gainParameter.volume

input stream in (FrameType)

Nodes

gainParameter = std::levels::SmoothedGainParameter(smoothingTimeSeconds)

Connections

connection in * gainParameter.gain -> out

processor std::levels::SmoothedGainParameter

processor std::levels::SmoothedGainParameter (float32 smoothingTimeSeconds = 0.2f)

Takes input events which change the level in decibels, and produces an output stream of smoothed gain factors which can be applied to a signal.

Endpoints

output stream gain (float32)

input event volume (float32)

Variables

Type	Variable
std::smoothing::SmoothedValue	smoothedGain

Functions

volume

event volume (float32 newVolumeDecibels)

main

void main()

init

void init()

namespace std::pan_lawcode

Functions

linear

Takes a pan position between -1 and 1 and returns a vector pair of left/right gains using a linear pan-law.

T<2> linear<T> (T panPosition)

centre3dB

Takes a pan position between -1 and 1 and returns a vector pair of left/right gains using a 3dB-centre pan-law.

T<2> centre3dB<T> (T panPosition)

std.matrix

namespace std::matrixcode

This namespace contains various matrix manipulation functions.

Functions

multiply

Returns the matrix product of two 2-dimensional arrays.

ElementType[n, m] multiply<ElementType, n, m, k> (ElementType[n, k] a, ElementType[k, m] b)

dot

Returns the dot-product of two 1-dimensional arrays.

ElementType dot<ElementType, n> (ElementType[n] a, ElementType[n] b)

dot

Returns the dot-product of two 2-dimensional arrays. (The dot product for 2D arrays is the same as a matrix multiplication).

ElementType[n, m] dot<ElementType, n, m, k> (ElementType[n, k] a, ElementType[k, m] b)

inverse

Returns the inverse of the input 2-dimensional array. If no inverse is possible, it returns an empty array. This algorithm uses the Gaussian elimination method to calculate the inverse.

ElementType[n, n] inverse<ElementType, n> (ElementType[n, n] matrix)

add

Returns the sum of two 2-dimensional arrays.

ElementType[n, m] add<ElementType, n, m> (ElementType[n, m] a, ElementType[n, m] b)

subtract

Returns the difference between two 2-dimensional arrays.

ElementType[n, m] subtract<ElementType, n, m> (ElementType[n, m] a, ElementType[n, m] b)

std.midi

Various utilities for handling raw MIDI data.

namespace std::midicode

The classes in the standard library which deal with synthesisers have been designed to avoid raw MIDI messages, and instead to work with strongly-typed event objects for note-ons/offs, pitch-bends, etc, which are vastly more usable than a 3-byte code that was designed for a 1980s serial link.

Structs

struct Message

Holds a short (3-byte) MIDI message.

Type	Member	Comment
int32	message	This contains 3 packed bytes, arranged as (byte2 \| (byte1 << 8) \| (byte0 << 16)). This layout means that when you view the value in hex in your debugger, it reads in the natural order for a MIDI message.

Functions

getByte1

int32 getByte1 (const 
         Message& this)

getByte2

int32 getByte2 (const 
         Message& this)

getByte3

int32 getByte3 (const 
         Message& this)

getMessageType

int32 getMessageType (const 
         Message& this)

getChannel0to15

int32 getChannel0to15 (const 
         Message& this)

getChannel1to16

int32 getChannel1to16 (const 
         Message& this)

get14BitValue

int32 get14BitValue (const 
         Message& this)

isNoteOn

bool isNoteOn (const 
         Message& this)

isNoteOff

bool isNoteOff (const 
         Message& this)

getNoteNumber

int32 getNoteNumber (const 
         Message& this)

getPitch

float32 getPitch (const 
         Message& this)

getVelocity

int32 getVelocity (const 
         Message& this)

getFloatVelocity

float32 getFloatVelocity (const 
         Message& this)

isProgramChange

bool isProgramChange (const 
         Message& this)

getProgramChangeNumber

int32 getProgramChangeNumber (const 
         Message& this)

isPitchWheel

bool isPitchWheel (const 
         Message& this)

getPitchWheelValue

int32 getPitchWheelValue (const 
         Message& this)

isAftertouch

bool isAftertouch (const 
         Message& this)

getAfterTouchValue

int32 getAfterTouchValue (const 
         Message& this)

isChannelPressure

bool isChannelPressure (const 
         Message& this)

getChannelPressureValue

int32 getChannelPressureValue (const 
         Message& this)

getFloatChannelPressureValue

float32 getFloatChannelPressureValue (const 
         Message& this)

isController

bool isController (const 
         Message& this)

isControllerNumber

bool isControllerNumber (const 
         Message& this, int32 number)

getControllerNumber

int32 getControllerNumber (const 
         Message& this)

getControllerValue

int32 getControllerValue (const 
         Message& this)

getFloatControllerValue

float32 getFloatControllerValue (const 
         Message& this)

isAllNotesOff

bool isAllNotesOff (const 
         Message& this)

isAllSoundOff

bool isAllSoundOff (const 
         Message& this)

isQuarterFrame

bool isQuarterFrame (const 
         Message& this)

isClock

bool isClock (const 
         Message& this)

isStart

bool isStart (const 
         Message& this)

isContinue

bool isContinue (const 
         Message& this)

isStop

bool isStop (const 
         Message& this)

isActiveSense

bool isActiveSense (const 
         Message& this)

isMetaEvent

bool isMetaEvent (const 
         Message& this)

isSongPositionPointer

bool isSongPositionPointer (const 
         Message& this)

getSongPositionPointerValue

int32 getSongPositionPointerValue (const 
         Message& this)

createMessage

Creates a short MIDI message object from the raw bytes


         Message createMessage (int32 byte1, int32 byte2, int32 byte3)

Constants

standard MPE range of 48 semitones

MPE slide controller number

Type	Variable	Constant	Comment
float32	semitoneBendRange	48.0f
int32	slideController	74

processor std::midi::MPEConverter

Accepts an input stream of raw MIDI MPE events and converts them to a stream of note event objects which can be more easily used by synthesiser classes.

Endpoints

output event eventOut ( NoteOn, NoteOff, PitchBend, Slide, Pressure, Control)

input event parseMIDI ( Message)

Functions

parseMIDI

event parseMIDI (
          Message message)

processor std::midi::NoteToMIDI

Accepts an input of note events, and converts them to a stream of short midi messages.

Endpoints

output event midiOut ( Message)

input event eventIn ( NoteOn, NoteOff, PitchBend, Slide, Pressure, Control)

Functions

eventIn

event eventIn (
          NoteOn e)

eventIn

event eventIn (
          NoteOff e)

eventIn

event eventIn (
          PitchBend e)

eventIn

event eventIn (
          Slide e)

eventIn

event eventIn (
          Pressure e)

eventIn

event eventIn (
          Control e)

std.mixers

namespace std::mixerscode

These processors can be used to mix various combinations of audio streams together with static or dynamic gains.

processor std::mixers::StereoToMono

processor std::mixers::StereoToMono (using SampleType)

Simple utility processor that takes a vector size 2 and outputs the sum of its elements.

Endpoints

output stream out (SampleType)

input stream in (SampleType<2>)

Functions

main

void main()

processor std::mixers::MonoToStereo

processor std::mixers::MonoToStereo (using SampleType)

Simple utility processor that takes a scalar input and outputs a vector size 2 which contains two copies of the input value

Endpoints

output stream out (SampleType<2>)

input stream in (SampleType)

Functions

main

void main()

processor std::mixers::DynamicSum

processor std::mixers::DynamicSum (using FrameType)

Takes two input streams and two gain streams which it uses to attenuate the inputs. Their result is then emitted. FrameType can be a float or float vector type.

Endpoints

output stream out (FrameType)

input stream in1 (FrameType)

input stream in2 (FrameType)

input stream gain1 (float32)

input stream gain2 (float32)

Functions

main

void main()

processor std::mixers::ConstantSum

processor std::mixers::ConstantSum (using FrameType,
                                    float32 inputGain1 = 1.0f,
                                    float32 inputGain2 = 1.0f)

Takes two input streams which it adds together after applying some optional constant gains. FrameType can be a float or float vector type.

Endpoints

output stream out (FrameType)

input stream in1 (FrameType)

input stream in2 (FrameType)

Functions

main

void main()

processor std::mixers::Interpolator

processor std::mixers::Interpolator (using FrameType,
                                     float32 mixRange)

Takes two input streams and outputs a dynamic mix of their values, using a third stream to control the mix.
mixRange determines the range of values that the mix stream will take. So the mix input is expected to be between 0 and mixRange, where mix = 0 will cause 100% of in1 to be emitted, and mix = mixRange will cause 100% of in2 to be emitted.
This processor is handy as a wet/dry mixer - for example you could connect a dry stream to in1, a wet stream to in2, and set mixRange to 100. Then, the mix input will act as a "percentage wet" control.

Endpoints

output stream out (FrameType)

input stream in1 (FrameType)

input stream in2 (FrameType)

input stream mix (float32)

Functions

main

void main()

std.noise

namespace std::noisecode

These processors can be used to generate various flavours of noise.

processor std::noise::White

Simple white noise generator. See https://en.wikipedia.org/wiki/White_noise

Endpoints

output stream out (float32)

Variables

Type	Variable
RNG	rng

Functions

init

void init()

main

void main()

processor std::noise::Brown

Brown (a.k.a. Brownian) noise generator. See https://en.wikipedia.org/wiki/Brownian_noise

Endpoints

output stream out (float32)

Variables

Type	Variable	Constant
RNG	rng
float32	lastLevel
float32	filter	0.998f
float32	scale	32.0f

Functions

init

void init()

main

void main()

processor std::noise::Pink

Pink noise generator See https://en.wikipedia.org/wiki/Pink_noise

Endpoints

output stream out (float32)

Variables

Type	Variable
RNG	rng
float32[12]	values
int32	sampleCount
float32	lastLevel

Functions

init

void init()

main

void main()

std.notes

namespace std::notescode

These structs are used for events that model the start/stop/control of notes that are playing in synthesisers.
Unlike sending raw MIDI around, these are strongly typed and use floating point data so are far nicer to work with.
The objects include a channel ID field, so that a multi-channel input device can indicate which events should be applied to each of the active notes that are being played.

Structs

struct NoteOn

Type	Member	Comment
int32	channel	This channel ID is used to associate events which act on a particular voice. When a NoteOn object is sent, the sender will create a unique ID, and use the same ID for any subsequent pitch and control events, and for the final matching NoteOff event.
float32	pitch	The pitch uses the same semitone scale as MIDI note numbers, between 0 and 127, where middle C = 60.
float32	velocity	Velocity is between 0 and 1

struct NoteOff

Type	Member	Comment
int32	channel	This channel ID can be used to associate this NoteOff event with the earlier NoteOn to which it applies.
float32	pitch	You may not care exactly what the pitch is when a note is released, but in case it's needed, it's included here.
float32	velocity	Indicates how quickly the key was released: range is 0 to 1.

struct PitchBend

Type	Member	Comment
int32	channel	This channel ID can be used to associate this event with the earlier NoteOn to which it applies.
float32	bendSemitones	The number of semitones to bend up from the original note-on pitch.

struct Pressure

Type	Member	Comment
int32	channel	This channel ID can be used to associate this event with the earlier NoteOn to which it applies.
float32	pressure	Key pressure is in the range 0 to 1

struct Slide

"Slide" refers to a Y-axis controller parameter. (In MPE input devices, this is a MIDI controller number 74)

Type	Member	Comment
int32	channel	This channel ID can be used to associate this event with the earlier NoteOn to which it applies.
float32	slide	The slide position ranges from 0 to 1. Exactly what you choose to do with it depends on the instrument.

struct Control

Type	Member	Comment
int32	channel	This channel ID can be used to associate this event with the earlier NoteOn to which it applies.
int32	control	This could be used for any kind of controller index, but is probably best used for MIDI controller numbers.
float32	value	The normalised value of the controller, between 0 and 1

Functions

frequencyToNote

Returns the MIDI note equivalent for a frequency in Hz. This uses the standard A = 440Hz reference tuning. See: noteToFrequency

float32 frequencyToNote (float32 frequency)

frequencyToNote

Returns the MIDI note equivalent for a frequency in Hz. The frequencyOfA parameter lets you use non-standard tunings if you need to. See: noteToFrequency

float32 frequencyToNote (float32 frequency, float32 frequencyOfA)

noteToFrequency

Returns the frequency in Hz for a MIDI note number. You can provide either an integer or floating point argument - the MIDI note scale is in semitone units from 0 to 127, where middle C = 60. This uses the standard A = 440Hz reference tuning. See: frequencyToNote

float32 noteToFrequency<T> (T midiNoteNumber)

noteToFrequency

Returns the frequency in Hz for a MIDI note number. You can provide either an integer or floating point argument - the MIDI note scale is in semitone units from 0 to 127, where middle C = 60. The frequencyOfA parameter lets you use non-standard tunings if you need to. See: frequencyToNote

float32 noteToFrequency<T> (T midiNoteNumber, float32 frequencyOfA)

getSpeedRatioBetween

Calculates the speed ratio by which playback must be changed to re-pitch a given source note to a target note.

float32 getSpeedRatioBetween (float32 sourceMIDINote, float32 targetMIDINote)

getSpeedRatioBetween

Given a source with a known sample rate and pitch, this calculates the ratio at which it would need to be sped-up in order to achieve a target pitch and sample-rate.

float64 getSpeedRatioBetween (float64 sourceSampleRate, float32 sourceMIDINote, float64 targetSampleRate, float32 targetMIDINote)

std.oscillators

namespace std::oscillatorscode

These utility functions and processors provide oscillators such as sine, square, triangle and sawtooth.

Structs

struct PhasorState

A class to manage a phase and increment that loops between 0 and 1.

Type	Member
float32	phase
float32	increment

struct PolyblepState

Type	Member
PhasorState	phasor
float32	accumulator

Functions

setFrequency

void setFrequency (
         PhasorState& this, float64 outputFrequencyHz, float64 oscillatorFrequencyHz)

float32 next (
         PhasorState& this)

setFrequency

void setFrequency (
         PolyblepState& this, float64 outputFrequencyHz, float64 oscillatorFrequencyHz)

nextSine

float32 nextSine (
         PolyblepState& this)

nextSquare

Returns the sample of a square wave.

float32 nextSquare (
         PolyblepState& this)

nextSawtooth

Returns the sample of a sawtooth wave.

float32 nextSawtooth (
         PolyblepState& this)

nextTriangle

float32 nextTriangle (
         PolyblepState& this)

processor std::oscillators::Phasor

processor std::oscillators::Phasor (using FrameType,
                                    float32 initialFrequency = 1000)

A processor which generates a unipolar ramp, and has an input to control its frequency. The FrameType parameter could be a float or a float vector.

Endpoints

output stream out (FrameType)

input event frequencyIn (float32)

Variables

Type	Variable
PhasorState	phasor

Functions

init

void init()

frequencyIn

event frequencyIn (float32 newFrequency)

main

void main()

processor std::oscillators::Sine

processor std::oscillators::Sine (using FrameType,
                                  float32 initialFrequency = 440.0f)

A basic sinewave generation processor with an input to control its frequency. The FrameType parameter could be a float or a float vector.

Endpoints

output stream out (FrameType)

input event frequencyIn (float32)

Variables

Type	Variable
PhasorState	phasor

Functions

init

void init()

frequencyIn

event frequencyIn (float32 newFrequency)

main

void main()

processor std::oscillators::PolyblepOscillator

processor std::oscillators::PolyblepOscillator (using FrameType,
                                                Shape initialShape = Shape::sawtoothUp,
                                                float32 initialFrequency = 440.0f)

Uses a polyblep algorithm to generate a wave, with inputs to control its shape and frequency.

Endpoints

output stream out (FrameType)

input event frequencyIn (float32)

input event shapeIn (float32)

Variables

Type	Variable	Constant
PolyblepState	polyblep
Shape	currentShape

Functions

init

void init()

frequencyIn

event frequencyIn (float32 newFrequency)

shapeIn

event shapeIn (float32 newShape)

main

void main()

processor std::oscillators::LFO

processor std::oscillators::LFO (Shape initialShape = Shape::sine,
                                 float32 initialFrequency = 1.0f,
                                 float32 initialAmplitude = 1.0f,
                                 float32 initialOffset = 0.0f)

A LFO processor with event inputs to control its parameters.

Endpoints

output stream out (float32)

input event shapeIn (float32)

input event rateHzIn (float32)

input event rateTempoIn (float32)

input event amplitudeIn (float32)

input event offsetIn (float32)

input event rateModeIn (float32)

input event syncIn (float32)

input event positionIn (std::timeline::Position)

input event transportStateIn (std::timeline::TransportState)

input event tempoIn (std::timeline::Tempo)

Variables

Type	Variable	Constant
Shape	currentShape
std::smoothing::SmoothedValue	currentAmplitude
float32	currentOffset
bool	isUsingTempo	false
bool	isSyncActive	false
bool	isPlaying	false
float32	cyclesPerBeat	1
float64	lastQuarterNotePos
float32	currentPhase
float32	currentRandomValue
float32	phaseIncrementHz	initialFrequency * float32(processor.period)
float32	phaseIncrementTempo	120.0f * float32(processor.period / 60)
std::random::RNG	rng

Functions

positionIn

event positionIn (std::timeline::Position newPos)

transportStateIn

event transportStateIn (std::timeline::TransportState newState)

tempoIn

event tempoIn (std::timeline::Tempo newTempo)

rateTempoIn

event rateTempoIn (float32 newNumBeats)

amplitudeIn

event amplitudeIn (float32 newAmplitude)

offsetIn

event offsetIn (float32 newOffset)

shapeIn

event shapeIn (float32 newShape)

rateModeIn

event rateModeIn (float32 isTempo)

syncIn

event syncIn (float32 isSyncing)

rateHzIn

event rateHzIn (float32 newRateHz)

isRandomMode

bool isRandomMode()

init

void init()

main

void main()

getNextSample

float32 getNextSample()

resetRandomValue

void resetRandomValue()

advancePhase

void advancePhase (float32 increment)

namespace std::oscillators::waveshape

namespace std::oscillators::waveshape (using SampleType = float32)

Functions

sine

Returns a sine wave, where phase is in the range 0 to 1

SampleType sine<T> (T phase)

sine

Returns a sine wave with a given amplitude, where phase is in the range 0 to 1

SampleType sine<T> (T phase, SampleType amplitude)

sine

Returns a sine wave with a given amplitude and offset, where phase is in the range 0 to 1

SampleType sine<T> (T phase, SampleType amplitude, SampleType offset)

square

Returns a bipolar square wave, where phase is in the range 0 to 1

SampleType square<T> (T phase)

square

Returns a square wave with a given amplitude, where phase is in the range 0 to 1

SampleType square<T> (T phase, SampleType amplitude)

square

Returns a square wave with a given amplitude and offset, where phase is in the range 0 to 1

SampleType square<T> (T phase, SampleType amplitude, SampleType offset)

triangle

Returns a bipolar triangle wave, where phase is in the range 0 to 1

SampleType triangle<T> (T phase)

triangle

Returns a triangle wave with a given amplitude, where phase is in the range 0 to 1

SampleType triangle<T> (T phase, SampleType amplitude)

triangle

Returns a triangle wave with a given amplitude and offset, where phase is in the range 0 to 1

SampleType triangle<T> (T phase, SampleType amplitude, SampleType offset)

sawtoothUp

Returns a bipolar upwards sawtooth wave, where phase is in the range 0 to 1

SampleType sawtoothUp<T> (T phase)

sawtoothUp

Returns an upwards sawtooth wave with a given amplitude, where phase is in the range 0 to 1

SampleType sawtoothUp<T> (T phase, SampleType amplitude)

sawtoothUp

Returns an upwards sawtooth wave with a given amplitude and offset, where phase is in the range 0 to 1

SampleType sawtoothUp<T> (T phase, SampleType amplitude, SampleType offset)

sawtoothDown

Returns a bipolar downwards sawtooth wave, where phase is in the range 0 to 1

SampleType sawtoothDown<T> (T phase)

sawtoothDown

Returns an downwards sawtooth wave with a given amplitude, where phase is in the range 0 to 1

SampleType sawtoothDown<T> (T phase, SampleType amplitude)

sawtoothDown

Returns an downwards sawtooth wave with a given amplitude and offset, where phase is in the range 0 to 1

SampleType sawtoothDown<T> (T phase, SampleType amplitude, SampleType offset)

polyblep

SampleType polyblep<T> (T phase, T increment)

polyblep_square

SampleType polyblep_square<T> (T phase, T increment)

polyblep_sawtooth

SampleType polyblep_sawtooth<T> (T phase, T increment)

generate

Returns a wave of the shape type passed in as an argument, where phase is in the range 0 to 1

SampleType generate<T> (Shape waveShapeType, T phase)

generate

Returns a wave of the shape type passed in as an argument, where phase is in the range 0 to 1

SampleType generate<T> (Shape waveShapeType, T phase, SampleType amplitude, SampleType offset)

std.random

namespace std::randomcode

If you're writing code that needs to be cryptographically secure, then this is not the random number generation library that you want. The target audience for these classes are those who need quick-and-dirty RNGs for noise generation and similar non-critical tasks.
When seeding RNGs, the processor.id and processor.session values are very useful:

processor.id is different for each instance of a processor, but the same for each run of the program. If you have multiple instances of a processor node which each have an RNG, then if you seed them with a value based on processor.id, they'll each use a different stream of values, but the sequences will be the same each time the program runs.

processor.session is the same for all processors, but different each time the program runs, so if you use it as part of your seed, it'll make the program behave differently each time.

Structs

struct RNG

This default RNG is a basic linear congruential generator. See https://en.wikipedia.org/wiki/Lehmer_random_number_generator

Type	Member	Comment
int64	state	The Lehmer algorithm uses a simple 64-bit state which mutates each time a number is generated.

Functions

seed

Resets the generator with a given seed.

void seed (
         RNG& this, int64 newSeed)

getInt32

Returns a positive int32 between 0 and 0x7fffffff

int32 getInt32 (
         RNG& this)

getUnipolar

Returns a value between 0 and 1.

float32 getUnipolar (
         RNG& this)

getBipolar

Returns a value between -1 and 1.

float32 getBipolar (
         RNG& this)

getFloat

Returns a floating point value between 0 and maximumValue

float32 getFloat (
         RNG& this, float32 maximumValue)

std.timeline

namespace std::timelinecode

This namespace contains various types and functions for dealing with tempos, positions and events that describe DAW-style timelines.

Structs

struct Tempo

Type	Member	Comment
float32	bpm	BPM = beats per minute :)

struct TimeSignature

Type	Member
int32	numerator
int32	denominator

struct TransportState

Indicates whether a host is currently playing or recording. This struct is intended for purposes like sending as an event into a plugin to tell it when the host's playback state changes.

Type	Member	Comment
int32	flags	This is used as a bit-field, where bit 0 = playing bit 1 = recording bit 2 = looping

struct Position

This struct holds data that a host may want to send as an event to a plugin to update it with various measurements of positions along its timeline.

Type	Member	Comment
int64	frameIndex	The frame index, from the start of the host's timeline.
float64	quarterNote	A floating-point count of quarter-notes from the start of the host's timeline. If a host doesn't count time in terms of beats, then this could be left as 0.
float64	barStartQuarterNote	The position of the start of the current bar, measured as the number of quarter-notes from the start of the host's timeline. If a host doesn't count time in terms of beats, then this could be left as 0. This is useful in conjunction with quarterNote if you need to know e.g. how many beats you are into the current bar.

Functions

secondsPerBeat

float32 secondsPerBeat (const 
         Tempo& this)

framesPerBeat

float64 framesPerBeat (const 
         Tempo& this, float64 framesPerSecond)

secondsPerQuarterNote

float32 secondsPerQuarterNote (const 
         Tempo& this, 
         TimeSignature timeSig)

framesPerQuarterNote

float64 framesPerQuarterNote (const 
         Tempo& this, 
         TimeSignature timeSig, float64 framesPerSecond)

beatsPerQuarterNote

float32 beatsPerQuarterNote (const 
         TimeSignature& this)

quarterNotesPerBeat

float32 quarterNotesPerBeat (const 
         TimeSignature& this)

isStopped

bool isStopped (const 
         TransportState& this)

isPlaying

bool isPlaying (const 
         TransportState& this)

isRecording

bool isRecording (const 
         TransportState& this)

isLooping

bool isLooping (const 
         TransportState& this)

std.voices

namespace std::voicescode

This module demonstrates a simple voice-allocation algorithm.
The way it's structured is that you pass an incoming stream of note events to the voice allocator processor, and it redirects them to an array of destination processors which each handle a single voice.
The voice allocators use the channel property of the incoming events to group them together, and take care of ensuring that each target voice only receives the events from one channel at a time.

processor std::voices::VoiceAllocator

processor std::voices::VoiceAllocator (int32 numVoices,
                                       int32 MPEMasterChannel = 0)

A basic least-recently-used voice allocator.
If there's an inactive voice, then a new note will be assigned to it, otherwise it will steal the least-recently-used active voice. For more fancy note-stealing algorithms, you can use this as an example and add your own logic!

Endpoints

output event voiceEventOut (std::notes::NoteOn, std::notes::NoteOff, std::notes::PitchBend, std::notes::Slide, std::notes::Pressure, std::notes::Control)

input event eventIn (std::notes::NoteOn, std::notes::NoteOff, std::notes::PitchBend, std::notes::Slide, std::notes::Pressure, std::notes::Control)

Structs

struct VoiceState

Type	Member
bool	isActive
bool	isReleasing
int32	channel
int32	age
float32	pitch

Variables

Type	Variable	Constant
VoiceState[numVoices]	voiceState
int32	nextActiveTime	0x70000000
int32	nextInactiveTime	1
bool	mpeMasterSustainActive
int64	perChannelSustainActive

Functions

eventIn

event eventIn (std::notes::NoteOn noteOn)

eventIn

event eventIn (std::notes::NoteOff noteOff)

eventIn

event eventIn (std::notes::PitchBend bend)

eventIn

event eventIn (std::notes::Pressure pressure)

eventIn

event eventIn (std::notes::Slide slide)

eventIn

event eventIn (std::notes::Control control)

start

void start (
          VoiceState& this, int32 channel, float32 pitch)

free

void free (
          VoiceState& this)

isSustainActive

one per bit (assumes that channel IDs are <64, and could be made more general)

bool isSustainActive (int32 channel)

setChannelSustain

void setChannelSustain (int32 channel, bool active)

findOldestIndex

wrap<numVoices> findOldestIndex()