libopus-wasm

Small, modern WebAssembly bindings for libopus raw packet encode/decode. One single-file ES module that runs unchanged in browsers and Node — no locateFile hook, no second .wasm request, no native build step.

The default path is realtime voice: 48 kHz, stereo, 20 ms frames, raw Opus packets, no Ogg/WebM container layer.

• Browser and Node from one import. Bundles cleanly with Vite, webpack, esbuild.
• Int16 and Float32 PCM — use whatever your pipeline already speaks.
• Loss-resilient — in-band FEC and packet-loss concealment.
• Tunable — bitrate, VBR/CBR, complexity, signal, bandwidth, DTX, plus a curated CTL passthrough.
• Drop-in @discordjs/opus adapter — same method shape, no node-gyp.

📖 Full documentation: libopus-wasm.dev

Install

npm install libopus-wasm

ESM-only; Node 20+ or any current browser. No @types install needed.

Quick start

import { createDecoder, createEncoder, getPacketInfo } from "libopus-wasm";

const encoder = await createEncoder(); // 48 kHz, stereo, 20 ms, audio
const decoder = await createDecoder();

const pcm = new Int16Array(encoder.frameSize * encoder.channels); // 960 * 2
const packet = encoder.encode(pcm);    // Uint8Array — one raw Opus packet
const info = await getPacketInfo(packet); // duration, frames, bandwidth
const frame = decoder.decode(packet);  // Int16Array — interleaved PCM

encoder.free();
decoder.free();

Both factories share one lazily-loaded WASM module; the first call pays the load cost and the rest are cheap.

Examples

Float32 PCM

Encode and decode floats directly — ideal for Web Audio:

const frame = new Float32Array(encoder.frameSize * encoder.channels); // [-1, 1]
const packet = encoder.encodeFloat(frame);
const decoded = decoder.decodeFloat(packet); // Float32Array

Batches

const packets = encoder.encodeFrames([frameA, frameB, frameC]); // Uint8Array[]
const frames = decoder.decodeFrames(packets);                   // Int16Array[]

Packet loss: FEC + concealment

// Encoder: enable in-band FEC and declare the expected loss rate.
const encoder = await createEncoder({ fec: true, packetLossPercent: 15 });

// Decoder: a packet is lost. If the next packet is in hand, recover from its
// FEC data; otherwise synthesize a concealment frame.
const recovered = decoder.decode(nextPacket, { decodeFec: true, frameSize: 960 });
const concealed = decoder.decodePacketLoss(960); // == decode(null, { frameSize: 960 })

See Packet loss for the full receive loop.

Tuning the encoder

const encoder = await createEncoder({
  application: Application.Audio,
  bitrate: 96000,        // or "auto" / "max"
  complexity: 10,        // 0..10
  signal: Signal.Music,
  vbr: true,
});

encoder.setBitrate(128000);
encoder.setMaxBandwidth(Bandwidth.Wideband);
encoder.getBitrate();    // 128000

Deterministic cleanup with using

{
  using encoder = await createEncoder();
  using decoder = await createDecoder();
  decoder.decode(encoder.encode(new Int16Array(960 * 2)));
} // both freed automatically at scope exit

discord.js compatibility

libopus-wasm/discordjs matches the @discordjs/opus method shape, minus the native toolchain. It is Node-only (uses Buffer) and loads asynchronously:

import { OpusEncoder } from "libopus-wasm/discordjs";

const opus = await OpusEncoder.create(48000, 2);
const packet = opus.encode(pcmBuffer);
const decoded = opus.decode(packet);
opus.setBitrate(64000);
opus.setFEC(true);
opus.free();

Or construct directly and await ready to keep existing call sites:

const opus = new OpusEncoder(48000, 2);
await opus.ready;

More in discord.js compatibility.

Browser

The main entry inlines the WASM, so it bundles with no plugins and needs no cross-origin isolation. Web Audio delivers Float32 samples that go straight into encodeFloat — see Browser usage for a microphone-capture walkthrough.

API overview

Full reference with every option and constant lives at libopus-wasm.dev/api-reference.

Top-level

| Function | Returns | Description | | --- | --- | --- | | loadLibopus() | Promise<{ version }> | Loads the module; returns the bundled libopus version. | | createEncoder(options?) | Promise<OpusEncoderHandle> | Create a raw-packet encoder. | | createDecoder(options?) | Promise<OpusDecoderHandle> | Create a raw-packet decoder. | | getPacketInfo(packet, options?) | Promise<OpusPacketInfo> | Validate a raw packet and return duration, frame count, channels, and bandwidth. |

Encoder

| Member | Description | | --- | --- | | encode(pcm, options?) | Encode one Int16 frame (Int16Array \| Uint8Array) → Uint8Array. | | encodeFloat(pcm, options?) | Encode one Float32Array frame → Uint8Array. | | encodeFrames / encodeFloatFrames | Batch variants → Uint8Array[]. | | setBitrate / getBitrate | Bitrate (number \| "auto" \| "max"). | | setComplexity setSignal setMaxBandwidth | Quality and bandwidth controls. | | setVbr setVbrConstraint setDtx | Rate-mode controls. | | setFec setPacketLossPercent | Loss-resilience controls. | | getLookahead getInDtx | Encoder state. | | encoderCtl(request, value) | Curated integer-setter CTL passthrough. | | free() / [Symbol.dispose]() | Release WASM memory. |

Read-only: application, channels, frameSize, sampleRate.

Decoder

| Member | Description | | --- | --- | | decode(packet, options?) | Decode a packet (or null for PLC) → Int16Array. | | decodeFloat(packet, options?) | Decode → Float32Array. | | decodeFrames / decodeFloatFrames | Batch variants; null entries are concealed. | | decodePacketLoss(frameSize?) | Synthesize one concealment frame. | | decodePacketLossFloat(frameSize?) | Float32 variant. | | decoderCtl(request, value) | Integer-setter CTL passthrough. | | free() / [Symbol.dispose]() | Release WASM memory. |

Read-only: channels, maxFrameSize, sampleRate.

Constants

Application (Voip, Audio, RestrictedLowDelay) · Signal (Auto, Voice, Music) · Bitrate (Auto, Max) · Bandwidth (Narrowband…Fullband) · EncoderCtl / DecoderCtl request codes · OpusError (code, operation).

Supported formats

| Constraint | Allowed values | | --- | --- | | Sample rate | 8000, 12000, 16000, 24000, 48000 Hz | | Channels | 1 (mono), 2 (stereo) | | Encode frame duration | 2.5, 5, 10, 20, 40, 60 ms | | Decode output capacity | up to 120 ms | | PLC / FEC frame size | multiples of 2.5 ms, up to 120 ms |

Validation errors (wrong frame size, out-of-range option, empty packet, non-allow-listed CTL) throw a RangeError before reaching WASM; libopus errors surface as OpusError.

Build from source

The npm package ships compiled output, so using it needs no toolchain. Building from source requires Emscripten (emcc) on PATH:

pnpm install
pnpm build
pnpm test

pnpm build downloads libopus 1.6.1 from Xiph.Org, verifies the pinned SHA-256, compiles it with Emscripten, and emits a single-file ES module under dist/generated/. See Building from source.

Benchmark

Native comparison requires @discordjs/opus to build on the host:

pnpm benchmark

Apple Silicon, Node 26, 20k iterations, 48 kHz stereo, 20 ms frames:

wasm encode:   15,304 ops/sec
native encode: 15,741 ops/sec
wasm decode:   38,416 ops/sec
native decode: 41,280 ops/sec

A regression check, not a portable score. CI also exposes a manual Benchmark workflow. More in Benchmark.

Documentation & license

Full docs: libopus-wasm.dev. Released under the MIT license; libopus carries its own BSD license, reproduced in THIRD_PARTY_NOTICES. Not affiliated with Xiph.Org.