# torchsynth.module¶

## SynthModule¶

class torchsynth.module.SynthModule(synthconfig, device=None, **kwargs)

Bases: torch.nn.modules.module.Module

A base class for synthesis modules. A SynthModule optionally takes input from other SynthModule instances. The SynthModule uses its (optional) input and its set of ModuleParameter to generate output. All ModuleParameter of the SynthModule are assumed to be batch_size-length 1-D tensors.

All SynthModule objects should be atomic, i.e., they should not contain other SynthModule objects. This design choice is in the spirit of modular synthesis.

Parameters
add_parameters(parameters)

Adds parameters to the SynthModule parameter dictionary. Used by the class constructor.

Parameters

parameters (List[ModuleParameter]) – List of parameters to register with this module.

property batch_size

Size of the batch to be generated.

Return type

Tensor

property buffer_size

Size of the module output in samples.

Return type

Tensor

property eps

A very small value used to avoid computational errors.

Return type

float

forward(*args, **kwargs)

Wrapper for output that ensures a buffer_size length output.

Return type

Signal

get_parameter(parameter_id)

Retrieves a single ModuleParameter, as specified by its parameter Id.

Parameters

parameter_id (str) – Id of the parameter to retrieve.

Return type

ModuleParameter

get_parameter_0to1(parameter_id)

Retrieves a specified parameter value in the normalized range [0,1].

Parameters

parameter_id (str) – Id of the parameter to retrieve.

Return type

Tensor

property nyquist

Convenience property for the highest frequency that can be represented at sample_rate (as per Shannon-Nyquist).

output(*args, **kwargs)

Performs the main action of SynthModule. Each child class should override this method.

Return type

Signal

p(parameter_id)

Convenience method for retrieving a parameter value. Returns the value in parameter-specific, non-normalized range.

Parameters

parameter_id (str) – Id of the parameter to retrieve.

Return type

Tensor

property sample_rate

Sample rate frequency in Hz.

Return type

Tensor

seconds_to_samples(seconds)

Convenience function to calculate the number of samples corresponding to given a time value and sample_rate. Returns a possibly fractional value.

Parameters

seconds (Tensor) – Time value in seconds.

Return type

Tensor

set_parameter(parameter_id, value)

Updates a parameter value in a parameter-specific non-normalized range.

Parameters
set_parameter_0to1(parameter_id, value)

Update a parameter value in a normalized range [0,1].

Parameters
to(device=None, **kwargs)

This function overrides the to() call in torch.nn.Module. It ensures that the related values ModuleParameterRange and ModuleParameter, as well as synthconfig are also transferred to the correct device.

Parameters

device (Optional[device]) – device to send this module to

to_buffer_size(signal)

Fixes the length of a signal to the default buffer size of this module, as specified by buffer_size. Longer signals are truncated to length; shorter signals are zero-padded.

Parameters

signal (Signal) – A signal to pad or truncate.

Return type

Signal

## Audio Rate Modules¶

These modules operate at full audio sampling rate.

### AudioMixer¶

class torchsynth.module.AudioMixer(synthconfig, n_input, curves=None, names=None, **kwargs)

Sums together N audio signals and applies range-normalization if the resulting signal is outside of [-1, 1].

output(*signals)

Returns a mixed signal from an array of input signals.

Return type

Signal

### ControlRateUpsample¶

class torchsynth.module.ControlRateUpsample(synthconfig, device=None, **kwargs)

Upsample control signals to the global sampling rate

Uses linear interpolation to resample an input control signal to the audio buffer size set in synthconfig.

output(signal)

Performs the main action of SynthModule. Each child class should override this method.

Return type

Signal

### Noise¶

class torchsynth.module.Noise(synthconfig, seed, **kwargs)

Generates white noise that is the same length as the buffer.

For performance noise is pre-computed. In order to maintain reproducibility noise must be computed on the CPU and then transferred to the GPU, if a GPU is being used. We pre-compute BASE_REPRODUCIBLE_BATCH_SIZE samples of noise and then repeat those for larger batch sizes.

To keep things fast we only support multiples of BASE_REPRODUCIBLE_BATCH_SIZE when reproducibility mode is enabled. For example, if you batch size is 4 times BASE_REPRODUCIBLE_BATCH_SIZE, then you get the same noise signals repeated 4 times.

Note: If you have multiple Noise modules in the same AbstractSynth, make sure you instantiate each Noise with a unique seed.

Parameters
output()

Performs the main action of SynthModule. Each child class should override this method.

Return type

Signal

### SineVCO¶

class torchsynth.module.SineVCO(synthconfig, device=None, **kwargs)

Simple VCO that generates a pitched sinusoid.

oscillator(argument, midi_f0)

A cosine oscillator. …Good ol’ cosine.

Parameters
Return type

Signal

### SquareSawVCO¶

class torchsynth.module.SquareSawVCO(synthconfig, device=None, **kwargs)

An oscillator that can take on either a square or a sawtooth waveshape, and can sweep continuously between them, as determined by the shape parameter. A shape value of 0 makes a square wave; a shape of 1 makes a saw wave.

With apologies to Lazzarini and Timoney (2010). “New perspectives on distortion synthesis for virtual analog oscillators.” Computer Music Journal 34, no. 1: 28-40.

Module Parameters
tuning

tuning adjustment for VCO in midi.

(Min: -24.0, Max: 24.0, Curve: 1, Symmetric: False)

mod_depth

depth of the pitch modulation in semitones.

(Min: -96.0, Max: 96.0, Curve: 0.2, Symmetric: True)

initial_phase

Initial phase for this oscillator.

(Min: -3.1415927410125732, Max: 3.1415927410125732, Curve: 1, Symmetric: False)

shape

Waveshape - square to saw [0,1].

(Min: 0.0, Max: 1.0, Curve: 1, Symmetric: False)

oscillator(argument, midi_f0)

Generates output square/saw audio given a phase argument.

Parameters
Return type

Signal

partials_constant(midi_f0)

Calculates a value to determine the number of overtones in the resulting square / saw wave, in order to keep aliasing at an acceptable level. Higher fundamental frequencies require fewer partials for a rich sound; lower-frequency sounds can safely have more partials without causing audible aliasing.

Parameters

midi_f0 – Fundamental frequency in midi.

### FmVCO¶

class torchsynth.module.FmVCO(synthconfig, device=None, **kwargs)

Frequency modulation VCO. Takes a modulation signal as instantaneous frequency (in Hz) rather than as a midi value.

Typical modulation is calculated in pitch-space (midi). For FM to work, we have to change the order of calculations. Here the modulation depth is re-interpreted as the “modulation index” which is tied to the fundamental of the oscillator being modulated:

$$I = \Delta f / f_m$$

where $$I$$ is the modulation index, $$\Delta f$$ is the frequency deviation imparted by the modulation, and $$f_m$$ is the modulation frequency, both in Hz.

make_control_as_frequency(midi_f0, mod_signal)

Creates a time-varying control signal in instantaneous frequency (Hz).

Parameters
• midi_f0 (Tensor) – Fundamental frequency in midi.

• mod_signal – FM modulation signal (interpreted as modulation index).

Return type

Signal

oscillator(argument, midi_f0)

A cosine oscillator. …Good ol’ cosine.

Parameters
Return type

Signal

output(midi_f0, mod_signal)
Parameters
Return type

Signal

### VCA¶

class torchsynth.module.VCA(synthconfig, device=None, **kwargs)

Voltage controlled amplifier.

The VCA shapes the amplitude of an audio input signal over time, as determined by a control signal. To shape control-rate signals, use torchsynth.module.ControlRateVCA.

output(audio_in, control_in)
Parameters
• audio – Audio input to shape with the VCA.

• amp_control – Time-varying amplitude modulation signal.

Return type

Signal

### VCO¶

class torchsynth.module.VCO(synthconfig, device=None, **kwargs)

Base class for voltage controlled oscillators.

Think of this as a VCO on a modular synthesizer. It has a base pitch (specified here as a midi value), and a pitch modulation depth. Its call accepts a modulation signal between [-1, 1]. An array of 0’s returns a stationary audio signal at its base pitch.

Parameters
Module Parameters
tuning

tuning adjustment for VCO in midi.

(Min: -24.0, Max: 24.0, Curve: 1, Symmetric: False)

mod_depth

depth of the pitch modulation in semitones.

(Min: -96.0, Max: 96.0, Curve: 0.2, Symmetric: True)

initial_phase

Initial phase for this oscillator.

(Min: -3.1415927410125732, Max: 3.1415927410125732, Curve: 1, Symmetric: False)

make_argument(freq)

Generates the phase argument to feed an oscillating function to generate an audio signal.

Parameters

freq (Signal) – Time-varying instantaneous frequency in Hz.

Return type

Signal

make_control_as_frequency(midi_f0, mod_signal=None)

Generates a time-varying control signal in frequency (Hz) from a midi fundamental pitch and pitch-modulation signal.

Parameters
Return type

Signal

oscillator(argument, midi_f0)

This function accepts a phase argument and generates output audio. It is implemented by the child class.

Parameters
Return type

Signal

output(midi_f0, mod_signal=None)

Generates audio signal from modulation signal.

Parameters
Return type

Signal

## Control Rate Modules¶

Control rate modules produce signals that are used to modulate parameters of other modules. For performance these modules run at a reduced sampling rate.

### ControlRateModule¶

class torchsynth.module.ControlRateModule(synthconfig, device=None, **kwargs)

An abstract base class for non-audio modules that adapts the functions of SynthModule to run at control_rate.

property control_buffer_size

Size of the module output in samples.

Return type

Tensor

property control_rate

Control rate frequency in Hz.

Return type

Tensor

output(*args, **kwargs)

Performs the main action of ControlRateModule. Each child class should override this method.

Return type

Signal

seconds_to_samples(seconds)

Convenience function to calculate the number of samples corresponding to given a time value and control_rate. Returns a possibly fractional value.

Parameters

seconds (Tensor) – Time value in seconds.

Return type

Tensor

to_buffer_size(signal)

Fixes the length of a signal to the control buffer size of this module, as specified by control_buffer_size. Longer signals are truncated to length; shorter signals are zero-padded.

Parameters

signal (Signal) – A signal to pad or truncate.

Return type

Signal

class torchsynth.module.ADSR(synthconfig, device=None, **kwargs)

Envelope class for building a control-rate ADSR signal.

Parameters
Module Parameters

attack

attack time (sec).

(Min: 0.0, Max: 2.0, Curve: 0.5, Symmetric: False)

decay

decay time (sec).

(Min: 0.0, Max: 2.0, Curve: 0.5, Symmetric: False)

sustain

sustain amplitude 0-1. The only part of ADSR that (confusingly, by convention) is not a time value..

(Min: 0.0, Max: 1.0, Curve: 1, Symmetric: False)

release

release time (sec).

(Min: 0.0, Max: 5.0, Curve: 0.5, Symmetric: False)

alpha

envelope curve. 1 is linear, >1 is exponential..

(Min: 0.1, Max: 6.0, Curve: 1, Symmetric: False)

make_attack(attack_time)

Builds the attack portion of the envelope.

Parameters

attack_time – Length of the attack in seconds.

Return type

Signal

make_decay(attack_time, decay_time)

Creates the decay portion of the envelope.

Parameters
• attack_time – Length of the attack in seconds.

• decay_time – Length of the decay time in seconds.

Return type

Signal

make_release(note_on_duration)

Creates the release portion of the envelope.

Parameters

note_on_duration – Duration of midi note in seconds (release starts when the midi note is released).

Return type

Signal

output(note_on_duration)

By default, this envelope reacts as if it was triggered with midi, for example playing a keyboard. Each midi event has a beginning and end: note-on, when you press the key down; and note-off, when you release the key. note_on_duration is the amount of time that the key is depressed.

During the note-on, the envelope moves through the attack and decay sections of the envelope. This leads to musically-intuitive, but programatically-counterintuitive behaviour:

Example

Assume attack is .5 seconds, and decay is .5 seconds. If a note is held for .75 seconds, the envelope won’t pass through the entire attack-and-decay (specifically, it will execute the entire attack, and only .25 seconds of the decay).

If this is confusing, don’t worry about it. ADSR’s do a lot of work behind the scenes to make the playing experience feel natural.

Parameters

note_on_duration (Tensor) – Duration of note on event in seconds.

Return type

Signal

ramp(duration, start=None, inverse=False)

Makes a ramp of a given duration in seconds.

The construction of this matrix is rather cryptic. Essentially, this method works by tilting and clipping ramps between 0 and 1, then applying a scaling factor alpha.

Parameters
Return type

Signal

### ControlRateVCA¶

class torchsynth.module.ControlRateVCA(synthconfig, device=None, **kwargs)

Voltage controlled amplifier.

The VCA shapes the amplitude of a control input signal over time, as determined by another control signal. To shape audio-rate signals, use torchsynth.module.VCA.

output(audio_in, control_in)
Parameters
• control – Control signal input to shape with the VCA.

• amp_control – Time-varying amplitude modulation signal.

Return type

Signal

### LFO¶

class torchsynth.module.LFO(synthconfig, exponent=tensor(2.7183), **kwargs)

Low Frequency Oscillator.

The LFO shape can be any mixture of sine, triangle, saw, reverse saw, and square waves. Contributions of each base-shape are determined by the lfo_types values, which are between 0 and 1.

Parameters
• synthconfig (SynthConfig) – See SynthConfig.

• exponent (Tensor) – A non-negative value that determines the discrimination of the soft-max selector for LFO shapes. Higher values will tend to favour one LFO shape over all others. Lower values will result in a more even blend of LFO shapes.

Module Parameters
frequency

Frequency in Hz of oscillation.

(Min: 0.0, Max: 20.0, Curve: 0.25, Symmetric: False)

mod_depth

LFO rate modulation in Hz.

(Min: -10.0, Max: 20.0, Curve: 0.5, Symmetric: True)

initial_phase

Initial phase of LFO.

(Min: -3.1415927410125732, Max: 3.1415927410125732, Curve: 1, Symmetric: False)

make_control(mod_signal=None)

Applies the LFO-rate modulation signal to the LFO base frequency.

Parameters

mod_signal (Optional[Signal]) – Modulation signal in Hz. Positive values increase the LFO base rate; negative values decrease it.

Return type

Signal

make_lfo_shapes(argument)

Generates five separate signals for each LFO shape and returns them as a tuple, to be mixed by torchsynth.module.LFO.output().

Parameters

argument (Signal) – Time-varying phase to generate LFO signals.

Return type
output(mod_signal=None)

Generates low frequency oscillator control signal.

Parameters

mod_signal (Optional[Signal]) – LFO rate modulation signal in Hz. To modulate the depth of the LFO, use torchsynth.module.ControlRateVCA.

Return type

Signal

### ModulationMixer¶

class torchsynth.module.ModulationMixer(synthconfig, n_input, n_output, curves=None, input_names=None, output_names=None, **kwargs)

A modulation matrix that combines $$N$$ input modulation signals to make $$M$$ output modulation signals. Each output is a linear combination of all in input signals, as determined by an $$N imes M$$ mixing matrix.

Parameters
forward(*signals)

Performs mixture of modulation signals.

Return type

## Parameter Modules¶

Parameter modules simply output values.

class torchsynth.module.CrossfadeKnob(synthconfig, device=None, **kwargs)

Crossfade knob parameter with no signal generation

Module Parameters
ratio

(Min: 0.0, Max: 1.0, Curve: 1, Symmetric: False)

### HardModeSelector¶

class torchsynth.module.HardModeSelector(synthconfig, n_modes, **kwargs)

A hard mode selector. NOTE: This is non-differentiable.

forward()

Wrapper for output that ensures a buffer_size length output.

Return type

### MonophonicKeyboard¶

class torchsynth.module.MonophonicKeyboard(synthconfig, device=None, **kwargs)

A keyboard controller module. Mimics a mono-synth keyboard and contains parameters that output a midi_f0 and note duration.

Module Parameters
midi_f0

pitch value in ‘midi’ (69 = 440Hz).

(Min: 0.0, Max: 127.0, Curve: 1.0, Symmetric: False)

duration

note-on button, in seconds.

(Min: 0.01, Max: 4.0, Curve: 0.5, Symmetric: False)

forward()

Wrapper for output that ensures a buffer_size length output.

Return type

### SoftModeSelector¶

class torchsynth.module.SoftModeSelector(synthconfig, n_modes, exponent=tensor(2.7183), **kwargs)

A soft mode selector. If there are n different modes, return a probability distribution over them.

TODO: Would be nice to sample in a way that maximizes KL-divergence from uniform: https://github.com/torchsynth/torchsynth/issues/165

forward()

Normalize all mode weights so they sum to 1.0

Return type