Module dsp 

The signal core that every estimator uses.

It holds windows, the STFT, peak picking, active frames with their statistics, the analytic signal, decay fits, the stem descriptors, the modulation spectrum and the Lomb-Scargle periodogram.

Conventions that bind every estimator:

• Samples and spectra are f64 at the stem’s native rate.
• The window is the periodic Hann, w[n] = 0.5 - 0.5 cos(2 pi n / N).
• Frames are centred and zero-padded, with hop N/4. The layer chooses N from the median f0 of the note list: 8192 below 100 Hz, else 4096. A Hann main lobe is about 4 bins wide, so harmonics f0 apart need N >= 4 fs / f0.
• A frame is active when its RMS lies within 40 dB of the loudest frame. Statistics over active frames are the median and the interquartile range, which resist outliers.
• The transforms are not normalised; the caller scales.

Structs

ActiveFrames

The frames that carry signal: frame RMS within a gate of the loudest frame. Digital silence has no active frame.

AnalyticSignal

The analytic signal z = x + j H{x} of a real signal.

BandShare

The share of power in one band.

Baseband

One partial moved to baseband: complex samples at a reduced rate.

Decay

The decay of one tail: the noise floor and a decay time per fit range.

Descriptors

The descriptors of a stem.

FilterError

A filter cutoff that the sample rate cannot carry.

FrameDescriptors

The descriptors of one frame.

HeterodyneParams

Settings of a band-pass heterodyne.

ModulationSpectrum

The magnitude spectrum of a detrended, Hann-windowed track, zero-padded 8x. Its resolution stays 1 / T; the padding samples it finer.

Peak

A spectral peak with its interpolated position.

Shape

The shape of a folded cycle.

Snap

A rate snapped to the nearest note division.

Stats

The median and the interquartile range of a value over active frames, in its unit type.

Stft

A planned STFT. It computes one frame at a time into a buffer it owns, so a long stem never holds its whole spectrogram in memory.

StftParams

The frame layout of an STFT: frame length N, hop, window, padding and FFT oversampling.

Summary

The median and the interquartile range of a set of values.

Track

A time series at its own rate, such as a band envelope.

Enums

DecayFailure

Why a decay fit has no value.

FitRange

The level range of a decay fit, in decibels below the start of the energy decay curve.

Padding

How a centred frame continues past either end of the signal.

ShapeKind

The coarse shape of a folded cycle. A sine and a triangle are never told apart.

StftError

STFT parameters that cannot work.

Window

An analysis window. Every window is periodic: its N samples are the first N of a symmetric window of length N + 1, as spectral analysis expects. The symmetric form shifts every bin slightly.

Constants

ACTIVE_GATE_DB

The gate of the project’s convention: a frame is active when its RMS lies within 40 dB of the loudest frame.

ATTACK_LOW_PASS_HZ

The default low-pass for an attack envelope. A 5 Hz smoother smears any attack shorter than tens of milliseconds; 100 to 200 Hz keeps it.

BAND_CONVENTION

The convention of the band shares.

BAND_EDGES_HZ

The band edges of the band shares in hertz. The edges are a project choice.

BPM_SCAN

The tempo scan of the snap, as a share of the BPM on either side.

FLATNESS_CONVENTION

The convention of the flatness.

FLATNESS_FLOOR

The flatness floor, applied after the window-sum scale.

FOLD_BINS

The bins of a folded cycle.

GRID_STEP_HZ

The step of the trial frequencies.

LEVEL_CONVENTION

The convention of the levels.

LINE_PROMINENCE

How many times above the median amplitude of the scan a rate line must stand.

MIN_ACTIVE_FRAMES

The fewest active frames a statistic over frames needs; with fewer it gives no estimate.

MIN_CYCLES

A rate needs this many full cycles in the span. A pure count, so a bare f64.

MIN_LINE_DEPTH

A rate line needs at least this relative depth: the amplitude of its sine in the log track, about the share by which the level swings.

SCAN_BOTTOM_HZ

The bottom of the modulation scan unless the 4-bar rate lies lower.

SCAN_TOP_HZ

The top of the modulation scan. Above it a modulation leaves the envelope domain and shows as sidebands.

SETTLE_S

The settling time after an onset whose samples are left out.

SHAPE_CONVENTION

The convention of the shape descriptors.

SPECTRUM_OVERSAMPLE

Zero padding of the modulation spectrum.

TRACK_RATE_HZ

The rate of envelope tracks: a 5 ms hop, Nyquist at 100 Hz.

Functions

am_depth

The modulation depth of an envelope, (max - min) / (max + min). Returns None for an empty or all-zero envelope.

backward_integral

The Schroeder integral of an energy sequence: element n is the sum from n to the end. Summed backward, so the small late terms add first.

band_envelope

The envelope of one band at 200 Hz: band_magnitude, then the mean of each 5 ms block.

band_magnitude

The envelope of the band from lo to hi.

band_pass_zero_phase

Band-passes a signal with a fourth-order Butterworth high-pass at lo and low-pass at hi, each run forward and backward, so the band has no delay.

cmndf_period

The period of a track between 1 / hi and 1 / lo.

describe

Computes the descriptors of a mono signal.

fold

Folds a track over a period into 64 bins: bin b is the mean of the samples whose phase falls in [b / 64, (b + 1) / 64). The result is one cycle of the waveform.

frame_descriptors

Computes the descriptors of one magnitude frame, already divided by the window sum, with bins bin_hz apart. Returns None for an all-zero frame, or for one with a negative, NaN or infinite magnitude.

frame_rms

Returns the RMS of each centred frame of an STFT layout, over the raw samples (no window) with the layout’s padding. Frame m lines up with STFT frame m.

gated_samples

The samples of a level track that a modulation estimate may use: level within 40 dB of the track’s peak, inside a note, and at least settle after the note’s onset.

grid

The trial frequencies from lo to hi in 0.01 Hz steps.

heterodyne

Moves the band around centre to baseband, so a tone at f_c + d comes out at d.

interpolate

Interpolates the local maximum at bin k of a magnitude spectrum.

local_maxima

Returns the bins of the strict local maxima of a magnitude spectrum, skipping the first and the last bin.

lomb_scargle

The periodogram of values at times, one power per frequency.

low_pass_zero_phase

Low-passes a signal forward and then backward with a fourth-order Butterworth, so the result has no delay: an attack stays where it is. For attack envelopes use ATTACK_LOW_PASS_HZ.

periodogram_rate

The modulation rate of irregular samples between lo and hi.

quantile

The linear quantile of sorted values, the default of numpy.quantile. Returns None for no values.

scan_range

The scan range at a tempo: from two semitones below min(0.2 Hz, the 4-bar rate) to 20 Hz.

shape

Reads the shape of a folded cycle, or None for a flat one.

snap

Snaps a rate to the nearest division at a tempo, in log distance.

snap_scan

Snaps a rate at the BPM and at tempos within 2 % of it, in 0.1 % steps, and returns the snap with the smallest residual. A drifting tempo shows as a best BPM away from the nominal one.

strongest_peak

Returns the interpolated peak with the largest magnitude between bins lo and hi inclusive, or None when the range holds no local maximum.

Type Aliases

Complex64

Alias for a Complex<f64>