Crate heron_sound

heron-sound is a library of DSP utilities used in Heron Sounds audio plugins.

Currently supports the following DSP components:

• Envelope generators (ADSR, Exponential ADSR, DA)
• Envelope follower
• Filters (State-variable)
• Basic waveforms (Saw, Sine, Pulse, Triangle)
• Oscillators built on basic waveforms
• Low-frequency oscillators
• Tools for parameter modulation
• Tools for pitch manipulation
• Bitmask implementation
• Tools for sample rate manipulation

As well as a variety of utilities to support the above.

Implementation

To help develop DSP components, we provide two basic traits, Gen and Proc. Gen is for components that generate some value from their internal state without any explicit input, while Proc is for processors that take some input value and produce an output. The inputs and outputs may be samples, gains, or more complex types, but should not be user-modifiable parameters.

To pass in user-modifiable parameters, both traits have a Spec associated type which is passed by shared reference at processing time and evaluated, along with the processor’s internal state, to produce an output.

For example, an envelope follower can be implemented as a Proc that takes an input sample and returns a bool indicating whether the envelope is engaged or not:

struct EnvFollower {
    engaged: bool,
    counter: u32,
}
 
struct EnvFollowerSpec {
    threshold: f64,
    hold_time: u32,
}
 
impl Proc<f64, bool> for EnvFollower {
    type Spec = EnvFollowerSpec;
    fn proc(&mut self, spec: &Self::Spec, sample: f64) -> bool {
        // implementation omitted
    }
}

Its internal state keeps track of whether it’s currently engaged and for how long, and its associated Spec type keeps track of the amplitude threshold and hold time, both of which can be set by the user. At processing time, it checks whether the input sample’s amplitude is above the threshold, increments its internal counter and checks it against the user-set hold time, and computes a boolean value to return. To see how this is implemented in practice, take a look at EnvFollower and EnvFollowerSpec.

Most of the code in this library consists of implementations of Gen and Proc, but we also include some miscellaneous utils in the util mod.

Approach

The components in this library are implemented according to the following constraints:

• keep memory use low
• but prefer caching values over recomputing them
• avoid allocations during processing
• perform as few operations as possible during processing
• maintain a strict boundary between user-modifiable parameters and internal mutable state
• minimize dependencies
• avoid unsafe code

As well as a few more relaxed constraints:

• avoid newtypes, but use type aliases where it aids readability
• use f64 as the default float type
• prefer use of phase offsets to pitches in Hz to minimize computations (see pitch)
• in simple code, bounds checks can be skipped in release builds to aid performance
• allow some unnecessary memory use if it’s small and keeps code cleaner
• keep components as generic as feasible, but allow some opinionated decisions (see ExpAdsrSpec)

Future

In general, we put code in this library as soon as we can find a way to make it generic enough to be useful for more than one type of plugin (and write adequate tests for it). Expect the functionality to expand as we clean up application-specific code and make it more modular.

The following additions are in the works, but not fully tested or cleaned up:

• First class support for plugin parameters
• Ring buffers, delay lines, and pitch-shifting
• Distortion algorithms
• Additional filter types

Modules

• clock
  Sample rate utilities.
• env
  Envelope generator implementations.
• filter
  Filter implementations.
• follow
  Envelope follower implementations.
• lfo
  Low-frequency oscillator implementations.
• modulate
  Utilities for modulating parameters.
• osc
  Oscillator implementations.
• phase
  Phasor implementation.
• pitch
  Utilities for manipulating pitches (or phase increments).
• trigger
  Midi note trigger implementation.
• util
  Miscellaneous useful stuff.
• wave
  Low-level computations for oscillator waveforms.

Macros

• accessors
  helper to create get_val() and set_val() fns.
• check_float_01
  Check that float values are in range 0..=1.
• check_float_finite
  Check that float values are finite.
• check_float_nonneg
  Check that float values are nonnegative.
• check_float_nonzero
  Check that float values are nonzero.
• check_float_pos
  Check that float values are positive and nonzero.
• check_hz_bounds
  Check that float values representing Hz are positive and non-zero.
• check_int_less_than
  Check that int values are less than a constant.
• check_phase_bounds
  Check that float values representing phases are in range 0..1.
• getters
  helper to create get_val() and get_val_mut() fns.
• index_accessors
  helper to create get_val() and set_val() fns that take indexes.
• index_getters
  helper to create get_val() and get_val_mut() fns that take indexes.

Traits

• Gen
  A processor that generates a value, with no input.
• Proc
  A processor that transforms a value.

Type Aliases

• F
  Basic float type (currently f64 but this may change).
• Hz
  Anything measured in Hz; positive only.
• Note
  A midi note; 0..128.
• Phase
  Phase position of a wave; 0.0..1.0.
• Sample
  Amplitude of a sample; -1.0..=1.0.
• Scale
  Anything measured in fractions.
• Seconds
  Anything measured in seconds; positive only, probably.
• Vel
  Midi velocity; 0..128.