Audio Preprocessing¶

Classes:

Name	Description
`AudioPipeline`	An ordered list of audio preprocessing steps for a fixed clip length.
`PeakNormalize`	Per-clip peak normalization: `y = x / max(max\|x\|, eps)`.
`Window`	Slice the waveform into overlapping frames and apply a window function.
`Spectrum`	Per-frame real-FFT magnitude (`power=1`) or power (`power=2`) spectrum.
`MelFilterbank`	Triangular mel filterbank, weighting spectrum bins onto the mel scale.
`Log`	Elementwise natural log with an additive floor: `y = ln(x + eps)`.
`DCT`	Orthonormal DCT-II keeping the first `num_coefficients` outputs.

dg.preprocess.AudioPipeline ¶

AudioPipeline(steps: list[Step], num_samples: int)

An ordered list of audio preprocessing steps for a fixed clip length.

num_samples is the clip length the deployed model expects, as int16 PCM samples. Call features to precompute training features, and pass the same pipeline to dg.export(model, preprocess=pipe) so training and deployed inference run identical steps. Training clips must be num_samples long, so a train/deploy mismatch fails immediately.

Parameters:

Name	Type	Description	Default
`steps`	`list[Step]`	Ordered preprocessing steps.	required
`num_samples`	`int`	Input clip length in samples.	required

Methods:

Name	Description
`features`	Precompute a whole dataset's training features.

features ¶

features(
    source: Tensor | Dataset,
    *,
    batch_size: int = 1024,
    num_workers: int = 0
) -> torch.Tensor

Precompute a whole dataset's training features.

Runs the pipeline once over the dataset rather than once per epoch. Wrap the returned tensor in a TensorDataset to train on it, and apply any augmentation on top of it rather than inside this call.

Inputs must match the shape and dtype this pipeline is configured for, so a train/deploy mismatch fails here. A Dataset yielding (sample, label) pairs has the label dropped; labels stay yours to keep track of.

Parameters:

Name	Type	Description	Default
`source`	`Tensor \| Dataset`	Stacked raw inputs, or a Dataset of raw samples.	required
`batch_size`	`int`	Samples per pipeline call. Lower it if memory is tight.	`1024`
`num_workers`	`int`	DataLoader workers for a Dataset source. Worth setting when decoding the samples dominates (JPEG frames, WAV clips).	`0`

Returns:

Type	Description
`Tensor`	The features in PyTorch's NCHW layout: `[N, C, H, W]` for images, `[N, 1, T, features]` for framed audio.

Raises:

Type	Description
`ValueError`	If `source` is empty.

dg.preprocess.PeakNormalize ¶

PeakNormalize(eps: float = 1e-06)

Per-clip peak normalization: y = x / max(max|x|, eps).

Automatic gain over the whole clip, so loud and quiet recordings scale alike. The peak needs the complete clip, so this suits clip-based inference rather than streaming. An all-zero clip yields all zeros.

Parameters:

Name	Type	Description	Default
`eps`	`float`	Floor value to avoid division by zero.	`1e-06`

dg.preprocess.Window ¶

Window(
    frame_length: int,
    hop: int,
    window: str | Tensor = "hann",
    input_scale: float = 1.0,
)

Slice the waveform into overlapping frames and apply a window function.

Frames start at sample 0 and advance by hop, with no padding and no centering. Any samples left over at the end are dropped.

Use input_scale=dg.preprocess.INT16_SCALE when feeding raw int16 samples straight in, without a PeakNormalize step first.

Parameters:

Name	Type	Description	Default
`frame_length`	`int`	Window length in samples.	required
`hop`	`int`	Hop size in samples.	required
`window`	`str \| Tensor`	`"hann"` (periodic, the default) or a 1D tensor of `frame_length` coefficients.	`'hann'`
`input_scale`	`float`	Scale factor applied to the input samples.	`1.0`

dg.preprocess.Spectrum ¶

Spectrum(n_fft: int, power: int = 2)

Per-frame real-FFT magnitude (power=1) or power (power=2) spectrum.

Frames are zero-padded on the right to n_fft, and the output has n_fft // 2 + 1 frequency bins. Matches numpy.fft.rfft and tf.signal.stft, so features computed elsewhere line up.

Parameters:

Name	Type	Description	Default
`n_fft`	`int`	FFT size (must be a power of two).	required
`power`	`int`	Return the magnitude (1) or power (2) spectrum.	`2`

dg.preprocess.MelFilterbank ¶

MelFilterbank(
    num_mels: int,
    sample_rate: int,
    f_min: float,
    f_max: float,
)

Triangular mel filterbank, weighting spectrum bins onto the mel scale.

Uses the HTK mel scale, with the triangles evenly spaced in the mel domain between f_min and f_max.

Parameters:

Name	Type	Description	Default
`num_mels`	`int`	Number of mel filter bins.	required
`sample_rate`	`int`	Sample rate in Hz.	required
`f_min`	`float`	Minimum frequency in Hz.	required
`f_max`	`float`	Maximum frequency in Hz.	required

dg.preprocess.Log ¶

Log(eps: float = 1e-06)

Elementwise natural log with an additive floor: y = ln(x + eps).

Expects nonnegative input (a spectrum or mel energies).

Parameters:

Name	Type	Description	Default
`eps`	`float`	Floor value to avoid log(0).	`1e-06`

dg.preprocess.DCT ¶

DCT(num_coefficients: int)

Orthonormal DCT-II keeping the first num_coefficients outputs.

The usual last step of an MFCC frontend: it decorrelates the log-mel energies and discards the higher coefficients.

Parameters:

Name	Type	Description	Default
`num_coefficients`	`int`	Number of DCT coefficients to keep.	required