Initial Commit

packages/media/audio/audio-codecs/src/codecs/ogg-vorbis.md

@@ -0,0 +1,82 @@
+# `codecs/ogg-vorbis`
+
+Lazy Ogg Vorbis codec — decode-only wrapper over
+`@audio/decode-ogg-vorbis` WASM module loaded on first use.
+
+## Purpose
+
+Ogg Vorbis is the canonical open-source lossy audio format that pre-dates
+Opus, still widely used in game audio and free-software distributions.
+The codec is decode-only because (a) the Vorbis encoder is a complex
+piece of perceptual-audio engineering best left to the canonical
+`libvorbis` implementation packaged separately, and (b) Opus is the
+preferred lossy encode target for new content.
+
+Implementation delegates to [`createWasmCodec`](./wasm-base.md) — see
+that document for the lazy-load, error-wrapping, and missing-module
+behaviour shared by every WASM wrapper.
+
+## Features
+
+- `name === "ogg-vorbis"`, extensions `["ogg", "oga"]`, MIME types
+  `["audio/ogg", "audio/vorbis"]`.
+- `canDecode(bytes)` — magic-byte sniff for `OggS`
+  (`0x4f 0x67 0x67 0x53`) at byte 0; rejects buffers shorter than 4
+  bytes.
+- Decode supported via `@audio/decode-ogg-vorbis`.
+- `supportsEncode: false` — encode throws
+  `AUDIO_CODECS.NOT_SUPPORTED` short-circuit (no WASM load).
+- Streaming factory absent.
+
+## Usage: Basic Example
+
+```ts
+import { OggVorbisCodec } from "@suaveplan/audio-codecs/codecs/ogg-vorbis";
+
+const decoded = await OggVorbisCodec.decode(oggBytes);
+console.log(decoded.sampleRate, decoded.channelData.length);
+```
+
+## Usage: Advanced Example
+
+Detect-then-dispatch from a mixed source via the registry:
+
+```ts
+import { CodecRegistry, OggVorbisCodec, OpusCodec, WavCodec } from "@suaveplan/audio-codecs";
+
+const registry = new CodecRegistry({
+    codecs: [WavCodec, OggVorbisCodec, OpusCodec],
+});
+
+const fmt = registry.detect(bytes);
+// Ogg containers may carry Vorbis or Opus; the first matching codec by
+// magic wins. If both Ogg-based codecs are registered, the codec
+// registered first takes precedence — register OpusCodec first if you
+// want Opus to win the tie.
+if (fmt === "ogg-vorbis") {
+    return registry.decode(bytes);
+}
+```
+
+## API Reference
+
+- `OggVorbisCodec: AudioCodec` — frozen constant; decode-only.
+- `canDecode(bytes)`, `decode(bytes, opts?)` — standard
+  `AudioCodec` contract; encode throws `NOT_SUPPORTED`.
+
+## Implementation Notes
+
+- The `OggS` magic is shared with Opus, FLAC-in-Ogg, and Ogg-Speex —
+  callers need to layer downstream sniffing if they need to
+  discriminate. The default registry order in `decode-source.ts`
+  registers Vorbis before Opus, which is the convention
+  for ambiguous Ogg payloads.
+- Encode is intentionally not supported. Preferred lossy
+  encode target is Opus; callers needing Vorbis output should run
+  `libvorbis` in a separate worker.
+- The first decode call lazily loads `@audio/decode-ogg-vorbis`;
+  subsequent calls reuse the memoised module.
+- Missing `@audio/decode-ogg-vorbis` → `AUDIO_CODECS.NOT_SUPPORTED`
+  with the module name in `context.module`.
+- Streaming factory absent — `CodecRegistry.decodeStream("ogg-vorbis",
+  …)` throws `AUDIO_CODECS.STREAM_ERROR`.