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

import { WebMCodec } from "@suaveplan/audio-codecs/codecs/webm";

const decoded = await WebMCodec.decode(webmBytes);

Usage: Advanced Example

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.

2.6 KiB Raw Blame History

codecs/webm