`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 — 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

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:

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.

2.9 KiB Raw Permalink Blame History

codecs/ogg-vorbis