Shortcuts

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
  • synthconfig (SynthConfig) – An object containing synthesis settings that are shared across all modules, typically specified by Voice, or some other, possibly custom AbstractSynth subclass.

  • device (Optional[device]) – An object representing the device on which the torch tensors are to be allocated (as per PyTorch, broadly).

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
  • parameter_id (str) – Id of the parameter to update.

  • value (Tensor) – Value to assign to the parameter.

set_parameter_0to1(parameter_id, value)

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

Parameters
  • parameter_id (str) – Id of the parameter to update.

  • value (Tensor) – Value to assign to the parameter.

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)

Bases: torchsynth.module.SynthModule

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)

Bases: torchsynth.module.SynthModule

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)

Bases: torchsynth.module.SynthModule

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)

Bases: torchsynth.module.VCO

Simple VCO that generates a pitched sinusoid.

oscillator(argument, midi_f0)

A cosine oscillator. …Good ol’ cosine.

Parameters
  • argument (Signal) – The phase of the oscillator at each time sample.

  • midi_f0 (Tensor) – Fundamental frequency in midi (ignored in this VCO).

Return type

Signal

SquareSawVCO

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

Bases: torchsynth.module.VCO

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
  • argument (Signal) – The phase of the oscillator at each time sample.

  • midi_f0 (Tensor) – Fundamental frequency in midi.

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)

Bases: torchsynth.module.VCO

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
  • argument (Signal) – The phase of the oscillator at each time sample.

  • midi_f0 (Tensor) – Fundamental frequency in midi (ignored in this VCO).

Return type

Signal

output(midi_f0, mod_signal)
Parameters
  • midi_f0 (Tensor) – note value in midi

  • mod_signal (Signal) – audio rate frequency modulation signal

Return type

Signal

VCA

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

Bases: torchsynth.module.SynthModule

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)

Bases: torchsynth.module.SynthModule

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
  • synthconfig (SynthConfig) – An object containing synthesis settings that are shared across all modules, typically specified by Voice, or some other, possibly custom AbstractSynth subclass.

  • phase – Initial oscillator phase.

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
  • midi_f0 (Tensor) – Fundamental pitch value in midi.

  • mod_signal (Optional[Signal]) – Pitch modulation signal in midi.

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
  • argument (Signal) – The phase of the oscillator at each time sample.

  • midi_f0 (Tensor) – Fundamental frequency in midi.

Return type

Signal

output(midi_f0, mod_signal=None)

Generates audio signal from modulation signal.

Parameters
  • midi_f0 (Tensor) – Fundamental of note in midi note value (0-127).

  • mod_signal (Optional[Signal]) – Modulation signal to apply to the pitch.

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)

Bases: torchsynth.module.SynthModule

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

ADSR

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

Bases: torchsynth.module.ControlRateModule

Envelope class for building a control-rate ADSR signal.

Parameters
  • synthconfig (SynthConfig) – An object containing synthesis settings that are shared across all modules, typically specified by Voice, or some other, possibly custom AbstractSynth subclass.

  • device (Optional[device]) – An object representing the device on which the torch tensors are allocated (as per PyTorch, broadly).

Module Parameters

ADSR 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)

Generate an ADSR envelope.

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
  • duration (Tensor) – Length of the ramp in seconds.

  • start (Optional[Tensor]) – Initial delay of ramp in seconds.

  • inverse (Optional[bool]) – Toggle to flip the ramp from ascending to descending.

Return type

Signal

ControlRateVCA

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

Bases: torchsynth.module.ControlRateModule

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)

Bases: torchsynth.module.ControlRateModule

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

Tuple[Tensor, Tensor, Tensor, Tensor, Tensor]

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)

Bases: torchsynth.module.SynthModule

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
  • synthconfig (SynthConfig) – See SynthConfig.

  • n_input (int) – Number of input signals to module mix.

  • n_output (int) – Number of output signals to generate.

  • curves (Optional[List[float]]) – A positive value that determines the contribution of each input signal to the other signals. A low value discourages over-mixing.

forward(*signals)

Performs mixture of modulation signals.

Return type

Tuple[Signal]

Parameter Modules

Parameter modules simply output values.

CrossfadeKnob

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

Bases: torchsynth.module.SynthModule

Crossfade knob parameter with no signal generation

Module Parameters
ratio

crossfade knob.

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

HardModeSelector

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

Bases: torchsynth.module.SynthModule

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

forward()

Wrapper for output that ensures a buffer_size length output.

Return type

Tuple[Tensor, Tensor]

MonophonicKeyboard

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

Bases: torchsynth.module.SynthModule

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

Tuple[Tensor, Tensor]

SoftModeSelector

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

Bases: torchsynth.module.SynthModule

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

Tuple[Tensor, Tensor]

Read the Docs v: stable
Versions
latest
stable
v1.0.1
v1.0.0
Downloads
pdf
html
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.