Module audio 

Stem intake: decoding, mono, resampling and the Stem.

A file decodes at its native rate. A consumer that needs another rate resamples. The Stem adds the beat grid, the band edge, the flat-top flag and the stereo screen.

Samples are f64 from the decoder on. Every channel is kept, because the stereo statistics need both. Mono is the mean of the first two channels, the pair the stereo statistics read, with no gain normalisation. Only a consumer with a fixed input rate, such as the transcription model, resamples; analysis stays at the native rate.

use sound_to_patch::audio::{self, SampleRate};

let stem = audio::decode("bass.wav".as_ref())?.into_audio();
let mono = stem.mono();
let model_rate = SampleRate::new(22_050)?;
let resampled = audio::resample(&mono, stem.sample_rate(), model_rate)?;

Structs

Audio

Decoded audio: one or more channels of equal length at one sample rate. Every sample is finite.

BeatGrid

The beat grid from the BPM. The BPM gives the beat period, not where the first beat falls, so the offset is given, never estimated; it defaults to 0.

DecodeError

A file that does not decode: the path and the cause.

Decoded

A decoded file: its audio and the packets that became silence.

Division

A note division, such as a dotted eighth, that an LFO rate can lock to.

ResampleError

A resampling that failed: both rates and rubato’s message.

SampleRate

A sample rate in samples per second: a whole number above zero.

SkippedPacket

A packet that failed to decode and became silence.

Stem

The stem: native-rate samples with mid and side, the beat grid, the band edge, the flat-top flag and the stereo screen.

StereoScreen

The stereo screen of a stem or of a sample range.

StereoStats

The statistics of one band. A value is None when it does not exist: a silent channel, a zero mid or side, or no f0.

Tempo

The tempo of a stem: the given one, the refined one and the one used.

Enums

AudioError

A rule that decoded audio breaks.

Band

The bands of the screen.

Feel

The feel of a note division.

NoteValue

The length of a note division in beats, before its feel.

Constants

BAND_EDGE_CONVENTION

The convention of the band edge.

BAND_EDGE_MARGIN_DB

The margin above the noise floor that the fallback band-edge rule needs.

BAND_EDGE_PLATEAU_DB

The plateau allowance of a steep fall in the band-edge rule.

BAND_EDGE_STEEP_DROP_DB

A fall of at least this much over one semitone marks a cutoff, and the band edge sits at its half-depth point. Synthetic cuts fall 57 to 91 dB there, a 2-pole roll-off about 1.3 dB.

BPM_STEP

The step of the tempo search, in BPM.

CEILING_TOLERANCE

Samples within this share of the peak count as at the ceiling.

CLIP_APPROACH

The approach share of a flat-top run.

FLAT_TOP_MIN_RUN_S

The shortest run at the ceiling that counts as a flat top.

FLAT_TOP_MIN_SHARE

The share of samples in flat-top runs that marks a stem hard-limited.

HARD_LIMITED_CONVENTION

The convention of the flat-top flag.

HIGH_EDGE_HZ

The edge between the low-mid and the high band. The descriptors use it as a band edge too.

LONG_FRAME_BELOW_HZ

The median f0 below which harmonic analysis uses its long frame.

MAX_BEAT_LAGS

The most beat lags the score sums.

MAX_SAMPLE_RATE

The highest sample rate the analysis reads, the top of the standard export rates. The cost of the analysis grows faster than the rate.

MAX_SKIPPED_PACKETS

The most packets a file may lose to decode errors.

MIN_BEAT_LAGS

The fewest beat lags that refine a tempo; a shorter stem keeps the given tempo.

MIN_SAMPLE_RATE

The lowest sample rate the analysis reads: the band-edge rule looks for its fall above 2 kHz, so it needs a Nyquist frequency well above that.

OVERLAP_BEATS

Beats of the stem that every lag keeps in its overlap, so the longest lag still averages several beats.

PEAK_RATIO_MIN

The lowest ratio of the best score to the median score over the search that the refined tempo needs before it replaces the given one.

PERIODICITY_MIN

The lowest share of the onset strength that repeats at the refined beat.

SCREEN_FRAME_LEN

The STFT frame length of the screen, for every f0.

SCREEN_HARMONICS

The harmonics whose cross-spectrum phase the screen averages.

SEARCH_SHARE

How far the given tempo may lie from the true one: the search covers every tempo t with |given / t - 1| <= SEARCH_SHARE.

SHARPNESS_MIN

The lowest onset sharpness that trusts a refined tempo.

SPARSE_ONSETS_MAX

The most onsets per beat for which the sparse periodicity trusts a tempo.

SPARSE_PERIODICITY_MIN

The lowest share of the onset strength that repeats every 2 or every 4 refined beats, for a part whose beat periodicity is too low.

STEREO_CONVENTION

The convention of the screen.

SUB_EDGE_HZ

The upper edge of the sub band.

TEMPO_CONVENTION

The convention of the refined tempo in layers.json.

Functions

band_edge

The band edge of a mono signal: see BAND_EDGE_CONVENTION.

decode

Decodes the default audio track of a file at its native rate, with every channel kept: the audio track the container flags as default, else the first one with a known codec.

is_flat_topped

Whether a channel is flat-topped: see HARD_LIMITED_CONVENTION.

mono_mean

Mixes channels to mono as their mean. Mixing L = x with R = -x gives silence, and L = R = x gives x.

resample

Resamples a mono signal from one rate to another in f64.

stereo_screen

Runs the screen on two channels of equal length, or on a sample range of them. f0 is the fundamental from the caller; without it every ipd_deg is None.

write_wav

Writes audio to path as a WAV file of 32-bit float samples. Each sample rounds to the nearest f32.

write_wav_to

Writes audio to out as write_wav writes it to a file.