Crate tunelet 

A crate for vocal pitch correction, choir, harmony, formant control and effects.

Processor changes mono signed 16-bit PCM into the same number of stereo or mono frames. The sample rate is 44.1 kHz or 48 kHz. The signal chain is Punch → Warm → pitch tracking and resynthesis → Alien → reverb → output gain. The default configuration enables chromatic pitch correction and one choir voice. The optional effects and the formant stage are disabled.

Preparing and configuring

PrepareConfig sets the sample rate. It also sets the maximum number of frames for one process call or one drain call. To make a ProcessorConfig, start from its default value and change its public stage fields. Then give it to Processor::new. All configuration ranges are inclusive, unless the documentation tells you differently. Floating-point controls must be finite.

Validation also examines disabled stages and the controls of voice modes that are not active.

A configuration value is a copy. If you change it, the processor does not change until Processor::set_config or a configuration event applies it. You can change settings between blocks, or at a frame offset with a TimedEvent. To change the sample rate or the block limit, you must make a new processor.

Audio and timed controls

There are three process methods:

• Processor::process writes [left, right] frames.
• Processor::process_planar writes separate channels.
• Processor::process_mono_in_place replaces the input with the stereo downmix.

These layouts do not depend on ResynthesisConfig::stereo_output, which controls voice panning. The output is clipped to -32767..=32767.

An event applies before its selected frame. Offsets must be in the current block and must not decrease. Events with equal offsets execute in slice order. The processor validates the full block before it changes the output or its state. Thus, an invalid last event also rejects the full call. An empty block accepts no events.

ControlEvent::Midi controls harmony. ControlEvent::CorrectionMidi selects the correction pitch classes independently. The processor does not keep MIDI controls in a queue after the current call.

Feedback, latency and lifecycle

Processor::feedback gives the pitch, the correction ratio, the accumulated stereo peak and the frame count. Processor::take_feedback also clears the peak window. The pitch reporting bounds change only the reports. They do not change the detection or the audio signal. Processor::latency_frames gives a nominal resynthesis delay. Voice delays, pitch changes and effects have their own timing.

Processor::telemetry gives data for meters and displays: the ratio and the gain of each voice, the input and output peaks, the pitch clarity and the state of the effects. Processor::take_telemetry also clears the peak windows of the telemetry. Processor::formant_envelope writes the LPC envelopes before and after the formant controls. These calls do not change the audio.

After the last input block, call Processor::begin_drain one time. Then render drain blocks until a call returns zero. Each call fills the unused output with zeros. The drain uses a finite configured budget and mutes aspiration. It is not a silence detector.

The call that uses all of the budget does the same reset as Processor::reset. This occurs also if that call returns audio. A successful process call, a successful configuration call or a reset cancels the drain.

Processor::reset keeps the configuration and some controller state, for example the random stream. Its documentation lists the state that it keeps. If you need a fully new instance, make a new processor.

Execution model

Construction allocates the audio storage. After construction, the calls for audio, controls, feedback, reset and drain do not allocate memory. They do not acquire locks and do no I/O. Each processor owns its histories and its random stream. Fixed-point arithmetic uses explicit wrapping and quantization. If you change the order of the arithmetic, the samples can change.

The default build uses only safe Rust and has no dependencies.

WebAssembly

To export JavaScript bindings and generated TypeScript definitions, enable the optional wasm feature for wasm32-unknown-unknown. The binding owns PCM buffers that it uses again. Configuration conversion, event conversion, feedback objects and errors cause more allocation at the JavaScript boundary. Refer to the README for how to build the shared package for browsers and Node.js.

Structs

AlienConfig

Reverse playback of recent stereo audio in repeated loops with fades.

CorrectionConfig

The controls for pitch-class correction, with target selection in the period domain.

Feedback

A snapshot of the pitch analysis and the output level that you can copy.

FormantConfig

The controls for vocal-tract changes and synthesized aspiration during resynthesis.

HarmonyConfig

The configuration of four harmony voices that follow intervals, chords or MIDI.

NoteMask

The permitted correction pitch classes, in the order C, C♯, D, D♯, E, F, F♯, G, G♯, A, A♯, B.

PitchConfig

The acquisition sensitivity and the bounds for pitch reports to the host.

PrepareConfig

The fixed limits of a processor: the sample rate and the maximum number of frames for each call.

Processor

A prepared vocal processor with state, mono input and stereo synthesis.

ProcessorConfig

The settings for the complete signal chain, in the order of the stages.

PunchConfig

The input gain and the transient enhancement with arctangent saturation.

ResynthesisConfig

The controls for pitch correction, pitch shift, voice arrangement and formants.

ReverbConfig

The reverb after Alien, with controls for the network, the wet mix and the decay.

Telemetry

A snapshot of the voices, the levels and the effect state that you can copy.

TimedEvent

A control that applies immediately before the zero-based input frame offset.

WarmConfig

Asymmetric input saturation, followed by a 50 Hz high-pass filter.

Enums

ChordDegree

A diatonic chord with its root on a degree of the selected HarmonyScale.

ChordName

A named chord for HarmonySource::ChordByName.

ConfigProblem

The problem with a configuration field.

ControlEvent

A configuration or MIDI control that applies before a frame in the block.

CorrectionScale

A scale for NoteMask::from_key_scale.

Error

The reason for a rejected call.

EventProblem

The reason for the rejection of a timed event during the block preflight.

HarmonyScale

The scale that smart intervals and chords by degree use.

HarmonySource

The source of target periods for the four harmony voices.

Inversion

The chord inversion raises the lowest chord tones by one octave.

MidiEvent

The supported MIDI note controls, with zero-based channel numbers.

MultiVoiceMode

The method that resynthesis uses to render its voices.

PitchClass

One of the twelve notes in an octave.

ReverbMode

The echo or reverberation network. The default is Self::Echo.

SampleRate

The sample rate of the input and the output.

Constants

HARMONY_VOICES

The number of harmony voices in addition to the lead voice: four. The interval arrays and the voice allocation for MIDI channels use the same count.