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 otherSynthModule
instances. TheSynthModule
uses its (optional) input and its set ofModuleParameter
to generate output. AllModuleParameter
of theSynthModule
are assumed to bebatch_size
-length 1-D tensors.All
SynthModule
objects should be atomic, i.e., they should not contain otherSynthModule
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 byVoice
, or some other, possibly customAbstractSynth
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.
-
forward
(*args, **kwargs)¶ Wrapper for output that ensures a
buffer_size
length output.- Return type
-
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
-
get_parameter_0to1
(parameter_id)¶ Retrieves a specified parameter value in the normalized range [0,1].
-
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
-
p
(parameter_id)¶ Convenience method for retrieving a parameter value. Returns the value in parameter-specific, non-normalized range.
-
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.
-
set_parameter
(parameter_id, value)¶ Updates a parameter value in a parameter-specific non-normalized range.
-
set_parameter_0to1
(parameter_id, value)¶ Update a parameter value in a normalized range [0,1].
-
to
(device=None, **kwargs)¶ This function overrides the
to()
call intorch.nn.Module
. It ensures that the related valuesModuleParameterRange
andModuleParameter
, as well assynthconfig
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.
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].
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
-
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 timesBASE_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
synthconfig (
SynthConfig
) – SeeSynthModule
seed (
int
) – random number generator seed for white noise
-
output
()¶ Performs the main action of
SynthModule
. Each child class should override this method.- Return type
SineVCO¶
-
class
torchsynth.module.
SineVCO
(synthconfig, device=None, **kwargs)¶ Bases:
torchsynth.module.VCO
Simple VCO that generates a pitched sinusoid.
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.
-
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).
-
oscillator
(argument, midi_f0)¶ A cosine oscillator. …Good ol’ cosine.
-
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
.
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 byVoice
, or some other, possibly customAbstractSynth
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.
-
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.
-
oscillator
(argument, midi_f0)¶ This function accepts a phase argument and generates output audio. It is implemented by the child class.
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 atcontrol_rate
.-
output
(*args, **kwargs)¶ Performs the main action of
ControlRateModule
. Each child class should override this method.- Return type
-
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.
-
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.
-
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 byVoice
, or some other, possibly customAbstractSynth
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
-
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
-
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
-
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.
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
.
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
) – SeeSynthConfig
.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.
-
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()
.
-
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, usetorchsynth.module.ControlRateVCA
.- Return type
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
) – SeeSynthConfig
.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.
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.
-
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.
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