first commit

docs/media/audio/audio-codecs/src/codecs/webm.md

@@ -0,0 +1,74 @@
+# `codecs/webm`
+
+Lazy WebM-audio codec — decode-only wrapper over `@audio/decode-webm`
+WASM module loaded on first use.
+
+## Purpose
+
+WebM is an open container format used primarily for video on the web,
+but with an audio-only profile that wraps Opus or Vorbis payloads in
+the EBML matroska-derived structure. This codec extracts the audio
+track from WebM containers and decodes it to PCM.
+
+The codec is decode-only because WebM-audio is almost always a
+*receive* format (downloaded from a server), not something callers
+need to emit. The canonical audio encode targets  are WAV,
+FLAC, and Opus. Implementation delegates to
+[`createWasmCodec`](./wasm-base.md) for the shared lazy-load and
+error-wrapping behaviour.
+
+## Features
+
+- `name === "webm"`, extensions `["webm"]`, MIME types
+  `["audio/webm"]`.
+- `canDecode(bytes)` — magic-byte sniff for the EBML header
+  `0x1a 0x45 0xdf 0xa3` at byte 0; rejects buffers shorter than 4
+  bytes.
+- Decode supported via `@audio/decode-webm`.
+- `supportsEncode: false` — encode throws `NOT_SUPPORTED`.
+- Streaming factory absent.
+
+## Usage: Basic Example
+
+```ts
+import { WebMCodec } from "@suaveplan/audio-codecs/codecs/webm";
+
+const decoded = await WebMCodec.decode(webmBytes);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { CodecRegistry, WebMCodec, WavCodec } from "@suaveplan/audio-codecs";
+
+const registry = new CodecRegistry({ codecs: [WebMCodec, WavCodec] });
+
+// Extract audio from a WebM upload and re-encode as WAV for analysis.
+const webmDoc = await registry.decode(webmBytes);
+const wavBytes = await registry.encode(webmDoc, "wav", { bitDepth: 24 });
+```
+
+## API Reference
+
+- `WebMCodec: AudioCodec` — frozen constant; decode-only.
+- `canDecode(bytes)`, `decode(bytes, opts?)` — standard `AudioCodec`
+  contract.
+- `encode()` — always throws `AUDIO_CODECS.NOT_SUPPORTED`.
+
+## Implementation Notes
+
+- WebM uses EBML, not RIFF, so the magic-byte signature is
+  fundamentally different from other audio containers. The four-byte
+  EBML header is a hard signal — false positives are rare in
+  practice.
+- The codec returns PCM regardless of whether the underlying audio
+  track is Opus or Vorbis — `@audio/decode-webm` handles the inner
+  codec dispatch.
+- WebM containers commonly carry video alongside audio; this codec
+  decodes only the audio track. Video handling is out of scope and
+  belongs to a separate `@suaveplan/video-*` package family.
+- Decode-only by design; first decode lazily loads
+  `@audio/decode-webm`. Subsequent calls reuse the memoised module.
+- Missing `@audio/decode-webm` → `AUDIO_CODECS.NOT_SUPPORTED`.
+- Streaming factory absent — `decodeStream("webm", …)` throws
+  `AUDIO_CODECS.STREAM_ERROR`.