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

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.2.0 — 2026-11-13
+
+- Vendored rusty-opus 1.0.2 into `vendor/rusty-opus/` with
+  `[patch.crates-io]` and bit-preserving decode patches (see
+  `vendor/rusty-opus/PATCHES.md`): AVX2/SSE2 kernels for `exp_rotation1`
+  (the PVQ rotation had a NEON kernel but no x86 twin; no FMA, unit-
+  tested bit-exact vs scalar), `#[inline(always)]` on `dec_bits` /
+  `read_byte` / `unext`, and the SIG_SAT clamp loop slicing first.
+  Decode 28.6 → 27.8 ms in `bench.mjs` (0.78x → 0.80x vs
+  @discordjs/opus, overall 1.15x). Two leads were measured and dropped:
+  `compute_u` never fires on real content and an AVX `kf_bfly2`
+  extraction did not vectorise (reverted).
+- Validation harness: `scripts/check-decode-parity.sh` (pristine 1.0.2
+  vs fork, bit-for-bit, 44 checks: 11 configs × normal/PLC/FEC decode
+  + encode bit-identity — all pass) and `test/decode-parity.test.mjs`
+  (JS interop vs libopus: RMS ~2e-5, max 1 s16 LSB; PLC asserted as
+  sanity, not libopus parity, because upstream PLC legitimately
+  diverges from libopus's concealment fade).
+- `docs/DECODE_ESTIMATE.md` corrected: the 22–24 ms fork estimate was
+  too optimistic (PVQ scaffolding, already-optimised IMDCT/postfilter);
+  the fork's ~3% is real and the harness makes future patches cheap to
+  validate.
+
+## 0.1.1 — 2026-11-13
+
+- Faster decode: the f32→i16 conversion on the decode path is now
+  runtime-dispatched SIMD (AVX2/SSE2 on x86_64, NEON on aarch64, scalar
+  tail + fallback) instead of a scalar loop that did not auto-vectorise.
+  Decode 33.1 → 28.7 ms in `bench.mjs` (0.66x → 0.77x vs
+  @discordjs/opus), `decodeInto` 31.7 → 27.7 ms. Rounding may differ by
+  1 LSB on exact-half values (nearest-even vs half-away-from-zero).
+- Investigation notes in `docs/PERFORMANCE.md`: the remaining decode
+  gap is inside rusty-opus's CELT/Hybrid decode (SILK decode is at
+  parity or faster); ruled out with measurements — per-frame allocation
+  (0), denormals/FTZ (1.00x), SIMD dispatch, native CPU flags, packet
+  content. Also noted: SILK encode at 16 kHz mono is ~3x slower than
+  libopus in the crate (not fixed here).
+
+## 0.1.0 — 2026-11-13
+
+First release.
+
+- napi-rs bindings to rusty-opus 1.0.2 (pure-Rust Opus codec, no libopus).
+- `OpusEncoder` with the @discordjs/opus API shape (encode/decode on s16le
+  PCM, `setBitrate`/`setFEC`/`setPLP`, `applyEncoderCTL`, `finalRange`/
+  `lastRange`), plus `OpusDecoder` (decode-only).
+- Zero-copy Buffers (`BufferSlice`) and zero-allocation hot path
+  (`encodeInto`/`decodeInto` with caller-provided output buffers; reused
+  f32 scratch; no heap allocation per frame after warm-up).
+- Prebuilt napi binaries for 7 platforms via GitHub Actions; install fails
+  (`ERR_BUN_RUSTY_OPUS_NO_PREBUILT`) when no prebuilt fits — no
+  install-time source build anywhere.
+- `encoder.preSkip` / `opusPreSkip(rate, application)`: the real
+  end-to-end delay (120 samples @48 kHz CELT/Hybrid, 312 scaled for
+  SILK-only) — not libopus's uniform 312.
+- Interop verified both ways with @discordjs/opus 0.11.0 (libopus):
+  packets decode correctly in both directions at matched bitrate.
+- 18 tests pass under Node (15 under Bun; the 3 interop tests skip there
+  because @discordjs/opus ships no Bun prebuild). Typecheck clean.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NĐQP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,197 @@
-# Temporary Holding Version
+# @ndqp/bun-rusty-opus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Personal project — quick test, not production ready.** This is an
+> experiment for trying out rusty-opus under Bun/Node. It is not
+> hardened, not audited, and not supported for production use. If you
+> need a production Opus binding, use
+> [@discordjs/opus](https://www.npmjs.com/package/@discordjs/opus) —
+> the battle-tested libopus binding whose API this project mirrors.
+
+Bun/Node bindings to [rusty-opus](https://crates.io/crates/rusty-opus) — a
+**pure-Rust Opus codec** (RFC 6716/8251, no C, no libopus, no FFI) by
+jinti and the Remade-With-Rust team (see [Credits](#credits)).
+Drop-in replacement for
+[@discordjs/opus](https://www.npmjs.com/package/@discordjs/opus), with the
+same `OpusEncoder` shape discord.js voice uses — but the codec underneath
+is Rust, and encode is faster. This project is only the thin binding
+between the two; the codec and the API it mirrors are other people's
+work, credited below.
+
+## Install
+
+```sh
+npm install @ndqp/bun-rusty-opus
+# or
+bun install @ndqp/bun-rusty-opus
+```
+
+**Prebuilt binaries only.** The package ships napi prebuilts for 7
+platforms (below). There is no install-time build and no fallback to
+compiling from source: if no prebuilt fits your machine, install **fails**
+with a clear error (`ERR_BUN_RUSTY_OPUS_NO_PREBUILT`) instead of silently
+building — or silently succeeding and breaking at first use. If you are
+developing this package itself, `npm run build` (or
+`scripts/build-local.sh` for a `target-cpu=native` dev build) is the way.
+
+| OS | x86_64 | arm64 |
+| --- | --- | --- |
+| macOS | — (Intel Mac unsupported) | `darwin-arm64` |
+| Windows | `win32-x64-msvc` | `win32-arm64-msvc` |
+| Linux glibc | `linux-x64-gnu` | `linux-arm64-gnu` |
+| Linux musl (Alpine) | `linux-x64-musl` | `linux-arm64-musl` |
+
+Requires Node >= 18 or Bun >= 1.3.
+
+## Usage
+
+```js
+import { OpusEncoder, OpusDecoder } from '@ndqp/bun-rusty-opus';
+
+const encoder = new OpusEncoder(48000, 2); // rate, channels; defaults 48000/2
+const packet = encoder.encode(pcmBuffer);   // 20 ms s16le frame (3840 bytes) -> Opus
+const pcm = encoder.decode(packet);         // Opus packet -> s16le PCM
+
+const decoder = new OpusDecoder(48000, 2); // decode-only, same decoder
+```
+
+`frameSize` (samples per channel) is inferred when omitted: from the PCM
+buffer length for `encode`, from the packet TOC byte for `decode`. Valid
+frame sizes are 2.5/5/10/20/40/60 ms (and up to 120 ms in the codec); rates
+8000/12000/16000/24000/48000; channels 1/2.
+
+### Zero-allocation hot path
+
+For 50 frames/s/stream, `encode` allocates a Buffer per packet. Reuse one
+output buffer instead — no allocation per frame, no GC pressure:
+
+```js
+const outPacket = Buffer.alloc(1276);   // max Opus packet size
+const outPcm = Buffer.alloc(3840);      // one 20 ms stereo frame
+const n = encoder.encodeInto(pcmBuffer, outPacket, 960);   // n = bytes written
+const m = encoder.decodeInto(packet, outPcm, 960);         // m = PCM bytes written
+```
+
+The encoder also reuses a scratch f32 buffer internally and makes no heap
+allocation per frame after warm-up.
+
+### Options
+
+```js
+new OpusEncoder(48000, 2, {
+  application: 'audio',   // 'voip' | 'audio' (default) | 'lowDelay'
+  bitrate: 64000,         // default 64000 (see note below)
+  complexity: 9,          // 0-10, default 9
+  fec: false,             // in-band forward error correction
+  packetLoss: 0,          // expected loss, 0-100%
+  cbr: false, dtx: false,
+  bandwidth: 'auto', maxBandwidth: 'fullband', signal: 'auto',
+  lsbDepth: 16,           // 16 for s16 source (default)
+});
+```
+
+Also available, all @discordjs/opus-compatible: `setBitrate`/`getBitrate`,
+`setFEC`, `setPLP` (alias `setPacketLoss`), `setComplexity`, `setCBR`,
+`setDTX`, `setBandwidth`, `setMaxBandwidth`, `setSignal`, `setLsbDepth`,
+`applyEncoderCTL` (libopus CTL codes 4002/4006/4008/4009/4010/4012/4014/
+4016/4024/4036; 4000 application is rejected — set it in the constructor),
+`applyDecoderCTL` (always throws: rusty-opus exposes no decoder controls),
+`decodeFec(packet, frameSize)`, `decodePacketLoss(frameSize)`,
+`finalRange()` / `lastRange()`. Helpers: `packetFrameSize(packet, rate)`,
+`opusPreSkip(rate, application)`.
+
+## Differences from @discordjs/opus
+
+These are deliberate, measured, and tested (`test/interop.test.mjs`
+decodes each codec's packets with the other):
+
+- **Default bitrate is 64000 bps; @discordjs/opus defaults to 120000 bps**
+  (libopus `OPUS_AUTO`). If you switch and want identical output sizes,
+  set the bitrate explicitly. At matched bitrate, packet totals are within
+  a few percent.
+- **Pre-skip is not 312.** libopus pads every stream to a 312-sample
+  delay; rusty-opus does not. Its real end-to-end delay is 120 samples at
+  48 kHz for CELT/Hybrid modes and 312 (scaled by rate) for SILK-only
+  (voip/audio ≤ 16 kHz). Read it from `encoder.preSkip` and use it as the
+  Ogg OpusHead pre-skip — writing 312 for a 48 kHz CELT/Hybrid stream
+  trims 192 real samples (~4 ms) off the start. See `docs/PERFORMANCE.md`
+  for the measured table.
+- **No separate native decoder module** — same as @discordjs/opus: one
+  class encodes and decodes; `OpusDecoder` is a decode-only convenience.
+- **Pure Rust, no libopus.** rusty-opus is a from-scratch Rust port of
+  libopus 1.6, bit-exact on the RFC test vectors, and interoperates with
+  libopus both ways.
+
+## Performance
+
+Measured on this VM (shared 1.5 CPU, portable build), 10 s of 48 kHz
+stereo, 20 ms frames, bitrate matched at 64 kbps — see
+`docs/PERFORMANCE.md` for method and full numbers:
+
+- **encode ~1.3x faster** than @discordjs/opus (libopus)
+- **decode ~0.77x** (slower than libopus; was 0.66x before v0.1.1's SIMD
+  f32→i16 conversion — see `docs/PERFORMANCE.md` for the breakdown)
+- **overall ~1.15x**
+
+The crate's "1.5x faster" claim is about **encode** (CELT), which our
+measurements support (1.27–1.39x). It is not an overall figure, and this
+README does not present it as one. Both codecs run ~90–100x realtime here.
+
+## Why no `target-cpu=native` in the published builds?
+
+The project brief suggested compiling with native CPU flags. That would be
+a bug in a published prebuilt: a binary built with `-C target-cpu=native`
+on a CI runner can crash with an illegal instruction on a user's older
+CPU. rusty-opus already dispatches SIMD at runtime (AVX2/AVX/FMA/SSE2 on
+x86_64, NEON on arm64; `RUSTY_OPUS_ISA` can cap it), so the portable build
+still uses the fast paths. The release profile uses opt-level 3, fat LTO,
+and single codegen unit instead. `scripts/build-local.sh` offers
+`target-cpu=native` for your own machine only.
+
+## Development
+
+```sh
+npm ci
+npm run build        # napi build --platform --release
+npm test             # node:test, incl. interop tests vs @discordjs/opus
+npm run test:bun     # bun test (interop tests skip: @discordjs/opus has no Bun prebuild)
+npm run bench        # bench/bench.mjs
+npm run typecheck    # tsc --noEmit
+cargo clippy --all-targets -- -D warnings
+```
+
+Releasing: push a `v*` tag; `.github/workflows/release.yml` builds all 8
+prebuilts and publishes the main package plus the platform packages to
+npm (needs the `NPM_TOKEN` secret). `docs/DESIGN.md` documents the
+binding layout, the loader, and the gotchas found while building this.
+
+## Credits
+
+This project is a thin binding — almost all of the hard work is other
+people's:
+
+- **rusty-opus** — the codec itself: a pure-Rust port of libopus by
+  **jinti** (`shenjindi@fourz.cn`) and the **Remade-With-Rust** team
+  ([github.com/Remade-With-Rust/rusty-opus](https://github.com/Remade-With-Rust/rusty-opus),
+  BSD-3-Clause). The SILK/CELT/Hybrid implementation, the SIMD kernels,
+  the bit-exact RFC test vectors — all theirs. v0.2.0 vendors their
+  1.0.2 release with a few small decode patches (see
+  `vendor/rusty-opus/PATCHES.md`); the patches are mine, the codec is
+  theirs.
+- **The Opus codec** — rusty-opus is a port of libopus, whose authors
+  are Xiph.Org, Skype Limited, Octasic, Jean-Marc Valin, Timothy B.
+  Terriberry and contributors (full copyright notice in
+  `vendor/rusty-opus/COPYING`).
+- **@discordjs/opus** — by **iCrawl** (`icrawltogo@gmail.com`) and the
+  discord.js team ([github.com/discordjs/opus](https://github.com/discordjs/opus),
+  MIT). This binding mirrors its `OpusEncoder` API and uses it as the
+  interop reference in every test and bench. If this project looks
+  familiar, that is why.
+- **napi-rs** — the binding framework that makes the Rust↔JS boundary
+  work.
+
+## License
+
+MIT for the binding code in this repo. rusty-opus (including the
+vendored copy in `vendor/rusty-opus/`) is BSD-3-Clause; @discordjs/opus
+is MIT. See `vendor/rusty-opus/COPYING` for the codec's copyright
+notice.