API reference¶

Every name on this page comes straight from import kudio: you call kudio.file_load, not kudio.core.io.file_load. The pages after this one document the same names module by module, with full signatures, every parameter, and the examples from the docstrings.

Audio files¶

Documented in full on Audio files.

Name	Kind	What it does
`audio_info`	function	Describe an audio file (or an in-memory waveform) without interpreting it.
`AudioDataManager`	class	Keyed store of audio clips: `{name: {dir, wave, sr, ch}}`.
`AudioInfo`	class	What a file is, before you decide whether to load it.
`check_file`	function	Normalize an output wave path: force the `.wav` suffix, create parent directories, and (optionally) rename to avoid overwriting an existing file.
`check_input`	function	Recursively collect `.wav` files from input.
`check_path`	function	Return `path` if it is free (or `exist_ok`), otherwise an incremented variant, e.g.
`convert_folder`	function	Resample / re-encode / trim / normalise every `.wav` file under src.
`ConvertResult`	class	What `convert_folder` did.
`copy_waves`	function	Copy wave files into directory path and return where they went.
`file_load`	function	Load a wave file;
`load_wave`	function	Load one wave file or a list of them into `(waveform, sr)` tuples.
`load_waves`	function	Convert every `.wav` in wave (see `check_input`) to waveform data.
`LoadAudio`	class	Iterate over the `.wav` files found (recursively) in a directory, collected the way `check_input` collects them.
`resample`	function	Resample a waveform already in memory.
`save_wave`	function	Write wave to an audio file via soundfile.

STFT and features¶

Documented in full on STFT and features.

Name	Kind	What it does
`ContextFrames`	class	`stack_context` over a whole corpus, stacked a batch at a time.
`denoise_spec2wav`	function	Inverse of `denoise_wav2spec`;
`denoise_wav2spec`	function	Peak-normalized magnitude spectrogram + phase, for denoising models.
`features2matrix`	function	Concatenate feature matrices;
`file_to_spectrogram`	function	File -> log-power spectrogram (see `waveform_to_spectrogram`).
`frame_windows`	function	Cut a feature matrix into fixed-length windows.
`logspec_from_files`	function	Convert each file to a log spectrogram and stack them.
`melspectrogram`	function	Audio -> stacked log-mel feature vectors `(n_vectors, n_mels * n_frames)`.
`mfcc`	function	Waveform -> MFCC, shaped `(1, n_frames, n_mfcc)`.
`mfcc_from_files`	function	Load each wave file and stack their MFCC matrices `(n_files, frames, n_mfcc)`.
`save_spectrogram_as_wave`	function	Reconstruct a waveform from enhanced_spec (phase from noisy_file) and write it to wave_out_dir as 16-bit PCM, clipped at full scale.
`spectrogram_to_waveform`	function	Log-power spectrogram -> waveform, reusing the phase of reference y.
`SpectrogramStream`	class	A rolling log-magnitude spectrogram, one column per hop.
`stack_context`	function	Stack `±context` neighbouring frames onto each frame.
`Standardizer`	class	Per-column mean/std normalisation, with the statistics saved alongside.
`STFT`	class	Immutable STFT settings, with the two transforms attached.
`wave_separate`	function	Split an interleaved multi-channel waveform into per-channel arrays.
`wave_slicing`	function	Slice a waveform into overlapping frames (flattened if is_reshape).
`waveform_to_spectrogram`	function	Waveform -> log-power spectrogram `(frames, bins)`, `log10(\\|X\\|^2)`.

Inspection¶

Documented in full on Inspection.

Name	Kind	What it does
`audio_report`	function	Inspect y without needing a clean reference to compare it against.
`AudioReport`	class	Reference-free measurements of one clip.
`dnsmos`	function	Predict P.835 opinion scores for y.
`DnsmosScore`	class	Three P.835 opinion scores, each on the 1–5 MOS scale.
`find_dnsmos_model`	function	Locate `sig_bak_ovr.onnx`.
`loudness`	function	Gated integrated loudness of y, in LUFS.
`loudness_over_time`	function	Loudness measured over a sliding window -- where a take drifted.
`loudness_range`	function	Loudness range in LU, to EBU Tech 3342.
`LoudnessCurve`	class	Loudness measured over a sliding window, in LUFS.
`match_loudness`	function	Scale y until it is as loud as reference.
`MOMENTARY`	constant	Convert a string or number to a floating-point number, if possible.
`normalize_lufs`	function	Scale y to lufs integrated loudness.
`SHORT_TERM`	constant	Convert a string or number to a floating-point number, if possible.
`true_peak`	function	Peak of the reconstructed waveform, in dBTP (BS.1770-4 Annex 2).

Speech activity and pitch¶

Documented in full on Speech activity and pitch.

Name	Kind	What it does
`f0`	function	Track the fundamental frequency of y with pYIN.
`PitchTrack`	class	A pitch contour plus the voicing decision that makes it readable.
`speech_ratio`	function	Fraction of the clip that `vad` calls speech, in `[0, 1]`.
`vad`	function	Find the spans of y that contain speech, in seconds.
`vad_frames`	function	`vad` as one decision per STFT frame, `True` for speech.
`vad_split`	function	The speech segments themselves, as waveforms.
`vad_trim`	function	Trim to the first and last speech, keeping whatever is between them.

Editing and effects¶

Documented in full on Editing and effects.

Name	Kind	What it does
`add_noise_snr`	function	Mix noise into y at the target signal-to-noise ratio (dB).
`band_filter`	function	Butterworth filter of any of the four kinds.
`bandpass`	function	Keep only `low..high` Hz.
`bandstop`	function	Remove `low..high` Hz.
`crossfade`	function	Join two clips through a short overlap, instead of butting them together.
`DEFAULT_CROSSFADE`	constant	Convert a string or number to a floating-point number, if possible.
`fade`	function	Fade both ends in one call.
`fade_in`	function	Ramp the first duration seconds up from silence.
`fade_out`	function	Ramp the last duration seconds down to silence.
`gain`	function	Apply a fixed gain in decibels.
`highpass`	function	Remove everything below cutoff Hz — rumble, handling noise, DC drift.
`lowpass`	function	Remove everything above cutoff Hz — hiss, and anything past the band a downstream model was trained on.
`normalize`	function	Scale so the loudest sample sits at peak.
`normalize_db`	function	Scale so the peak sits at dbfs decibels below full scale.
`pitch_shift`	function	Shift pitch by n_steps semitones without changing duration.
`random_gain`	function	Apply a random gain sampled uniformly from db_range dB.
`remove_dc`	function	Subtract the mean, per channel.
`reverb`	function	Cheap synthetic reverb via an exponentially-decaying comb filter: an echo every delay_ms, each decay times the one before.
`reverse`	function	Play the waveform backwards.
`spec_augment`	function	SpecAugment: mask random frequency bands and time spans of a spectrogram.
`splice`	function	Join several clips end to end, crossfading every seam.
`split_on_silence`	function	Split y into non-silent segments (each below-`top_db` gap is a cut).
`time_stretch`	function	Speed up (`rate>1`) or slow down (`rate<1`) without changing pitch.
`trim_silence`	function	Trim leading/trailing silence below `top_db` dB under peak.

Rooms and channels¶

Documented in full on Rooms and channels.

Name	Kind	What it does
`a_law`	function	The same, through the A-law curve -- G.711 as Europe specifies it.
`A_LAW_A`	constant	Convert a string or number to a floating-point number, if possible.
`apply_channel`	function	Run y through a whole link in the order a link does it.
`apply_rir`	function	Put y in the room described by ir.
`bit_depth`	function	Requantise y to bits, linearly.
`CHANNEL_DEFAULTS`	constant	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list.
`CHANNEL_PRESETS`	constant	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list.
`channel_spec`	function	Normalise spec -- a preset name, a dict, or `None` -- to a dict.
`channel_tag`	function	A short, stable description of spec, for a manifest or a filename.
`dropouts`	function	Drop packets, the way a bad link does.
`independent_burst`	function	The mean run length that independent loss at rate loss produces.
`mu_law`	function	Push y through the G.711 mu-law companding curve and back.
`MU_LAW_MU`	constant	Convert a string or number to a floating-point number, if possible.
`PACKET_MS`	constant	Convert a string or number to a floating-point number, if possible.
`Reverberation`	class	What a room does, measured from its impulse response.
`rir`	function	A synthetic room impulse response: exponentially decaying noise.
`rt60`	function	Measure a room from its impulse response, to ISO 3382-1.
`schroeder_curve`	function	Backward-integrated energy decay of ir, in dB, starting at 0.
`telephone`	function	Everything a phone line does, in the order it does it.
`TELEPHONE_BAND`	constant	Built-in immutable sequence.

Datasets¶

Documented in full on Datasets.

Name	Kind	What it does
`Label`	class	A named span of a recording, in seconds.
`load_labels`	function	Read labels written by `save_labels`, or by Audacity.
`load_manifest`	function	Read a manifest written by `save_manifest`.
`Pair`	class	One training example: a degraded file and the clean signal behind it.
`save_labels`	function	Write labels as JSON, or as an Audacity label track.
`save_manifest`	function	Write pairs to path as JSON.
`split_pairs`	function	Shuffle once, then cut into `(train, validation, test)`.
`Synthesizer`	class	Mix clean audio with noise at the requested SNRs.

Enhancement¶

Documented in full on Enhancement.

Name	Kind	What it does
`compare_enhancers`	function	Run several methods over the same clip and measure each one.
`CUSTOM_NOISE`	constant	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
`CustomEnhancer`	class	Anything that denoises, wrapped so it can be ranked with the rest.
`DecisionDirected`	class	The a priori SNR estimator of Ephraim & Malah, as state plus an update.
`enhance_folder`	function	Denoise every `.wav` file under src into dst.
`EnhanceFolderResult`	class	What `enhance_folder` did.
`EnhanceResult`	class	One run's output, with everything needed to rank it against another.
`estimate_noise_psd`	function	Noise power spectrum for every frame of `power` `(frames, bins)`.
`make_gain_rule`	function	The per-frame gain function for one of `RECURSIVE_METHODS`.
`make_noise_tracker`	function	A stateful tracker for method.
`Method`	class	An enhancement method: what it is, and what it lets you turn.
`METHODS`	constant	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list.
`NOISE_ESTIMATORS`	constant	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list.
`NoiseTracker`	class	A noise estimator as state plus one update, not a whole-file pass.
`Param`	class	One tunable knob, described well enough to build a control from it.
`RECURSIVE_METHODS`	constant	Built-in immutable sequence.
`spectral_enhance`	function	Enhance y with one of the methods in `METHODS`.
`STREAMABLE_METHODS`	constant	Built-in immutable sequence.
`StreamEnhancer`	class	Denoise a stream block by block, with a one-frame delay.
`trad_enhance`	function	Enhance waveform y using spectral subtraction with MCRA noise estimation and a Wiener-style gain function.
`wavelet_low_pass_filter`	function	Soft-threshold the detail coefficients of a wavelet decomposition.

Metrics and alignment¶

Documented in full on Metrics and alignment.

Name	Kind	What it does
`align`	function	Return ref and deg trimmed to the region they share, lined up.
`Alignment`	class	Where two recordings sit relative to each other.
`AudioEvaluate`	class	Evaluate enhanced audio against clean references.
`check_metrics_install`	function	Report availability of the optional metric back-ends.
`eval_metrics`	function	Score a single (reference, degraded) pair with every available metric.
`find_delay`	function	Measure how far deg sits after ref, to the nearest sample.
`MIN_CORRELATION`	constant	Convert a string or number to a floating-point number, if possible.
`pesq`	function	PESQ of deg against ref (ITU-T P.862 / P.862.2).
`score`	function	Score deg against ref: `{metric: value}`.
`sdi`	function	Speech distortion index: `sum((ref - deg)2) / sum(ref2)`.
`segmental_snr`	function	Frame-averaged (segmental) SNR in dB, clipped to [-10, 35] per frame.
`si_sdr`	function	Scale-invariant SDR (dB) — immune to overall gain differences.
`snr`	function	Signal-to-noise ratio (dB) of deg relative to ref (pure numpy).

Live audio¶

Documented in full on Live audio.

Name	Kind	What it does
`AudioBuffer`	class	Bounded FIFO of audio frames shared between producer/consumer threads.
`check_device`	function	List system devices and probe an input;
`CheckDevice`	class	Query/validate PortAudio devices.
`FetchBuffer`	class	Collect a fixed number of frames from an `AudioBuffer` in a background thread.
`is_available`	function	Smoke-test the terminal colors and the audio input stack.
`list_devices`	function	Devices as sounddevice sees them.
`LocalStreamReader`	class	Stream from a local microphone into an `AudioBuffer`, with optional live monitoring through the default output device.
`PA_FLOAT32`	constant	int([x]) -> integer int(x, base=10) -> integer
`PA_INT16`	constant	int([x]) -> integer int(x, base=10) -> integer
`play_audio`	function	Play audio from a file path, an opened `wave.Wave_read`, or an ndarray.
`record`	function	Blocking record for seconds via sounddevice (modern backend).
`Recorder`	class	Blocking recorder for a fixed duration.
`RemoteStreamReader`	class	Receive an audio stream over TCP and feed it into an `AudioBuffer` (optionally playing it back locally).
`StreamRecorder`	class	Record for as long as you like, and watch the level while it happens.
`wave_decode`	function	Raw int16 bytes -> array of shape `(chunk_length, channels)`.
`wave_encode`	function	Multi-channel array -> interleaved int16 bytes.

Configuration and errors¶

Documented in full on Configuration and errors.

Name	Kind	What it does
`AudioIOError`	class	Reading or writing an audio file failed.
`DependencyError`	class	An optional dependency is required for this operation but not installed.
`DeviceError`	class	An audio input/output device could not be opened or configured.
`FeatureError`	class	A feature, effect, room, channel or enhancement step refused its input or its settings: the wrong shape of audio, a parameter out of range, a clip too short to frame.
`KC`	class	Attribute-style config with YAML load/save and audio-centric defaults.
`KudioConfig`	class	Attribute-style config with YAML load/save and audio-centric defaults.
`KudioError`	class	Base class for every error raised by kudio.
`SynthesisError`	class	Noisy-data synthesis failed.
`UnsupportedFormatError`	class	The file type / dtype is not supported.

Utilities¶

Documented in full on Utilities.

Name	Kind	What it does
`find_duplicate`	function	Return the `Counter` dict of file_list, logging duplicated entries.
`lowercase`	function	The strings in lst, lower-cased.
`map_waves`	function	Apply fn to every item, optionally across `workers` processes.
`Timer`	class	Decorator: run func in a daemon thread, optionally joining for at most `time_delay` seconds.
`timer`	function	Decorator: log the wall-clock run time of func.
`uppercase`	function	The strings in lst, upper-cased.

Old names¶

Still importable, but each call warns and points at the new name. They will be removed in a future release.

Old name	Use instead
`blu`	`kudio.util.blu`
`color_test`	`kudio.util.color_test`
`concat_logspec`	`logspec_from_files`
`concat_logspec_`	`logspec_from_files`
`concat_mfcc`	`mfcc_from_files`
`concat_mfcc_`	`mfcc_from_files`
`contextual_LogSpectrogram`	`logspec_from_files`
`cya`	`kudio.util.cya`
`dkblu`	`kudio.util.dkblu`
`dkcya`	`kudio.util.dkcya`
`dkgre`	`kudio.util.dkgre`
`dkpur`	`kudio.util.dkpur`
`dkred`	`kudio.util.dkred`
`dkyel`	`kudio.util.dkyel`
`error`	`kudio.util.error`
`f2s`	`file_to_spectrogram`
`fGre`	`kudio.util.fGre`
`fRed`	`kudio.util.fRed`
`gre`	`kudio.util.gre`
`h1`	`kudio.util.h1`
`info`	`kudio.util.info`
`pur`	`kudio.util.pur`
`red`	`kudio.util.red`
`s2w`	`save_spectrogram_as_wave`
`spec2wav`	`save_spectrogram_as_wave`
`spec2wavform`	`spectrogram_to_waveform`
`upercase`	`uppercase`
`w2mfcc`	`mfcc`
`w2s`	`waveform_to_spectrogram`
`warn`	`kudio.util.warn`
`wav2mel`	`melspectrogram`
`wav2mfcc`	`mfcc`
`wav2spec`	`file_to_spectrogram`
`wavform2spec`	`waveform_to_spectrogram`
`yel`	`kudio.util.yel`