Module pcm 

Lossless codec for uncompressed PCM audio.

Why this exists

zstd manages about 1.05x on 16-bit PCM — below the gate that decides a chunk is worth compressing at all, so the engine ships raw .wav untouched. That is the correct call for a general-purpose compressor, and it is the wrong outcome for a transfer whose payload is audio.

PCM is not high-entropy, it is correlated. Consecutive samples are close together and the two channels of a stereo pair are nearly the same signal. A general compressor looks for repeated byte strings and finds none, because a waveform never repeats exactly. Modelling the correlation instead is what FLAC does, and most of FLAC’s ratio comes from two cheap stages:

1. Decorrelate the channels. Send left and (left − right) rather than left and right; the difference of two similar signals is small.
2. Predict from previous samples and send only the error. A fixed polynomial predictor of order 0–4 costs a few adds per sample and turns a smooth waveform into residuals clustered near zero.

Small numbers clustered near zero is exactly what Rice coding encodes well, so that is the third stage. The predictor is solved per partition, by autocorrelation and Levinson–Durbin, so it follows the music through a track rather than assuming the signal is locally polynomial; fixed polynomial predictors are kept as the cheaper option and used whenever they win. On a real library this reaches 1.58x, against reference FLAC’s ~1.53x on the same files.

Formats

Every sample layout a WAV can hold: 8-bit unsigned, 16/24/32-bit signed, and 32-bit IEEE float. Each reaches the same signed-integer predictor by a different exactly-reversible step — 8-bit is biased by 128, 24-bit has no native type, float is scaled by a power of two chosen so the whole chunk lands on integers. Float that is genuinely fractional has no such scale, and is declined rather than rounded; nothing here ever approximates.

Why you can trust it with your only copy

Every encode is decoded again and compared against its input before it is accepted. If they differ for any reason at all, the encode is discarded and the caller falls back to zstd or to raw bytes. A bug in this file can therefore cost throughput, never a file.

Guarantees

Exactly lossless: decode(encode(x)) == x for every input, including inputs that are not really audio — and checked, per chunk, at encode time rather than merely intended. Anything the codec cannot model — an unsupported sample width, a chunk with no whole frames in it — is refused rather than approximated, and the caller falls back to zstd or to raw.

Chunk alignment

The engine splits files into fixed-size chunks that know nothing about frame boundaries, and a .wav file starts with a header, so a chunk generally begins mid-frame. Each encoded chunk therefore carries a raw prefix and suffix around the region it could actually model, and is entirely self-describing: the decoder needs no manifest, no format side-channel, and no neighbouring chunk.

Structs

AudioFormat

PCM layout, as read from a container header.

Enums

SampleFormat

How samples are laid out within a frame.

Functions

decode

Decode a chunk produced by encode, appending the original bytes to out.

encode

Encode one chunk of a PCM file.

parse_wav_header

Read a RIFF/WAVE header, returning the sample layout and where data starts.