loom-ai-org/snac-24khz-loom

SNAC 24 kHz (decoder)

Multi-Scale Neural Audio Codec at 24 kHz, decode half, exported for loom.cpp. Family 11: codec tokens in, a waveform out -- and the first with its codebooks at different frame rates.

This is a loom.cpp export: a single self-describing GGUF that carries its own graph topologies, tokenizer (if any) and driver script, produced by loom-exporter.

Original model

Exported from hubertsiuzdak/snac_24khz. Weights are unmodified; this repo packages the same parameters into loom.cpp's GGUF format.

License

mit, inherited from the base model above.

Language(s)

(none tagged upstream)

a codec, not a language model: it carries no vocabulary and no language. The upstream repo declares license: mit on its own card, and the package (github.com/hubertsiuzdak/snac) is MIT too.

Usage

Run it with loom-py -- loom-py-rt on PyPI:

pip install -U "loom-py-rt[hub]"

import loom

model = loom.Model.from_pretrained("loom-ai-org/snac-24khz-loom")

# The geometry a caller needs, declared by the file rather than looked up in a paper:
n_codebooks = model.hparam("codec.n_codebooks")       # code streams per frame
codebook_size = model.hparam("codec.codebook_size")   # valid id range per stream
frame_rate = model.hparam("codec.frame_rate", "f32")  # codes per second
print(n_codebooks, codebook_size, frame_rate, model.contract["sample_rate"])

# Codes are FRAME-MAJOR: all `n_codebooks` codes for frame 0, then frame 1, and so on. This file
# is the DECODE half -- real codes come from the matching encoder, or an AR model that emits them.
frames = round(frame_rate)                            # one second of audio
codes = [[0] * n_codebooks for _ in range(frames)]
audio = model.codes2speech.infer(codes)
print(len(audio), "samples at", audio.sample_rate, "Hz =", round(audio.duration, 3), "s")
audio.save("out.wav")

# A flat list works too, and is what a driver that emitted the codes hands over. One that is not a
# whole number of frames is refused rather than reinterpreted at a different width.
audio = model.codes2speech.infer([0] * (frames * n_codebooks))

The layer underneath

The call above is the high-level door: one per task, named for the modality pair it maps between, with the windowing, sampling and assembly this model needs already applied. Under it, model.infer(...) passes your arguments straight to the driver this GGUF embeds -- which is where you go for a knob the door does not name.

model.driver_source prints that driver, including a header comment documenting every argument it accepts for this model, and is the authority on it. See loom-py for the API and loom.cpp for what the engine does between the two.

Known limitations

This is the DECODE half only. encode is audio-in/codes-out -- a different contract with a different modality pair -- and no model that decodes through this codec ever calls it, so exporting it would be weight in the file for a door nothing opens. To go the other way, use the upstream checkpoint.

A row is one COARSEST frame, and it is 7 ids wide. SNAC's three codebooks run at different rates -- vq_strides [4, 2, 1], so codebook 0 emits one code where codebook 2 emits four -- and the flat frame-major layout this file takes is one row per coarsest frame at 11.72 frames per second, decoding to 2048 samples each. The 7 columns are level-major: column 0 is codebook 0, columns 1-2 are codebook 1's two sub-frames in order, columns 3-6 are codebook 2's four. An AR model that emits SNAC tokens 7 at a time (Orpheus and its relatives) may interleave them depth-first instead; rearranging them is the caller's job, as the delay pattern is.

The decode is stochastic, like the model it comes from, and it is seeded. SNAC's decoder adds randn * linear(x) at four points. A graph cannot draw that itself, so the driver draws it and passes it in -- seeded from seed= and defaulting to a fixed value, so two runs of the same codes agree unless you ask them not to:

a = model.codes2speech.infer(codes)              # the same waveform every time
b = model.codes2speech.infer(codes, seed=99)     # a different draw

Dropping the noise instead gives the mean of that distribution, which is 2.4% away in relative RMS and measurably duller up high; this file does not do that.

Its noise floor is reconstructed, not reproduced. At 0.98 kbps a steady background hiss in the source comes back slightly modulated -- audible as a slow wave under quiet passages. That is the upstream model's own behaviour at this bitrate, present in the reference decoder too, and not something the export introduces.

It does not undo a delay pattern. An AR model that emits these codes typically offsets stream k by k steps; realigning them is a property of that model, not of the codec, so feed it aligned codes.

Files

• snac-24khz.gguf -- the model, exported with loom-exporter.