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