Tutorial 1 — Load and listen

The first thing to verify in any new corpus: you can read it, inspect it, and write it back without losing anything.

Option A — pull from the catalog

If you just want to try the toolkit without bringing your own audio, decipher.fetch downloads clips from the bundled public corpus:

from decipher import fetch

# One humpback song excerpt
clips = fetch(paper_id="001_payne_mcvay_1971",
              substrate="humpback_song_raw", limit=1)
src = clips[0]
print(src.path, src.sr, src.duration_s)

Option B — load your own file

from decipher import load_audio

src = load_audio(
    "data/raw/payne_excerpt.wav",
    source_url="https://example.org/dataset/payne_excerpt.wav",
    label="humpback_song",
)

print(src.path)
print(f"sr = {src.sr} Hz, duration = {src.duration_s:.2f} s")
print(f"original sr = {src.original_sr} Hz, original channels = {src.original_channels}")

Stereo files are downmixed to mono by mean. The original sample rate and channel count are preserved on the dataclass for provenance — this matters when the original is, say, a 96 kHz hydrophone recording later resampled to 16 kHz for an SSL model.

Inspect

To produce the spectrogram above:

from decipher.audio import render_spectrogram

render_spectrogram(
    src.samples, src.sr,
    out_path="figures/raw/excerpt_00.png",
    lo_hz=20, hi_hz=4000,
    title="raw excerpt",
)

Round-trip

Write the samples back; the result must be playable.

from decipher import write_wav

write_wav("data/processed/roundtrip.wav", src.samples, src.sr)

write_wav emits 16-bit PCM and applies a clipping safety divide if the peak exceeds 1.0. This is the simplest case of the round-trip invariant.

Resample

Use resample_to when you need a different sample rate. It uses torchaudio's Kaiser-windowed sinc resampler (the same parameters as HuBERT preprocessing).

from decipher import resample_to

x16k = resample_to(src.samples, sr_in=src.sr, sr_out=16000)
write_wav("data/processed/x16k.wav", x16k, 16000)

The function operates on raw arrays — wrap the result back into an AudioSource yourself if you want to preserve provenance through the resample.