Generators

Collection of audio signal generators.

This module is part of the libdamp package.

class libdamp.generators.Generator(*args: Any, **kwargs: Any)

Bases: ABC, Module

Base class for stateful audio generators in libdamp.

Child classes must implement three core methods: - generate(): generate an audio signal from the current parameters - update(): set parameters of the generator - clear(): reset internal states to initial state

abstractmethod generate(*args, **kwargs) → Tensor

Generate audio from the current parameters.

Returns:

Generated audio signal.

Return type:

torch.Tensor

abstractmethod update(*args, **kwargs) → None

Update generator parameters.

Change the parameters that influence how the signal is generated in generate(). Actual arguments depend on the implemented functionality and should be documented in derived classes.

abstractmethod clear() → None

Reset generator internal state.

If the generator has state (i.e., a call to generate() depends on previous calls), this method should reset any state variables so that the generator behaves as if it was just initialized.

forward(*args, **kwargs) → Tensor

Generate audio (implements torch.nn.Module forward pass).

Calls generate() with the provided arguments.

Returns:

Generated audio signal.

Return type:

torch.Tensor

class libdamp.generators.SinusoidalOsc(frame_len: int, fs: float, interp_f: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const', interp_a: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const')

Bases: Generator

Generator for independent sinusoids with given amplitude and frequency.

generate(sum_up: bool = True) → Tensor

Generate audio from the current parameters.

Parameters:

sum_up (bool) – whether or not the individual sinusoids are summed up before returning the signal tensor in generate() (default: True)

Returns:

Audio signal of shape (B, samples) if sum_up=True or (B, sinusoids, samples) if sum_up=False.

Return type:

torch.Tensor

update(f: Tensor, a: Tensor) → None

Update the sinusoid parameters.

Parameters:

• f (torch.Tensor or array-like) – Frequencies for each sinusoid, shape (B, sinusoids, frames) in Hz.

• a (torch.Tensor or array-like) – Amplitudes for each sinusoid, shape (B, sinusoids, frames).

clear()

Reset generator internal state.

If the generator has state (i.e., a call to generate() depends on previous calls), this method should reset any state variables so that the generator behaves as if it was just initialized.

class libdamp.generators.HarmonicOsc(frame_len: int, fs: float, sum_up: bool = True, interp_f: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const', interp_a: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const')

Bases: Generator

Generator for harmonic sinusoids with given amplitude and fundamental frequency.

generate() → Tensor

Generate audio from the current harmonic parameters.

Returns:

Audio signal of shape (B, samples) if sum_up=True or (B, harmonics, samples) if sum_up=False.

Return type:

torch.Tensor

update(f0: Tensor, a: Tensor, inharmonicity: Tensor | None = None) → None

Update the harmonic oscillator parameters.

Parameters:

• f0 (torch.Tensor or array-like) – Fundamental frequencies, shape (B, frames) in Hz.

• a (torch.Tensor or array-like) – Harmonic amplitudes, shape (B, harmonics, frames).

• inharmonicity (torch.Tensor or array-like, optional) – Inharmonicity factors (frequency multipliers for each harmonic), shape (B, harmonics, frames). Default: None (uses perfect harmonics).

clear()

Reset generator internal state.

If the generator has state (i.e., a call to generate() depends on previous calls), this method should reset any state variables so that the generator behaves as if it was just initialized.

class libdamp.generators.BandFilteredNoise(frame_len: int, num_bands: int, order: int, fs: float)

Bases: Generator

Generator for band-filtered white noise

update(fc: Tensor, bw: Tensor, ba: Tensor)

Set amplitudes, bandwidths, and center frequencies.

Parameters:

• fc (torch.Tensor) – Center frequencies of the noise bands in Hz, shape (B, frames, N).

• bw (torch.Tensor) – Band width of the noise bands in Hz, shape (B, frames, N).

• ba (torch.Tensor) – Band amplitudes of the noise bands, shape (B, frames, N).

Returns:

Generated filtered noise signal consisting of summed-up noise bands, shape (B, frames * L).

Return type:

torch.Tensor

generate(sum_up: bool = True) → Tensor

Generate band-filtered white noise with specified amplitudes, bandwidths, and center frequencies.

Parameters:

sum_up (bool) – whether or not the individual sinusoids are summed up before returning the signal tensor in generate() (default: True)

Returns:

Generated filtered noise signal consisting of summed-up noise bands, shape (B, frames * L).

Return type:

torch.Tensor

clear()

Reset generator internal state.

If the generator has state (i.e., a call to generate() depends on previous calls), this method should reset any state variables so that the generator behaves as if it was just initialized.

class libdamp.generators.SimpleFilteredNoise(frame_len: int, filt_len: int, fs: float, freq_bands)

Bases: Generator

Generator for simple filtered white noise with linear filters.

generate(mags: Tensor) → Tensor

Generate filtered white noise with specified magnitude response.

Parameters:

mags (torch.Tensor) – Magnitudes for each frequency band, per frame, shape (B, frames, num_freq_bands).

Returns:

Generated filtered noise signal, shape (B, frames * L).

Return type:

torch.Tensor

update()

No-op. SimpleFilteredNoise is stateless and all parameters are passed directly to generate().

clear()

No-op. SimpleFilteredNoise is stateless and has no internal state to reset.

class libdamp.generators.WhiteNoise(*args: Any, **kwargs: Any)

Bases: Generator

Generator for full-scale white noise in time domain.

generate(shape, device=None) → Tensor

Generate full-scale white noise.

Parameters:

• shape (tuple of int) – Shape of the generated noise tensor, e.g. (B, channels, num_samples).

• device (torch.device or None) – Device to generate the noise tensor on (default: None, uses the default device).

Returns:

Generated white noise signal of the given shape, with values in [-1, 1).

Return type:

torch.Tensor

update()

No-op. WhiteNoise is stateless and has no parameters.

clear()

No-op. WhiteNoise is stateless and has no internal state to reset.

class libdamp.generators.ImpulseTrain(frame_len: int, num_harm: int, fs: float, sum_up: bool = True, interp_f: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const')

Bases: Generator

Generator for a band-limited impulse train with a given fundamental frequency.

generate()

Generate audio from the current parameters.

Returns:

Generated audio signal.

Return type:

torch.Tensor

update(f0, inharmonicity=None)

Update the impulse train fundamental frequency and optionally inharmonicity.

Parameters:

• f0 (torch.Tensor or array-like) – Fundamental frequencies, shape (B, frames) in Hz.

• inharmonicity (torch.Tensor or array-like, optional) – Inharmonicity factors (frequency multipliers for each harmonic), shape (B, harmonics, frames). Default: None (uses perfect harmonics).

clear()

Reset generator internal state.

If the generator has state (i.e., a call to generate() depends on previous calls), this method should reset any state variables so that the generator behaves as if it was just initialized.

class libdamp.generators.TableOsc(frame_len: int, table, table_param, fs: float, mode: Literal['pulse', 'wave'] = 'pulse', normalize: Literal['power', 'peak'] | None = None, learnable_table: bool = False, interp_f0: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const', interp_ts: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const', interp_entry: bool = True, table_freq=None, table_mask: Tensor | None = None)

Bases: Generator

Wave/Pulse Table Oscillator for reading out waveforms from a table.

generate()

Generate audio from the current parameters.

Returns:

Generated audio signal.

Return type:

torch.Tensor

update(f0, table_select)

Update the fundamental frequency and table selection parameter.

Parameters:

• f0 (torch.Tensor or array-like) – Fundamental frequencies, shape (B, frames) in Hz.

• table_select (torch.Tensor or array-like) – Table selection parameter (matched against table_param), shape (B, frames).

clear()

Reset generator internal state.

If the generator has state (i.e., a call to generate() depends on previous calls), this method should reset any state variables so that the generator behaves as if it was just initialized.

class libdamp.generators.WeightedTableOsc(frame_len: int, table, fs: float, mode: Literal['pulse', 'wave'] = 'pulse', normalize: Literal['power', 'peak'] | None = None, learnable_table: bool = False, interp_f0: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const', interp_w: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const', table_freq: float | None = None, table_mask: Tensor | None = None)

Bases: Generator

Wave/Pulse Table Oscillator for reading out waveforms from a table.

generate()

Generate audio from the current parameters.

Returns:

Generated audio signal.

Return type:

torch.Tensor

update(f0, weighting)

Update the fundamental frequency and per-entry table weights.

Parameters:

• f0 (torch.Tensor or array-like) – Fundamental frequencies, shape (B, frames) in Hz.

• weighting (torch.Tensor or array-like) – Weight of each table entry, shape (B, frames, num_entries).

clear()

Reset generator internal state.

If the generator has state (i.e., a call to generate() depends on previous calls), this method should reset any state variables so that the generator behaves as if it was just initialized.

class libdamp.generators.FMSynth(frame_len: int, fs: float, num_ops: int, connections: list[tuple[int, int]], interp_f0: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const', interp_r: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const', interp_m: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const')

Bases: Generator

Frequency Modulation (FM) Synthesis

generate()

Generate audio from the current parameters.

Returns:

Generated audio signal.

Return type:

torch.Tensor

update(f0, r, m)

Update generator parameters.

Change the parameters that influence how the signal is generated in generate(). Actual arguments depend on the implemented functionality and should be documented in derived classes.

clear()

Reset generator internal state.

If the generator has state (i.e., a call to generate() depends on previous calls), this method should reset any state variables so that the generator behaves as if it was just initialized.