@ndqp/bun-rusty-opus 0.0.0-stage → 0.2.1

package/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @ndqp/bun-rusty-opus — Bun/Node bindings to rusty-opus (pure-Rust Opus codec).
+ *
+ * `OpusEncoder` mirrors @discordjs/opus: one class that encodes AND decodes,
+ * s16le PCM Buffers in and out. See README.md for the full API.
+ *
+ * NOTE: this is the hand-written public type definition. The napi-rs
+ * generated types for the raw native binding live in lib/binding.d.ts.
+ */
+
+export type OpusApplication = 'voip' | 'audio' | 'lowDelay';
+export type OpusBandwidth = 'auto' | 'narrowband' | 'mediumband' | 'wideband' | 'superwideband' | 'fullband';
+export type OpusSignal = 'auto' | 'voice' | 'music';
+
+export interface OpusEncoderOptions {
+  /** 'voip' (speech), 'audio' (music/general, default), 'lowDelay' (CELT only). */
+  application?: OpusApplication;
+  /** Target bitrate in bits/sec. Default 64000. */
+  bitrate?: number;
+  /** Complexity 0 (fastest) to 10 (best quality). Default 9. */
+  complexity?: number;
+  /** Constant bitrate. Default false (VBR). */
+  cbr?: boolean;
+  /** @deprecated Use `cbr`. */
+  useCbr?: boolean;
+  /** In-band forward error correction (SILK LBRR). Default false. */
+  fec?: boolean;
+  /** @deprecated Use `fec`. */
+  useFec?: boolean;
+  /** Discontinuous transmission. Default false. */
+  dtx?: boolean;
+  /** @deprecated Use `dtx`. */
+  useDtx?: boolean;
+  /** Expected packet loss, 0-100 (%). Default 0. */
+  packetLoss?: number;
+  /** @deprecated Use `packetLoss`. */
+  packetLossPerc?: number;
+  /** Input bit depth assumed by the analysis (16 for s16 source, default). */
+  lsbDepth?: number;
+  /** Force an audio bandwidth, or 'auto' (default). */
+  bandwidth?: OpusBandwidth;
+  /** Cap the automatically selected bandwidth. Default 'fullband'. */
+  maxBandwidth?: OpusBandwidth;
+  /** Voice/music bias, or 'auto' (default). */
+  signal?: OpusSignal;
+}
+
+/**
+ * @discordjs/opus-compatible encoder/decoder.
+ *
+ * ```ts
+ * import { OpusEncoder } from '@ndqp/bun-rusty-opus';
+ * const encoder = new OpusEncoder(48000, 2);
+ * const packet = encoder.encode(pcmBuffer); // 20 ms s16le frame -> Opus
+ * const pcm = encoder.decode(packet);
+ * ```
+ */
+export declare class OpusEncoder {
+  constructor(rate?: number, channels?: number, options?: OpusEncoderOptions | OpusApplication);
+  readonly rate: number;
+  readonly channels: number;
+  readonly application: OpusApplication;
+  /**
+   * End-to-end encoder delay in samples per channel — the Ogg OpusHead
+   * pre-skip for streams encoded here. 120 at 48 kHz for CELT/Hybrid,
+   * 312 (scaled by rate) for SILK-only modes. See `opusPreSkip`.
+   */
+  readonly preSkip: number;
+
+  /** Encode one s16le PCM frame -> one Opus packet. `frameSize` in samples per channel; inferred from the buffer length when omitted. */
+  encode(pcm: Buffer | Uint8Array, frameSize?: number): Buffer;
+  /**
+   * Encode into a caller-provided output buffer. Returns bytes written.
+   * No Buffer is allocated per frame. `out` should hold at least 1276 bytes.
+   */
+  encodeInto(pcm: Buffer | Uint8Array, out: Buffer | Uint8Array, frameSize?: number): number;
+  /** Decode one Opus packet -> s16le PCM. `frameSize` inferred from the packet TOC when omitted. */
+  decode(packet: Buffer | Uint8Array, frameSize?: number): Buffer;
+  /** Decode into a caller-provided PCM buffer. Returns PCM bytes written. */
+  decodeInto(packet: Buffer | Uint8Array, out: Buffer | Uint8Array, frameSize?: number): number;
+  /** Reconstruct a lost frame from the in-band FEC (LBRR) in the *next* packet. `frameSize` is required. */
+  decodeFec(packet: Buffer | Uint8Array, frameSize: number): Buffer;
+  /** Packet-loss concealment: synthesise `frameSize` samples per channel for a lost frame. */
+  decodePacketLoss(frameSize: number): Buffer;
+
+  setBitrate(bitrate: number): void;
+  getBitrate(): number;
+  setFEC(enabled: boolean): void;
+  /** Expected packet loss, 0-100 (%). */
+  setPLP(percentage: number): void;
+  setPacketLoss(percentage: number): void;
+  setComplexity(complexity: number): void;
+  setCBR(enabled: boolean): void;
+  setDTX(enabled: boolean): void;
+  setBandwidth(bandwidth: OpusBandwidth): void;
+  setMaxBandwidth(bandwidth: OpusBandwidth): void;
+  setSignal(signal: OpusSignal): void;
+  setLsbDepth(depth: number): void;
+  /** Raw `opus_encoder_ctl` passthrough for the codes in `OPUS_CTL`. Unsupported codes throw. */
+  applyEncoderCTL(ctl: number, value: number): void;
+  /** rusty-opus exposes no decoder controls — this always throws. Kept for @discordjs/opus API parity. */
+  applyDecoderCTL(ctl: number, value: number): void;
+  /** Final range-coder state of the last encoded packet (OPUS_GET_FINAL_RANGE). */
+  finalRange(): number;
+  /** Final range-decoder state of the last decoded packet. */
+  lastRange(): number;
+}
+
+/** Decode-only codec. Same decoder as `OpusEncoder`, without an encoder. */
+export declare class OpusDecoder {
+  constructor(rate?: number, channels?: number);
+  readonly rate: number;
+  readonly channels: number;
+  decode(packet: Buffer | Uint8Array, frameSize?: number): Buffer;
+  decodeInto(packet: Buffer | Uint8Array, out: Buffer | Uint8Array, frameSize?: number): number;
+  decodeFec(packet: Buffer | Uint8Array, frameSize: number): Buffer;
+  decodePacketLoss(frameSize: number): Buffer;
+  lastRange(): number;
+}
+
+export declare const SUPPORTED_SAMPLE_RATES: readonly [8000, 12000, 16000, 24000, 48000];
+export declare const FRAME_DURATIONS_MS: readonly number[];
+export declare const OPUS_APPLICATIONS: Readonly<{ voip: 2048; audio: 2049; lowDelay: 2051 }>;
+export declare const OPUS_BANDWIDTHS: Readonly<{
+  auto: -1000;
+  narrowband: 1101;
+  mediumband: 1102;
+  wideband: 1103;
+  superwideband: 1104;
+  fullband: 1105;
+}>;
+export declare const OPUS_SIGNALS: Readonly<{ auto: 0; voice: 1; music: 2 }>;
+export declare const OPUS_CTL: Readonly<{
+  SET_APPLICATION: 4000;
+  SET_BITRATE: 4002;
+  SET_VBR: 4006;
+  SET_BANDWIDTH: 4008;
+  SET_MAX_BANDWIDTH: 4009;
+  SET_COMPLEXITY: 4010;
+  SET_INBAND_FEC: 4012;
+  SET_PACKET_LOSS_PERC: 4014;
+  SET_DTX: 4016;
+  SET_SIGNAL: 4024;
+  SET_LSB_DEPTH: 4036;
+  SIGNAL_AUTO: -1000;
+  SIGNAL_VOICE: 3001;
+  SIGNAL_MUSIC: 3002;
+}>;
+
+/** Infer the total output frame size (samples per channel) of an Opus packet from its TOC byte. */
+export declare function packetFrameSize(packet: Buffer | Uint8Array, rate: number): number;
+
+/**
+ * End-to-end encoder delay (pre-skip), in samples per channel, for the
+ * given rate and application. SILK-only (voip/audio at <= 16 kHz) is
+ * `round(rate * 312 / 48000)`; CELT/Hybrid is `round(rate * 120 / 48000)`.
+ * Unlike libopus, rusty-opus does not pad its output to a uniform 312 —
+ * use this value as the Ogg OpusHead pre-skip for streams encoded here.
+ */
+export declare function opusPreSkip(rate: number, application: OpusApplication): number;

package/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+// bun-rusty-opus — Bun/Node bindings to rusty-opus (pure-Rust Opus codec).
+//
+// The native binding is loaded by lib/loader.js (which delegates to the
+// napi-rs generated loader in lib/binding.js) and fails loudly with
+// ERR_BUN_RUSTY_OPUS_NO_PREBUILT when no prebuilt binary fits this machine.
+// This package never builds from source on install (see README).
+//
+// NOTE: `napi build` generates its loader as lib/binding.js (see the
+// `build` script in package.json) — it must NOT overwrite this file.
+
+module.exports = require('./lib/wrapper.js');

package/lib/binding.d.ts

@@ -0,0 +1,96 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
+/**
+ * One native codec: an encoder and a decoder sharing the same rate/channels.
+ * The JS `OpusEncoder` (encode + decode, @discordjs/opus shape) and the JS
+ * `OpusDecoder` (decode only) are both thin wrappers over this struct.
+ */
+export declare class NativeOpus {
+  rate(): number
+  channels(): number
+  getBitrate(): number
+  setBitrate(bitrate: number): void
+  setComplexity(complexity: number): void
+  setCbr(enabled: boolean): void
+  setFec(enabled: boolean): void
+  setDtx(enabled: boolean): void
+  setPacketLoss(percent: number): void
+  setBandwidth(code: number): void
+  clearBandwidth(): void
+  setMaxBandwidth(code: number): void
+  setSignal(code: number): void
+  setLsbDepth(depth: number): void
+  /**
+   * Raw `opus_encoder_ctl` passthrough for the CTL codes rusty-opus can
+   * express. Unknown / unsupported codes are an error, never silent.
+   * libopus CTL numbers: https://opus-codec.org/docs/opus_api-1.5/group__opus__encoderctls.html
+   */
+  applyEncoderCtl(ctl: number, value: number): void
+  /**
+   * rusty-opus exposes no decoder-side settings (no gain, no CTL), so
+   * every decoder CTL is an explicit error rather than a silent no-op.
+   */
+  applyDecoderCtl(ctl: number, value: number): void
+  finalRange(): number
+  lastRange(): number
+  /**
+   * `frame_size` is samples per channel; `0` infers it from the input
+   * length (`input.len() / (channels * 2)`).
+   */
+  encode(input: Buffer, frameSize: number): Buffer
+  /**
+   * Encode into a caller-provided output buffer. Returns bytes written.
+   * This is the zero-alloc hot path: no `Buffer` is created per frame.
+   */
+  encodeInto(input: Buffer, output: Buffer, frameSize: number): number
+  /**
+   * `frame_size` is the expected output samples per channel and is
+   * required here — the JS wrapper infers it from the packet TOC when
+   * the caller omits it. Pass an empty packet for PLC (lost frame).
+   */
+  decode(packet: Buffer, frameSize: number): Buffer
+  /** Decode into a caller-provided PCM buffer. Returns PCM bytes written. */
+  decodeInto(packet: Buffer, output: Buffer, frameSize: number): number
+  /** Reconstruct a lost frame from the LBRR in the *next* packet. */
+  decodeFec(packet: Buffer, frameSize: number): Buffer
+  /**
+   * Packet-loss concealment for a lost frame: synthesises `frame_size`
+   * samples per channel from decoder state.
+   */
+  decodePlc(frameSize: number): Buffer
+}
+
+/**
+ * JS entry point for creating a codec: `createOpus({ rate, channels,
+ * application, bitrate, complexity, useCbr, useFec, useDtx, packetLoss,
+ * lsbDepth })`. A free function (not a class constructor) so construction
+ * errors surface as a JS exception instead of a panic.
+ */
+export declare function createOpus(opts: OpusOptions): NativeOpus
+
+/**
+ * Creation options, passed as one JS object to `createOpus` — one argument
+ * instead of ten (clippy `too_many_arguments`), and the field names are the
+ * contract with `lib/wrapper.js` (`useCbr`, `packetLoss`, `lsbDepth`, ...).
+ */
+export interface OpusOptions {
+  rate: number
+  channels: number
+  application: number
+  bitrate: number
+  complexity: number
+  useCbr: boolean
+  useFec: boolean
+  useDtx: boolean
+  packetLoss: number
+  lsbDepth: number
+}

package/lib/loader.js

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Load the prebuilt native binding — and fail loudly if there is none.
+ *
+ * The actual loading is done by the napi-rs generated loader in
+ * `./binding.js` (regenerated by `npm run build`; do not hand-edit it).
+ * It tries a locally built `./bun-rusty-opus.<triple>.node` first, then the
+ * platform package `@ndqp/bun-rusty-opus-<triple>` installed as an
+ * optionalDependency. This file only translates its failure into the
+ * package's own error, so users get a clear message instead of napi-rs's
+ * generic "Cannot find native binding".
+ *
+ * There is intentionally NO build fallback here: no cargo, no node-gyp,
+ * no postinstall compile. If no prebuilt fits this machine, `require()`
+ * throws (and the `postinstall` check in `scripts/check-prebuilt.js`
+ * makes `npm install` / `bun install` fail at install time instead of
+ * at first use).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const BINARY_NAME = 'bun-rusty-opus';
+
+/** All triples CI builds (see .github/workflows/release.yml). */
+const SUPPORTED_TARGETS = [
+  'darwin-arm64',
+  'linux-x64-gnu',
+  'linux-x64-musl',
+  'linux-arm64-gnu',
+  'linux-arm64-musl',
+  'win32-x64-msvc',
+  'win32-arm64-msvc',
+];
+
+function isMusl() {
+  try {
+    if (fs.existsSync('/etc/alpine-release')) return true;
+    const { execFileSync } = require('node:child_process');
+    const out = execFileSync('ldd', ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return /musl/i.test(out);
+  } catch {
+    return false;
+  }
+}
+
+function candidateTriples() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if (platform === 'linux') {
+    const libc = isMusl() ? 'musl' : 'gnu';
+    const other = libc === 'musl' ? 'gnu' : 'musl';
+    return [`linux-${arch}-${libc}`, `linux-${arch}-${other}`];
+  }
+  if (platform === 'darwin') return [`darwin-${arch}`];
+  if (platform === 'win32') return [`win32-${arch}-msvc`];
+  return [];
+}
+
+function loadNative() {
+  const bindingPath = path.join(__dirname, '..', 'binding.js');
+  if (!fs.existsSync(bindingPath)) {
+    // Fresh checkout before any build — a dev problem, not a prebuilt one.
+    throw new Error(
+      '@ndqp/bun-rusty-opus: native binding has not been built yet (binding.js is missing). ' +
+        'Build it with `npm run build` (or `npm run build:local` for a native-CPU build).',
+    );
+  }
+  try {
+    return require(bindingPath);
+  } catch (err) {
+    const detected = `${process.platform}-${process.arch}${process.platform === 'linux' ? (isMusl() ? '-musl' : '-gnu') : ''}`;
+    const error = new Error(
+      `@ndqp/bun-rusty-opus: no prebuilt native binary for this machine (${detected}).\n` +
+        `Supported targets: ${SUPPORTED_TARGETS.join(', ')}.\n` +
+        `This package ships prebuilt binaries only and does not build from source on install. ` +
+        `If your platform is not listed, please open an issue at ` +
+        `https://github.com/nemesisqp/bun-rusty-opus/issues — do not try to build it by hand on this machine.\n` +
+        `Underlying loader error: ${err.message}`,
+    );
+    error.code = 'ERR_BUN_RUSTY_OPUS_NO_PREBUILT';
+    error.cause = err;
+    throw error;
+  }
+}
+
+module.exports = { loadNative, candidateTriples, SUPPORTED_TARGETS, BINARY_NAME };