rockbox-ffi 0.1.0

package/dist/node.js

@@ -0,0 +1,88 @@
+import {
+  SPEC,
+  resolveLibPath
+} from "./chunk-ewj9g332.js";
+import {
+  ChannelConfig,
+  CrossfadeMode,
+  DspReplayGainMode,
+  MixMode,
+  ReplayGainMode,
+  makeApi,
+  sineStereo
+} from "./chunk-raaa0pkf.js";
+
+// src/node.ts
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+var require2 = createRequire(import.meta.url);
+var koffi = require2("koffi");
+var TOK = {
+  void: "void",
+  ptr: "void *",
+  u32: "uint32",
+  i32: "int32",
+  u64: "uint64",
+  usize: "size_t",
+  f32: "float",
+  bool: "bool",
+  strbuf: "str",
+  i16in: "void *",
+  outsize: "void *"
+};
+function makeRaw() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const libPath = resolveLibPath(here, (k) => process.env[k], existsSync, join, dirname);
+  const lib = koffi.load(libPath);
+  const sym = {};
+  for (const [name, spec] of Object.entries(SPEC)) {
+    sym[name] = lib.func(name, TOK[spec.ret], spec.args.map((t) => TOK[t]));
+  }
+  return {
+    sym,
+    cstr(s) {
+      return s;
+    },
+    i16in(a) {
+      return Buffer.from(a.buffer, a.byteOffset, a.byteLength);
+    },
+    sizeOut() {
+      const buf = Buffer.alloc(8);
+      return { arg: buf, value: () => Number(buf.readBigUInt64LE(0)) };
+    },
+    takeString(p) {
+      if (p === null || p === undefined)
+        return null;
+      const str = koffi.decode(p, "char", -1);
+      sym.rb_string_free(p);
+      return str;
+    },
+    takeI16(p, len) {
+      const arr = koffi.decode(p, koffi.array("int16_t", len));
+      const copy = Int16Array.from(arr);
+      sym.rb_buffer_free(p, len);
+      return copy;
+    },
+    isNull(p) {
+      return p === null || p === undefined;
+    }
+  };
+}
+var api = makeApi(makeRaw());
+var { abiVersion, metadata, Dsp, Player } = api;
+export {
+  sineStereo,
+  metadata,
+  abiVersion,
+  ReplayGainMode,
+  Player,
+  MixMode,
+  DspReplayGainMode,
+  Dsp,
+  CrossfadeMode,
+  ChannelConfig
+};
+
+//# debugId=C34E81133977033C64756E2164756E21

package/dist/node.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/node.ts"],
+  "sourcesContent": [
+    "// Node.js backend + full API, using koffi for FFI. Import under Node:\n//   import { Dsp, Player, metadata } from \"rockbox-ffi/node\";\n//\n// Node has no built-in FFI, so this backend depends on `koffi`\n// (https://koffi.dev) — install it with `npm install koffi`.\n\nimport { existsSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { createRequire } from \"node:module\";\n\nimport { makeApi, sineStereo } from \"./api.ts\";\nimport { resolveLibPath, SPEC, type Raw, type Tok } from \"./ffi.ts\";\n\n// koffi ships as CommonJS; load it via require to keep ESM interop simple.\nconst require = createRequire(import.meta.url);\n// deno-lint-ignore no-explicit-any\nconst koffi: any = require(\"koffi\");\n\nconst TOK: Record<Tok, string> = {\n  void: \"void\",\n  ptr: \"void *\",\n  u32: \"uint32\",\n  i32: \"int32\",\n  u64: \"uint64\",\n  usize: \"size_t\",\n  f32: \"float\",\n  bool: \"bool\",\n  strbuf: \"str\", // koffi marshals a JS string to a NUL-terminated char*\n  i16in: \"void *\", // we pass a Buffer view of the Int16Array\n  outsize: \"void *\", // we pass a Buffer.alloc(8) and read it back\n};\n\nfunction makeRaw(): Raw {\n  const here = dirname(fileURLToPath(import.meta.url));\n  const libPath = resolveLibPath(\n    here,\n    (k) => process.env[k],\n    existsSync,\n    join,\n    dirname,\n  );\n\n  const lib = koffi.load(libPath);\n  const sym: Record<string, (...a: any[]) => any> = {};\n  for (const [name, spec] of Object.entries(SPEC)) {\n    sym[name] = lib.func(name, TOK[spec.ret], spec.args.map((t) => TOK[t]));\n  }\n\n  return {\n    sym,\n    cstr(s: string) {\n      // The `strbuf` params are typed \"str\"; koffi marshals the JS string.\n      return s;\n    },\n    i16in(a: Int16Array) {\n      return Buffer.from(a.buffer, a.byteOffset, a.byteLength);\n    },\n    sizeOut() {\n      const buf = Buffer.alloc(8);\n      return { arg: buf, value: () => Number(buf.readBigUInt64LE(0)) };\n    },\n    takeString(p: unknown) {\n      if (p === null || p === undefined) return null;\n      // Read a NUL-terminated char* of unknown length. (koffi's \"str\" type\n      // is unreliable for longer strings in 2.16 — this form is robust.)\n      const str = koffi.decode(p, \"char\", -1) as string;\n      sym.rb_string_free(p);\n      return str;\n    },\n    takeI16(p: unknown, len: number) {\n      const arr = koffi.decode(p, koffi.array(\"int16_t\", len)) as number[];\n      const copy = Int16Array.from(arr);\n      sym.rb_buffer_free(p, len);\n      return copy;\n    },\n    isNull(p: unknown) {\n      return p === null || p === undefined;\n    },\n  };\n}\n\nconst api = makeApi(makeRaw());\nexport const { abiVersion, metadata, Dsp, Player } = api;\nexport { sineStereo };\nexport * from \"./enums.ts\";\nexport type { Metadata, PlayerConfig, PlayerStatus } from \"./types.ts\";\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;AAMA;AACA;AACA;AACA;AAMA,IAAM,WAAU,cAAc,YAAY,GAAG;AAE7C,IAAM,QAAa,SAAQ,OAAO;AAElC,IAAM,MAA2B;AAAA,EAC/B,MAAM;AAAA,EACN,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,OAAO;AAAA,EACP,KAAK;AAAA,EACL,MAAM;AAAA,EACN,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,SAAS;AACX;AAEA,SAAS,OAAO,GAAQ;AAAA,EACtB,MAAM,OAAO,QAAQ,cAAc,YAAY,GAAG,CAAC;AAAA,EACnD,MAAM,UAAU,eACd,MACA,CAAC,MAAM,QAAQ,IAAI,IACnB,YACA,MACA,OACF;AAAA,EAEA,MAAM,MAAM,MAAM,KAAK,OAAO;AAAA,EAC9B,MAAM,MAA4C,CAAC;AAAA,EACnD,YAAY,MAAM,SAAS,OAAO,QAAQ,IAAI,GAAG;AAAA,IAC/C,IAAI,QAAQ,IAAI,KAAK,MAAM,IAAI,KAAK,MAAM,KAAK,KAAK,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;AAAA,EACxE;AAAA,EAEA,OAAO;AAAA,IACL;AAAA,IACA,IAAI,CAAC,GAAW;AAAA,MAEd,OAAO;AAAA;AAAA,IAET,KAAK,CAAC,GAAe;AAAA,MACnB,OAAO,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU;AAAA;AAAA,IAEzD,OAAO,GAAG;AAAA,MACR,MAAM,MAAM,OAAO,MAAM,CAAC;AAAA,MAC1B,OAAO,EAAE,KAAK,KAAK,OAAO,MAAM,OAAO,IAAI,gBAAgB,CAAC,CAAC,EAAE;AAAA;AAAA,IAEjE,UAAU,CAAC,GAAY;AAAA,MACrB,IAAI,MAAM,QAAQ,MAAM;AAAA,QAAW,OAAO;AAAA,MAG1C,MAAM,MAAM,MAAM,OAAO,GAAG,QAAQ,EAAE;AAAA,MACtC,IAAI,eAAe,CAAC;AAAA,MACpB,OAAO;AAAA;AAAA,IAET,OAAO,CAAC,GAAY,KAAa;AAAA,MAC/B,MAAM,MAAM,MAAM,OAAO,GAAG,MAAM,MAAM,WAAW,GAAG,CAAC;AAAA,MACvD,MAAM,OAAO,WAAW,KAAK,GAAG;AAAA,MAChC,IAAI,eAAe,GAAG,GAAG;AAAA,MACzB,OAAO;AAAA;AAAA,IAET,MAAM,CAAC,GAAY;AAAA,MACjB,OAAO,MAAM,QAAQ,MAAM;AAAA;AAAA,EAE/B;AAAA;AAGF,IAAM,MAAM,QAAQ,QAAQ,CAAC;AACtB,MAAQ,YAAY,UAAU,KAAK,WAAW;",
+  "debugId": "C34E81133977033C64756E2164756E21",
+  "names": []
+}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+export interface ReplayGain {
+    track_gain_db: number | null;
+    album_gain_db: number | null;
+    track_peak: number | null;
+    album_peak: number | null;
+    raw_track_gain: number;
+    raw_album_gain: number;
+    raw_track_peak: number;
+    raw_album_peak: number;
+}
+export interface AlbumArt {
+    kind: "bmp" | "png" | "jpeg" | "unknown";
+    offset: number;
+    size: number;
+    id3_unsync: boolean;
+    vorbis_base64: boolean;
+}
+export interface Cuesheet {
+    offset: number;
+    size: number;
+    encoding: "latin1" | "utf8" | "utf16le" | "utf16be" | "unknown";
+}
+export interface Metadata {
+    codec: string;
+    codec_id: number;
+    title: string;
+    artist: string;
+    album: string;
+    albumartist: string;
+    composer: string;
+    grouping: string;
+    comment: string;
+    genre: string;
+    year_string: string;
+    track_string: string;
+    disc_string: string;
+    mb_track_id: string;
+    track_number: number | null;
+    disc_number: number | null;
+    year: number | null;
+    duration_ms: number;
+    bitrate: number;
+    sample_rate: number;
+    filesize: number;
+    samples: number;
+    vbr: boolean;
+    first_frame_offset: number;
+    replaygain: ReplayGain;
+    album_art: AlbumArt | null;
+    cuesheet: Cuesheet | null;
+}
+export interface PlayerStatus {
+    state: "stopped" | "playing" | "paused";
+    index: number | null;
+    position_ms: number;
+    duration_ms: number;
+    queue_len: number;
+    metadata: Metadata | null;
+}
+export interface PlayerConfig {
+    sampleRate?: number;
+    bufferSeconds?: number;
+    volume?: number;
+    replaygainMode?: number;
+    replaygainPreampDb?: number;
+    replaygainPreventClipping?: boolean;
+    crossfadeMode?: number;
+    fadeOutDelayMs?: number;
+    fadeOutDurationMs?: number;
+    fadeInDelayMs?: number;
+    fadeInDurationMs?: number;
+    mixMode?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "rockbox-ffi",
+  "version": "0.1.0",
+  "description": "TypeScript bindings (Bun + Deno + Node.js FFI) for the Rockbox DSP / metadata / playback engine",
+  "license": "GPL-2.0-or-later",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./bun": {
+      "types": "./dist/bun.d.ts",
+      "import": "./dist/bun.js"
+    },
+    "./deno": {
+      "types": "./dist/deno.d.ts",
+      "import": "./dist/deno.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "prepublishOnly": "bun run build",
+    "smoke:bun": "bun run examples/smoke.bun.ts",
+    "smoke:deno": "deno run --allow-ffi --allow-read --allow-env examples/smoke.deno.ts",
+    "smoke:node": "tsx examples/smoke.node.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "koffi": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,221 @@
+// Runtime-agnostic high-level API, written once against the Raw backend.
+
+import type { Raw } from "./ffi.ts";
+import { CrossfadeMode, MixMode, ReplayGainMode } from "./enums.ts";
+import type { Metadata, PlayerConfig, PlayerStatus } from "./types.ts";
+
+const opt = (v: number | null | undefined): number =>
+  v === null || v === undefined ? Number.NaN : v;
+
+export function makeApi(raw: Raw) {
+  const s = raw.sym;
+
+  const abiVersion = (): number => Number(s.rb_ffi_abi_version());
+
+  const metadata = {
+    /** Parse the metadata of the audio file at `path`. */
+    read(path: string): Metadata {
+      const json = raw.takeString(s.rb_meta_read_json(raw.cstr(path)));
+      if (json === null) throw new Error(`could not read metadata from ${path}`);
+      return JSON.parse(json) as Metadata;
+    },
+    /** Guess the codec label from a filename's extension (null if unknown). */
+    probe(filename: string): string | null {
+      return raw.takeString(s.rb_meta_probe(raw.cstr(filename)));
+    },
+  };
+
+  /** Interleaved-S16LE-stereo DSP instance. Single instance per process. */
+  class Dsp {
+    #h: unknown;
+    constructor(sampleRate: number) {
+      this.#h = s.rb_dsp_new(sampleRate);
+      if (raw.isNull(this.#h)) throw new Error("rb_dsp_new returned NULL");
+    }
+    close(): void {
+      if (!raw.isNull(this.#h)) {
+        s.rb_dsp_free(this.#h);
+        this.#h = null;
+      }
+    }
+    [Symbol.dispose](): void {
+      this.close();
+    }
+
+    setInputFrequency(hz: number): void {
+      s.rb_dsp_set_input_frequency(this.#h, hz);
+    }
+    flush(): void {
+      s.rb_dsp_flush(this.#h);
+    }
+    eqEnable(enable: boolean): void {
+      s.rb_dsp_eq_enable(this.#h, enable);
+    }
+    setEqBand(band: number, cutoffHz: number, q: number, gainDb: number): void {
+      s.rb_dsp_set_eq_band(this.#h, band, cutoffHz, q, gainDb);
+    }
+    setEqPrecut(db: number): void {
+      s.rb_dsp_set_eq_precut(this.#h, db);
+    }
+    setTone(bassDb: number, trebleDb: number): void {
+      s.rb_dsp_set_tone(this.#h, bassDb, trebleDb);
+    }
+    setToneCutoffs(bassHz: number, trebleHz: number): void {
+      s.rb_dsp_set_tone_cutoffs(this.#h, bassHz, trebleHz);
+    }
+    setSurround(delayMs: number, balance: number, fx1: number, fx2: number): void {
+      s.rb_dsp_set_surround(this.#h, delayMs, balance, fx1, fx2);
+    }
+    setChannelConfig(mode: number): void {
+      s.rb_dsp_set_channel_config(this.#h, mode);
+    }
+    setStereoWidth(percent: number): void {
+      s.rb_dsp_set_stereo_width(this.#h, percent);
+    }
+    setCompressor(
+      threshold: number, makeupGain: number, ratio: number, knee: number,
+      releaseTime: number, attackTime: number,
+    ): void {
+      s.rb_dsp_set_compressor(this.#h, threshold, makeupGain, ratio, knee, releaseTime, attackTime);
+    }
+    /** mode: DspReplayGainMode (TRACK=0, ALBUM=1, SHUFFLE=2, OFF=3). */
+    setReplaygain(mode: number, noclip: boolean, preampDb: number): void {
+      s.rb_dsp_set_replaygain(this.#h, mode, noclip, preampDb);
+    }
+    /** Per-track gains in plain dB, peaks as linear amplitude. undefined => absent. */
+    setReplaygainGains(
+      trackGainDb?: number | null, albumGainDb?: number | null,
+      trackPeak?: number | null, albumPeak?: number | null,
+    ): void {
+      s.rb_dsp_set_replaygain_gains(
+        this.#h, opt(trackGainDb), opt(albumGainDb), opt(trackPeak), opt(albumPeak),
+      );
+    }
+    /** Native Q7.24 factors (the `raw_*` metadata fields); use BigInt. */
+    setReplaygainGainsRaw(
+      trackGain: bigint, albumGain: bigint, trackPeak: bigint, albumPeak: bigint,
+    ): void {
+      s.rb_dsp_set_replaygain_gains_raw(this.#h, trackGain, albumGain, trackPeak, albumPeak);
+    }
+    /** Run interleaved stereo S16 samples through the pipeline. */
+    process(samples: Int16Array): Int16Array {
+      if (samples.length % 2 !== 0) {
+        throw new Error("input must be interleaved stereo (even length)");
+      }
+      const out = raw.sizeOut();
+      const ptr = s.rb_dsp_process(this.#h, raw.i16in(samples), samples.length, out.arg);
+      const n = out.value();
+      if (raw.isNull(ptr) || n === 0) return new Int16Array(0);
+      return raw.takeI16(ptr, n);
+    }
+  }
+
+  /** Queue-based player. Owns a live output device + engine thread. */
+  class Player {
+    #h: unknown;
+    constructor(config?: PlayerConfig) {
+      if (config === undefined) {
+        this.#h = s.rb_player_new();
+      } else {
+        this.#h = s.rb_player_new_with_config(
+          config.sampleRate ?? 0,
+          config.bufferSeconds ?? 4.0,
+          config.volume ?? 1.0,
+          config.replaygainMode ?? ReplayGainMode.OFF,
+          config.replaygainPreampDb ?? 0.0,
+          config.replaygainPreventClipping ?? true,
+          config.crossfadeMode ?? CrossfadeMode.OFF,
+          config.fadeOutDelayMs ?? 0,
+          config.fadeOutDurationMs ?? 2000,
+          config.fadeInDelayMs ?? 0,
+          config.fadeInDurationMs ?? 2000,
+          config.mixMode ?? MixMode.CROSSFADE,
+        );
+      }
+      if (raw.isNull(this.#h)) {
+        throw new Error("failed to create Player (no output device?)");
+      }
+    }
+    close(): void {
+      if (!raw.isNull(this.#h)) {
+        s.rb_player_free(this.#h);
+        this.#h = null;
+      }
+    }
+    [Symbol.dispose](): void {
+      this.close();
+    }
+
+    setQueue(paths: string[]): void {
+      s.rb_player_set_queue_json(this.#h, raw.cstr(JSON.stringify(paths)));
+    }
+    enqueue(path: string): void {
+      s.rb_player_enqueue(this.#h, raw.cstr(path));
+    }
+    play(): void {
+      s.rb_player_play(this.#h);
+    }
+    pause(): void {
+      s.rb_player_pause(this.#h);
+    }
+    toggle(): void {
+      s.rb_player_toggle(this.#h);
+    }
+    stop(): void {
+      s.rb_player_stop(this.#h);
+    }
+    next(): void {
+      s.rb_player_next(this.#h);
+    }
+    previous(): void {
+      s.rb_player_previous(this.#h);
+    }
+    skipTo(index: number): void {
+      s.rb_player_skip_to(this.#h, index);
+    }
+    seekMs(ms: number | bigint): void {
+      s.rb_player_seek_ms(this.#h, BigInt(ms));
+    }
+    setVolume(vol: number): void {
+      s.rb_player_set_volume(this.#h, vol);
+    }
+    volume(): number {
+      return Number(s.rb_player_volume(this.#h));
+    }
+    sampleRate(): number {
+      return Number(s.rb_player_sample_rate(this.#h));
+    }
+    setCrossfade(
+      mode: number, foDelayMs = 0, foDurMs = 2000, fiDelayMs = 0, fiDurMs = 2000,
+      mixMode = MixMode.CROSSFADE,
+    ): void {
+      s.rb_player_set_crossfade(this.#h, mode, foDelayMs, foDurMs, fiDelayMs, fiDurMs, mixMode);
+    }
+    /** mode: ReplayGainMode (OFF=0, TRACK=1, ALBUM=2). */
+    setReplaygain(mode: number, preampDb: number, preventClipping: boolean): void {
+      s.rb_player_set_replaygain(this.#h, mode, preampDb, preventClipping);
+    }
+    status(): PlayerStatus {
+      const json = raw.takeString(s.rb_player_status_json(this.#h));
+      if (json === null) throw new Error("rb_player_status_json returned NULL");
+      return JSON.parse(json) as PlayerStatus;
+    }
+  }
+
+  return { abiVersion, metadata, Dsp, Player };
+}
+
+/** Generate `seconds` of a sine as interleaved stereo Int16. */
+export function sineStereo(
+  freqHz: number, seconds: number, rate: number, amplitude = 16000,
+): Int16Array {
+  const n = Math.floor(seconds * rate);
+  const buf = new Int16Array(n * 2);
+  for (let i = 0; i < n; i++) {
+    let v = Math.round(Math.sin((i * 2 * Math.PI * freqHz) / rate) * amplitude);
+    v = Math.max(-32768, Math.min(32767, v));
+    buf[i * 2] = v;
+    buf[i * 2 + 1] = v;
+  }
+  return buf;
+}

package/src/bun.ts

@@ -0,0 +1,95 @@
+// Bun backend + full API. Import from here under Bun:
+//   import { Dsp, Player, metadata } from "rockbox-ffi/bun";
+
+import {
+  CString,
+  dlopen,
+  FFIType,
+  type Pointer,
+  ptr,
+  toArrayBuffer,
+} from "bun:ffi";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { makeApi, sineStereo } from "./api.ts";
+import { resolveLibPath, SPEC, type Raw, type Tok } from "./ffi.ts";
+
+const TOK: Record<Tok, FFIType> = {
+  void: FFIType.void,
+  ptr: FFIType.ptr,
+  u32: FFIType.u32,
+  i32: FFIType.i32,
+  u64: FFIType.u64,
+  usize: FFIType.u64,
+  f32: FFIType.f32,
+  bool: FFIType.bool,
+  strbuf: FFIType.ptr,
+  i16in: FFIType.ptr,
+  outsize: FFIType.ptr,
+};
+
+function makeRaw(): Raw {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const libPath = resolveLibPath(
+    here,
+    (k) => Bun.env[k],
+    existsSync,
+    join,
+    dirname,
+  );
+
+  const symbols: Record<string, { args: FFIType[]; returns: FFIType }> = {};
+  for (const [name, spec] of Object.entries(SPEC)) {
+    symbols[name] = { args: spec.args.map((t) => TOK[t]), returns: TOK[spec.ret] };
+  }
+  const lib = dlopen(libPath, symbols);
+  const sym = lib.symbols as Record<string, (...a: any[]) => any>;
+
+  // Keep marshalled input buffers alive across the (synchronous) call by
+  // holding a reference on the caller's stack — Bun's `ptr()` does not copy.
+  const enc = new TextEncoder();
+
+  return {
+    sym,
+    cstr(s: string) {
+      const buf = enc.encode(s + "\0");
+      // Attach to a WeakRef-free holder: return the pointer but stash the
+      // buffer on the returned Number via closure is impossible, so we rely
+      // on synchronous FFI — the buffer is created fresh here and the call
+      // happens immediately after in the same tick.
+      return ptr(buf);
+    },
+    i16in(a: Int16Array) {
+      return ptr(a);
+    },
+    sizeOut() {
+      const arr = new BigUint64Array(1);
+      return { arg: ptr(arr), value: () => Number(arr[0]) };
+    },
+    takeString(p: unknown) {
+      if (p === null || p === 0) return null;
+      // Bun pointers are numbers at runtime; the typed API wants `Pointer`.
+      const str = new CString(p as Pointer).toString();
+      sym.rb_string_free(p);
+      return str;
+    },
+    takeI16(p: unknown, len: number) {
+      const ab = toArrayBuffer(p as Pointer, 0, len * 2);
+      const copy = new Int16Array(len);
+      copy.set(new Int16Array(ab));
+      sym.rb_buffer_free(p, len);
+      return copy;
+    },
+    isNull(p: unknown) {
+      return p === null || p === 0 || p === undefined;
+    },
+  };
+}
+
+const api = makeApi(makeRaw());
+export const { abiVersion, metadata, Dsp, Player } = api;
+export { sineStereo };
+export * from "./enums.ts";
+export type { Metadata, PlayerStatus, PlayerConfig } from "./types.ts";

package/src/deno.ts

@@ -0,0 +1,83 @@
+// Deno backend + full API. Import from here under Deno:
+//   import { Dsp, Player, metadata } from "./src/deno.ts";
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { makeApi, sineStereo } from "./api.ts";
+import { resolveLibPath, SPEC, type Raw, type Tok } from "./ffi.ts";
+
+// deno-lint-ignore no-explicit-any
+const D = (globalThis as any).Deno;
+
+const TOK: Record<Tok, string> = {
+  void: "void",
+  ptr: "pointer",
+  u32: "u32",
+  i32: "i32",
+  u64: "u64",
+  usize: "usize",
+  f32: "f32",
+  bool: "bool",
+  strbuf: "buffer",
+  i16in: "buffer",
+  outsize: "buffer",
+};
+
+function makeRaw(): Raw {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const libPath = resolveLibPath(
+    here,
+    (k) => D.env.get(k),
+    existsSync,
+    join,
+    dirname,
+  );
+
+  const defs: Record<string, { parameters: string[]; result: string }> = {};
+  for (const [name, spec] of Object.entries(SPEC)) {
+    defs[name] = { parameters: spec.args.map((t) => TOK[t]), result: TOK[spec.ret] };
+  }
+  const lib = D.dlopen(libPath, defs);
+  const sym = lib.symbols as Record<string, (...a: any[]) => any>;
+
+  const enc = new TextEncoder();
+
+  return {
+    sym,
+    cstr(s: string) {
+      return enc.encode(s + "\0");
+    },
+    i16in(a: Int16Array) {
+      return a;
+    },
+    sizeOut() {
+      const buf = new Uint8Array(8);
+      const view = new DataView(buf.buffer);
+      return { arg: buf, value: () => Number(view.getBigUint64(0, true)) };
+    },
+    takeString(p: unknown) {
+      if (p === null) return null;
+      const str = new D.UnsafePointerView(p).getCString();
+      sym.rb_string_free(p);
+      return str;
+    },
+    takeI16(p: unknown, len: number) {
+      const ab = new D.UnsafePointerView(p).getArrayBuffer(len * 2);
+      const copy = new Int16Array(len);
+      copy.set(new Int16Array(ab));
+      sym.rb_buffer_free(p, len);
+      return copy;
+    },
+    isNull(p: unknown) {
+      return p === null || p === undefined;
+    },
+  };
+}
+
+const api = makeApi(makeRaw());
+export const { abiVersion, metadata, Dsp, Player } = api;
+export { sineStereo };
+export * from "./enums.ts";
+export type { Metadata, PlayerConfig, PlayerStatus } from "./types.ts";

package/src/enums.ts

@@ -0,0 +1,44 @@
+// Enum constants for the Rockbox FFI.
+//
+// NOTE: the DSP and player use *different* ReplayGain mode integers (a quirk
+// of the underlying C ABI). Use DspReplayGainMode with `Dsp.setReplaygain`
+// and ReplayGainMode with `Player.setReplaygain`.
+
+/** For `Dsp.setReplaygain` (native Rockbox values). */
+export const DspReplayGainMode = {
+  TRACK: 0,
+  ALBUM: 1,
+  SHUFFLE: 2,
+  OFF: 3,
+} as const;
+
+/** For `Player.setReplaygain`. */
+export const ReplayGainMode = {
+  OFF: 0,
+  TRACK: 1,
+  ALBUM: 2,
+} as const;
+
+export const CrossfadeMode = {
+  OFF: 0,
+  AUTO_SKIP: 1,
+  MANUAL_SKIP: 2,
+  SHUFFLE: 3,
+  SHUFFLE_OR_MANUAL: 4,
+  ALWAYS: 5,
+} as const;
+
+export const MixMode = {
+  CROSSFADE: 0,
+  MIX: 1,
+} as const;
+
+export const ChannelConfig = {
+  STEREO: 0,
+  MONO: 1,
+  CUSTOM: 2,
+  MONO_LEFT: 3,
+  MONO_RIGHT: 4,
+  KARAOKE: 5,
+  SWAP: 6,
+} as const;