first commit

docs/media/audio/audio-decode-wav/README.md

@@ -0,0 +1,81 @@
+# @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.
+