# `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`.