suaveplan/packages/media/audio/audio-decode-wav/README.md

@suaveplan/audio-decode-wav - Universal WAV decoder wrapper over @audio/decode-wav. Exposes decodeWav, createWavStreamDecoder, frozen DecodedAudio, AbortSignal propagation, AUDIO_DECODE.WAV.* error codes, and a full OpenTelemetry surface.

Universal WAV decoder wrapper over the upstream @audio/decode-wav library. Exposes a stable, OTel-instrumented, AbortSignal-honouring contract over a frozen, validated DecodedAudio shape that every sibling codec wrapper (audio-decode-mp3, audio-decode-flac, audio-decode-opus, …) will reuse. The package is part of the audio-decode-* family and

Documentation tree

• decode-wav — decodeWav(bytes, options?) is the headline entry-point of @suaveplan/audio-decode-wav: it takes a Uint8Array of W…
  • decode-wav — decodeWav(bytes, options?) is the headline entry-point of @suaveplan/audio-decode-wav: it takes a Uint8Array of W…
• error-codes — This module is the canonical registry of every error code raised by @suaveplan/audio-decode-wav, alongside the struct…
  • error-codes — This module is the canonical registry of every error code raised by @suaveplan/audio-decode-wav, alongside the struct…
• otel — This module wires @suaveplan/audio-decode-wav into OpenTelemetry: it builds (and caches) the tracer, meter, counters…
  • otel — This module wires @suaveplan/audio-decode-wav into OpenTelemetry: it builds (and caches) the tracer, meter, counters…
• stream — createWavStreamDecoder(options?) returns a WavStreamDecoder for callers who receive WAV bytes incrementally — `Read…
  • stream — createWavStreamDecoder(options?) returns a WavStreamDecoder for callers who receive WAV bytes incrementally — `Read…
• decoded-audio — DecodedAudio is the canonical shape every WAV decode in @suaveplan/audio-decode-wav resolves to. It is a frozen, va…
• options — AudioDecodeOptions is the option bag accepted by every public entry-point in @suaveplan/audio-decode-wav (`decodeWa…
• utils — inspectWavHeader(bytes) is the wrapper-layer pre-scan that classifies a WAV byte buffer before the upstream `@aud…
  • inspect — inspectWavHeader(bytes) is the wrapper-layer pre-scan that classifies a WAV byte buffer before the upstream `@aud…

Install

bun add @suaveplan/audio-decode-wav

Quick start

import { decodeWav } from "@suaveplan/audio-decode-wav";

const audio = await decodeWav(wavBytes);
console.log(audio.channels, audio.sampleRate, audio.durationSec);

Stream a WAV from an HTTP response:

import { createWavStreamDecoder } from "@suaveplan/audio-decode-wav";

const dec = createWavStreamDecoder();
const reader = response.body!.getReader();
try {
    for (;;) {
        const { done, value } = await reader.read();
        if (done) break;
        await dec.feed(value);
    }
    const audio = await dec.flush();
} finally {
    dec.free();
}

Features

• Whole-buffer decode via decodeWav(bytes, options?).
• Chunked decode via createWavStreamDecoder(options?).
• Seven error codes: AUDIO_DECODE.WAV.INVALID_INPUT, UNSUPPORTED_FORMAT, CORRUPT_HEADER, TRUNCATED_BODY, ABORTED, RESAMPLE_UNSUPPORTED, STREAM_INVARIANT_VIOLATION.
• Full OpenTelemetry surface — audio_decode_wav.bytes_in_total, audio_decode_wav.frames_out_total, audio_decode_wav.errors_total{code}, audio_decode_wav.op_duration_ms{op, outcome}, plus spans on the @suaveplan/audio-decode-wav tracer.
• AbortSignal propagation, including pre-aborted short-circuit.
• Zod-validated DecodedAudio + AudioDecodeOptions schemas.
• Header pre-scan distinguishes corrupt vs. truncated vs. unsupported inputs before invoking upstream.

Modules

• decode-wav — whole-buffer decoder.
• stream — chunked streaming decoder.
• error-codes — code registry + AudioDecodeWavError.
• otel — telemetry surface (tracer, meter, counters, histogram).
• types/decoded-audio — frozen DecodedAudio type + schema.
• types/options — AudioDecodeOptions type + schema.
• utils/inspect — pure-JS WAV header pre-scan.

Out of scope

• Resampling — surfaced as RESAMPLE_UNSUPPORTED; a future @suaveplan/audio-resample will pair with this package.
• Non-WAV formats — sibling audio-decode-{mp3,flac,opus,…} packages each wrap their own upstream decoder behind the same contract.
• Format dispatching — owned by the upcoming @suaveplan/audio-decode umbrella package.