# @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

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```bash
bun add @suaveplan/audio-decode-wav
```

## Quick start

```ts
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:

```ts
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`](./src/decode-wav/decode-wav.md) — whole-buffer decoder.
- [`stream`](./src/stream/stream.md) — chunked streaming decoder.
- [`error-codes`](./src/error-codes/error-codes.md) — code registry + `AudioDecodeWavError`.
- [`otel`](./src/otel/otel.md) — telemetry surface (tracer, meter, counters, histogram).
- [`types/decoded-audio`](./src/types/decoded-audio.md) — frozen `DecodedAudio` type + schema.
- [`types/options`](./src/types/options.md) — `AudioDecodeOptions` type + schema.
- [`utils/inspect`](./src/utils/inspect.md) — 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.