rockbox-ffi 0.1.0

package/src/ffi.ts

@@ -0,0 +1,144 @@
+// Runtime-agnostic FFI description: one symbol table with abstract type
+// tokens that each backend (bun.ts / deno.ts) maps to its own FFI types.
+
+/** Abstract argument/return type tokens used by the symbol spec. */
+export type Tok =
+  | "void"
+  | "ptr" // opaque handle / returned pointer
+  | "u32"
+  | "i32"
+  | "u64"
+  | "usize"
+  | "f32"
+  | "bool"
+  | "strbuf" // input: a JS string marshalled as `const char *`
+  | "i16in" // input: an Int16Array marshalled as `const int16_t *`
+  | "outsize"; // input: a `size_t *` out-parameter
+
+export interface SymSpec {
+  args: Tok[];
+  ret: Tok;
+}
+
+// Mirrors include/rockbox_ffi.h. Keep in sync with the C ABI.
+export const SPEC: Record<string, SymSpec> = {
+  rb_ffi_abi_version: { args: [], ret: "u32" },
+  rb_string_free: { args: ["ptr"], ret: "void" },
+  rb_buffer_free: { args: ["ptr", "usize"], ret: "void" },
+
+  rb_dsp_new: { args: ["u32"], ret: "ptr" },
+  rb_dsp_free: { args: ["ptr"], ret: "void" },
+  rb_dsp_set_input_frequency: { args: ["ptr", "u32"], ret: "void" },
+  rb_dsp_flush: { args: ["ptr"], ret: "void" },
+  rb_dsp_eq_enable: { args: ["ptr", "bool"], ret: "void" },
+  rb_dsp_set_tone: { args: ["ptr", "i32", "i32"], ret: "void" },
+  rb_dsp_set_tone_cutoffs: { args: ["ptr", "i32", "i32"], ret: "void" },
+  rb_dsp_set_surround: { args: ["ptr", "i32", "i32", "i32", "i32"], ret: "void" },
+  rb_dsp_set_channel_config: { args: ["ptr", "i32"], ret: "void" },
+  rb_dsp_set_stereo_width: { args: ["ptr", "i32"], ret: "void" },
+  rb_dsp_set_compressor: {
+    args: ["ptr", "i32", "i32", "i32", "i32", "i32", "i32"],
+    ret: "void",
+  },
+  rb_dsp_set_replaygain: { args: ["ptr", "i32", "bool", "f32"], ret: "void" },
+  rb_dsp_set_replaygain_gains: {
+    args: ["ptr", "f32", "f32", "f32", "f32"],
+    ret: "void",
+  },
+  rb_dsp_set_replaygain_gains_raw: {
+    args: ["ptr", "u64", "u64", "u64", "u64"],
+    ret: "void",
+  },
+  rb_dsp_set_eq_band: { args: ["ptr", "usize", "i32", "f32", "f32"], ret: "void" },
+  rb_dsp_set_eq_precut: { args: ["ptr", "f32"], ret: "void" },
+  rb_dsp_process: { args: ["ptr", "i16in", "usize", "outsize"], ret: "ptr" },
+
+  rb_meta_read_json: { args: ["strbuf"], ret: "ptr" },
+  rb_meta_probe: { args: ["strbuf"], ret: "ptr" },
+
+  rb_player_new: { args: [], ret: "ptr" },
+  rb_player_new_with_config: {
+    args: [
+      "u32", "f32", "f32", "i32", "f32", "bool", "i32", "u32", "u32", "u32",
+      "u32", "i32",
+    ],
+    ret: "ptr",
+  },
+  rb_player_free: { args: ["ptr"], ret: "void" },
+  rb_player_set_queue_json: { args: ["ptr", "strbuf"], ret: "void" },
+  rb_player_enqueue: { args: ["ptr", "strbuf"], ret: "void" },
+  rb_player_play: { args: ["ptr"], ret: "void" },
+  rb_player_pause: { args: ["ptr"], ret: "void" },
+  rb_player_toggle: { args: ["ptr"], ret: "void" },
+  rb_player_stop: { args: ["ptr"], ret: "void" },
+  rb_player_next: { args: ["ptr"], ret: "void" },
+  rb_player_previous: { args: ["ptr"], ret: "void" },
+  rb_player_skip_to: { args: ["ptr", "usize"], ret: "void" },
+  rb_player_seek_ms: { args: ["ptr", "u64"], ret: "void" },
+  rb_player_set_volume: { args: ["ptr", "f32"], ret: "void" },
+  rb_player_set_crossfade: {
+    args: ["ptr", "i32", "u32", "u32", "u32", "u32", "i32"],
+    ret: "void",
+  },
+  rb_player_set_replaygain: { args: ["ptr", "i32", "f32", "bool"], ret: "void" },
+  rb_player_volume: { args: ["ptr"], ret: "f32" },
+  rb_player_sample_rate: { args: ["ptr"], ret: "u32" },
+  rb_player_status_json: { args: ["ptr"], ret: "ptr" },
+};
+
+/**
+ * The low-level backend a runtime loader must provide. High-level classes in
+ * api.ts are written once against this interface.
+ */
+export interface Raw {
+  /** The dlopen'd symbol table; call e.g. `sym.rb_dsp_new(44100)`. */
+  sym: Record<string, (...a: any[]) => any>;
+  /** Marshal a JS string as a `const char *` argument. */
+  cstr(s: string): unknown;
+  /** Marshal an Int16Array as a `const int16_t *` argument. */
+  i16in(a: Int16Array): unknown;
+  /** Allocate a `size_t` out-parameter; `value()` reads it after the call. */
+  sizeOut(): { arg: unknown; value(): number };
+  /** Read a returned `char *` into a string and free it (null => null). */
+  takeString(p: unknown): string | null;
+  /** Read a returned `int16_t *` of `len` samples into a copy and free it. */
+  takeI16(p: unknown, len: number): Int16Array;
+  /** True if a returned handle/pointer is NULL. */
+  isNull(p: unknown): boolean;
+}
+
+const LIB_NAMES = ["librockbox_ffi.dylib", "librockbox_ffi.so", "rockbox_ffi.dll"];
+
+/**
+ * Locate the shared library: `ROCKBOX_FFI_LIB` env var first, then by walking
+ * up from `startDir` to a `target/release` directory. `exists` and the path
+ * ops are injected so this works under both Bun and Deno.
+ */
+export function resolveLibPath(
+  startDir: string,
+  env: (k: string) => string | undefined,
+  exists: (p: string) => boolean,
+  join: (...p: string[]) => string,
+  dirname: (p: string) => string,
+): string {
+  const override = env("ROCKBOX_FFI_LIB");
+  if (override) return override;
+
+  let dir = startDir;
+  const tried: string[] = [];
+  for (let i = 0; i < 40; i++) {
+    const rel = join(dir, "target", "release");
+    for (const name of LIB_NAMES) {
+      const p = join(rel, name);
+      tried.push(p);
+      if (exists(p)) return p;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "could not locate librockbox_ffi. Set ROCKBOX_FFI_LIB or run " +
+      "`cargo build --release -p rockbox-ffi`. Tried:\n  " + tried.join("\n  "),
+  );
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// Runtime auto-detecting entry point.
+//
+// Prefer importing the runtime-specific module directly (`rockbox-ffi/bun` or
+// `./src/deno.ts`) — those load synchronously. This helper exists for code
+// that wants a single import and can await initialization.
+
+import type { makeApi } from "./api.ts";
+
+export * from "./enums.ts";
+export { sineStereo } from "./api.ts";
+export type { Metadata, PlayerConfig, PlayerStatus } from "./types.ts";
+
+type Api = ReturnType<typeof makeApi>;
+
+let cached: Api | undefined;
+
+/**
+ * Load the binding for the current runtime (Bun or Deno). Uses a dynamic
+ * import so the other runtime's FFI module is never parsed.
+ */
+export async function load(): Promise<Api> {
+  if (cached) return cached;
+  // deno-lint-ignore no-explicit-any
+  const g = globalThis as any;
+  let mod: { abiVersion: Api["abiVersion"]; metadata: Api["metadata"]; Dsp: Api["Dsp"]; Player: Api["Player"] };
+  if (typeof g.Bun !== "undefined") {
+    mod = await import("./bun.ts");
+  } else if (typeof g.Deno !== "undefined") {
+    mod = await import("./deno.ts");
+  } else if (typeof g.process !== "undefined" && g.process.versions?.node) {
+    mod = await import("./node.ts");
+  } else {
+    throw new Error("unsupported runtime: need Bun, Deno, or Node.js");
+  }
+  cached = { abiVersion: mod.abiVersion, metadata: mod.metadata, Dsp: mod.Dsp, Player: mod.Player };
+  return cached;
+}

package/src/node.ts

@@ -0,0 +1,87 @@
+// Node.js backend + full API, using koffi for FFI. Import under Node:
+//   import { Dsp, Player, metadata } from "rockbox-ffi/node";
+//
+// Node has no built-in FFI, so this backend depends on `koffi`
+// (https://koffi.dev) — install it with `npm install koffi`.
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+import { makeApi, sineStereo } from "./api.ts";
+import { resolveLibPath, SPEC, type Raw, type Tok } from "./ffi.ts";
+
+// koffi ships as CommonJS; load it via require to keep ESM interop simple.
+const require = createRequire(import.meta.url);
+// deno-lint-ignore no-explicit-any
+const koffi: any = require("koffi");
+
+const TOK: Record<Tok, string> = {
+  void: "void",
+  ptr: "void *",
+  u32: "uint32",
+  i32: "int32",
+  u64: "uint64",
+  usize: "size_t",
+  f32: "float",
+  bool: "bool",
+  strbuf: "str", // koffi marshals a JS string to a NUL-terminated char*
+  i16in: "void *", // we pass a Buffer view of the Int16Array
+  outsize: "void *", // we pass a Buffer.alloc(8) and read it back
+};
+
+function makeRaw(): Raw {
+  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: Record<string, (...a: any[]) => any> = {};
+  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: string) {
+      // The `strbuf` params are typed "str"; koffi marshals the JS string.
+      return s;
+    },
+    i16in(a: Int16Array) {
+      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: unknown) {
+      if (p === null || p === undefined) return null;
+      // Read a NUL-terminated char* of unknown length. (koffi's "str" type
+      // is unreliable for longer strings in 2.16 — this form is robust.)
+      const str = koffi.decode(p, "char", -1) as string;
+      sym.rb_string_free(p);
+      return str;
+    },
+    takeI16(p: unknown, len: number) {
+      const arr = koffi.decode(p, koffi.array("int16_t", len)) as number[];
+      const copy = Int16Array.from(arr);
+      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/types.ts

@@ -0,0 +1,80 @@
+// Types mirroring the JSON shapes emitted by crates/rockbox-ffi (snake_case).
+
+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; // 0 / undefined => device default
+  bufferSeconds?: number;
+  volume?: number;
+  replaygainMode?: number; // ReplayGainMode
+  replaygainPreampDb?: number;
+  replaygainPreventClipping?: boolean;
+  crossfadeMode?: number; // CrossfadeMode
+  fadeOutDelayMs?: number;
+  fadeOutDurationMs?: number;
+  fadeInDelayMs?: number;
+  fadeInDurationMs?: number;
+  mixMode?: number; // MixMode
+}