@pith-hash/pith-flac 0.0.0-stage → 0.1.0

package/index.js

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 pith-hash
+"use strict";
+
+/**
+ * pith-flac SDK: FLAC decoding through koffi.
+ *
+ * Decodes a native FLAC stream (STREAMINFO, constant/verbatim
+ * subframes, fixed predictors of orders 0-4, both Rice methods) into
+ * the canonical byte stream the `reference.json` vectors are defined
+ * over: a 64-byte big-endian header followed by the decoded PCM,
+ * interleaved `i32` little-endian.
+ *
+ * The cdylib is located through the suite's discovery chain:
+ *
+ *  1. `PITH_CDYLIB` — an explicit cdylib *file* path;
+ *  2. `PITH_CDYLIB_DIR` — a *directory* scanned for the cdylib names
+ *     (the CD pipeline points this at `target/release`);
+ *  3. `prebuilds/` — the packaged npm layout the CD publish job
+ *     assembles, flat and per `<os-arch>` (e.g. `linux-x64`);
+ *  4. `<repo root>/target/release` — the repository working-tree
+ *     layout, so a source checkout runs against a local cargo build
+ *     with no configuration.
+ *
+ * The FFI surface is one decode operation plus one free:
+ * `pith_flac_decode` decodes a whole FLAC stream into the canonical
+ * byte stream, and `pith_flac_free` releases the handed-out buffer.
+ */
+
+const koffi = require("koffi");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const STATUS_OK = 0;
+const STATUS_INVALID = -1;
+const STATUS_REJECTED = -2;
+
+/** Refusal kind "bad-value" (Error::BadValue). */
+const ERR_BAD_VALUE = 1;
+/** Refusal kind "invalid-magic" (Error::InvalidMagic). */
+const ERR_INVALID_MAGIC = 2;
+/** Refusal kind "too-large" (Error::TooLarge). */
+const ERR_TOO_LARGE = 3;
+/** Refusal kind "truncated" (Error::Truncated). */
+const ERR_TRUNCATED = 4;
+/** Refusal kind "unsupported" (Error::Unsupported). */
+const ERR_UNSUPPORTED = 5;
+
+/** The canonical stream's header length in bytes. */
+const HEADER_LEN = 64;
+
+/** Refusal-kind names by code — the stable names reference.json
+ * `error_vectors` record as strings. */
+const ERR_KIND_NAMES = Object.freeze({
+  [ERR_BAD_VALUE]: "bad-value",
+  [ERR_INVALID_MAGIC]: "invalid-magic",
+  [ERR_TOO_LARGE]: "too-large",
+  [ERR_TRUNCATED]: "truncated",
+  [ERR_UNSUPPORTED]: "unsupported",
+});
+
+/** Every cdylib file name cargo may drop into the build directory, per platform. */
+const CDYLIB_NAMES = ["pith_flac.dll", "libpith_flac.so", "libpith_flac.dylib"];
+
+const PKG_ROOT = path.join(__dirname);
+const REPO_ROOT = path.resolve(__dirname, "..", "..");
+
+/** FfiError: a non-zero status code came back from the cdylib. */
+class FfiError extends Error {
+  /**
+   * @param {string} op the FFI operation name
+   * @param {number} status the raw status code
+   * @param {number} kind the refusal kind code (0 unless rejected)
+   */
+  constructor(op, status, kind = 0) {
+    let kinded = { [STATUS_INVALID]: "invalid argument", [STATUS_REJECTED]: "input rejected" }[status] ?? "unknown failure";
+    if (kind) kinded += ` (${ERR_KIND_NAMES[kind] ?? `kind ${kind}`})`;
+    super(`${op} failed: ${kinded} (status ${status})`);
+    this.name = "FfiError";
+    /** The raw status code the FFI returned. */
+    this.status = status;
+    /** The refusal kind code (0 unless status is STATUS_REJECTED). */
+    this.kind = kind;
+  }
+}
+
+/**
+ * Locates the cdylib through the suite's discovery chain.
+ * @returns {string} an absolute path to the cdylib file
+ * @throws {Error} when nothing is found
+ */
+function findCdylib() {
+  const explicit = process.env.PITH_CDYLIB;
+  if (explicit && fs.statSync(explicit, { throwIfNoEntry: false })?.isFile()) {
+    return path.resolve(explicit);
+  }
+  /** @type {string[]} */
+  const dirs = [];
+  const envDir = process.env.PITH_CDYLIB_DIR;
+  if (envDir) {
+    dirs.push(envDir);
+    if (!path.isAbsolute(envDir)) {
+      dirs.push(path.join(REPO_ROOT, envDir));
+    }
+  }
+  const osArch = `${process.platform}-${process.arch}`;
+  dirs.push(path.join(PKG_ROOT, "prebuilds", osArch));
+  dirs.push(path.join(PKG_ROOT, "prebuilds"));
+  dirs.push(path.join(REPO_ROOT, "target", "release"));
+  for (const dir of dirs) {
+    for (const name of CDYLIB_NAMES) {
+      const p = path.join(dir, name);
+      if (fs.statSync(p, { throwIfNoEntry: false })?.isFile()) return p;
+    }
+  }
+  throw new Error(
+    "no pith-flac cdylib found (searched PITH_CDYLIB, PITH_CDYLIB_DIR, prebuilds/ and <repo>/target/release); " +
+      "run `cargo build --release` first",
+  );
+}
+
+let cached = undefined;
+
+/**
+ * Loads the cdylib and binds the exported symbols (lazily, once).
+ * @returns {{decode: Function, free: Function}}
+ */
+function loadLibrary() {
+  if (cached) return cached;
+  const lib = koffi.load(findCdylib());
+  const decode = lib.func("pith_flac_decode", "int32_t", [
+    "const uint8_t *",
+    "size_t",
+    koffi.out(koffi.pointer("void *")),
+    koffi.out(koffi.pointer("size_t")),
+    koffi.out(koffi.pointer("int32_t")),
+  ]);
+  const free = lib.func("void pith_flac_free(void *ptr, size_t len)");
+  cached = { decode, free };
+  return cached;
+}
+
+/**
+ * Decodes a complete FLAC stream into the canonical byte stream the
+ * `reference.json` vectors are defined over. The handed-out cdylib
+ * buffer is copied into a JS Buffer and released before returning.
+ *
+ * @param {Buffer} data the complete FLAC file bytes
+ * @returns {Buffer} the canonical stream (64-byte header + PCM)
+ * @throws {FfiError} with `status === -2` for any malformed input
+ */
+function decodeCanonical(data) {
+  if (!Buffer.isBuffer(data)) {
+    throw new TypeError("data must be a Buffer");
+  }
+  const { decode, free } = loadLibrary();
+  const out = [null];
+  const outLen = [0];
+  const err = [0];
+  const status = decode(data, data.length, out, outLen, err);
+  if (status !== STATUS_OK) {
+    throw new FfiError("pith_flac_decode", status, err[0]);
+  }
+  try {
+    // koffi.decode hands back a Uint8Array view over the external
+    // buffer; copy it into a Buffer before the cdylib buffer is freed.
+    return Buffer.from(koffi.decode(out[0], "uint8_t", Number(outLen[0])));
+  } finally {
+    free(out[0], Number(outLen[0]));
+  }
+}
+
+/**
+ * Re-expresses the canonical byte stream as a plain object.
+ *
+ * @param {Buffer} raw the canonical stream
+ * @returns {{siMinBlockSize: number, siMaxBlockSize: number, siSampleRate: number,
+ *   siChannels: number, siBitsPerSample: number, siTotalSamples: number,
+ *   sampleRate: number, channels: number, bitsPerSample: number,
+ *   totalSamples: number, decodedSamples: number, pcm: Buffer, raw: Buffer}}
+ */
+function parseCanonical(raw) {
+  if (!Buffer.isBuffer(raw) || raw.length < HEADER_LEN) {
+    throw new TypeError("canonical stream is shorter than the 64-byte header");
+  }
+  return {
+    siMinBlockSize: raw.readUInt32BE(0),
+    siMaxBlockSize: raw.readUInt32BE(4),
+    siSampleRate: raw.readUInt32BE(8),
+    siChannels: raw.readUInt32BE(12),
+    siBitsPerSample: raw.readUInt32BE(16),
+    siTotalSamples: Number(raw.readBigUInt64BE(20)),
+    sampleRate: raw.readUInt32BE(28),
+    channels: raw.readUInt32BE(32),
+    bitsPerSample: raw.readUInt32BE(36),
+    totalSamples: Number(raw.readBigUInt64BE(40)),
+    decodedSamples: Number(raw.readBigUInt64BE(48)),
+    pcm: raw.subarray(HEADER_LEN),
+    raw,
+  };
+}
+
+module.exports = {
+  STATUS_OK,
+  STATUS_INVALID,
+  STATUS_REJECTED,
+  ERR_BAD_VALUE,
+  ERR_INVALID_MAGIC,
+  ERR_TOO_LARGE,
+  ERR_TRUNCATED,
+  ERR_UNSUPPORTED,
+  HEADER_LEN,
+  ERR_KIND_NAMES,
+  CDYLIB_NAMES,
+  FfiError,
+  findCdylib,
+  decodeCanonical,
+  parseCanonical,
+};

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@pith-hash/pith-flac",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "FLAC decoding SDK: STREAMINFO, constant/verbatim/fixed subframes and both Rice methods via the pith-flac Rust cdylib (koffi, prebuilt)",
+  "license": "MIT",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "prebuilds/",
+    "reference.json"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "koffi": "^2.12.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pith-hash/pith-flac.git",
+    "directory": "sdk/node"
+  },
+  "keywords": [
+    "flac",
+    "audio",
+    "decoder",
+    "pcm",
+    "hashing"
+  ]
+}

package/reference.json

@@ -0,0 +1,106 @@
+{
+  "suite": "pith",
+  "crate": "pith-flac",
+  "format_version": 1,
+  "generator": "cargo run --bin gen-reference -- gen",
+  "vectors": [
+    {
+      "name": "fixture-tone",
+      "input_kind": "fixture-file",
+      "input_path": "tests/fixtures/tone.flac",
+      "input_sha256": "f954b800b5476f06529b365ed429da96fbf9961067073e955c1966d5fa098d9e",
+      "streaminfo_min_block_size": 16,
+      "streaminfo_max_block_size": 65535,
+      "streaminfo_sample_rate": 44100,
+      "streaminfo_channels": 1,
+      "streaminfo_bits_per_sample": 16,
+      "streaminfo_total_samples": 44100,
+      "sample_rate": 44100,
+      "channels": 1,
+      "bits_per_sample": 16,
+      "total_samples": 44100,
+      "decoded_samples": 44100,
+      "pcm_i32_le_sha256": "2514eff527051953533d999b57bc3745386432e2a37dcc32ccab77fb67faee6f",
+      "pcm_i32_le_fnv1a64": "3a1160e77c61f2b9"
+    },
+    {
+      "name": "constant-mono-16bit",
+      "input_kind": "inline-hex",
+      "input_hex": "664c61438000002200c012000000000000000ac440f00000000800000000000000000000000000000000fff860000007ff001234fd6f",
+      "sample_rate": 44100,
+      "channels": 1,
+      "bits_per_sample": 16,
+      "total_samples": 8,
+      "decoded_samples": 8,
+      "samples_i32": [4660, 4660, 4660, 4660, 4660, 4660, 4660, 4660],
+      "pcm_i32_le_sha256": "8949c8b20154a8ad94f90be09da09819eb3f6e4327b25df4ff0b28b0d8e9295c",
+      "pcm_i32_le_fnv1a64": "9e2315414d536a25"
+    },
+    {
+      "name": "verbatim-mono-signs",
+      "input_kind": "inline-hex",
+      "input_hex": "664c61438000002200c012000000000000000ac440f00000000800000000000000000000000000000000fff860000007ff020001fffe0003fffc0005fffa0007fff8af0b",
+      "sample_rate": 44100,
+      "channels": 1,
+      "bits_per_sample": 16,
+      "total_samples": 8,
+      "decoded_samples": 8,
+      "samples_i32": [1, -2, 3, -4, 5, -6, 7, -8],
+      "pcm_i32_le_sha256": "b646e9e2e7d9d9cdb8963241f30ef5b14db614b51f24cc9bbfbb8d6773ae4e60",
+      "pcm_i32_le_fnv1a64": "209cbf97ac330015"
+    },
+    {
+      "name": "fixed1-rice4-partitioned",
+      "input_kind": "inline-hex",
+      "input_hex": "664c61438000002200c012000000000000000ac440f00000000800000000000000000000000000000000fff860000007ff1201f40500000000000000000000000000000003e00000000000000000000000010300000000000100000000008000000000400000000020cd7a",
+      "sample_rate": 44100,
+      "channels": 1,
+      "bits_per_sample": 16,
+      "total_samples": 8,
+      "decoded_samples": 8,
+      "samples_i32": [500, -500, 300, 320, 340, 360, 380, 400],
+      "pcm_i32_le_sha256": "4224637b975f1bc8ecc4673122c35fa5c6b01976ac175627c1e1b37a0e68ea39",
+      "pcm_i32_le_fnv1a64": "57959265f7dfb14a"
+    },
+    {
+      "name": "fixed0-rice-escape",
+      "input_kind": "inline-hex",
+      "input_hex": "664c61438000002200c012000000000000000ac440f00000000800000000000000000000000000000000fff860000003e31007cb17848023fd",
+      "sample_rate": 44100,
+      "channels": 1,
+      "bits_per_sample": 16,
+      "total_samples": 8,
+      "decoded_samples": 4,
+      "samples_i32": [-15, 15, 0, 1],
+      "pcm_i32_le_sha256": "edc39f894f69e2678320dfe2884634e7d59ebee9324ad4d5a3ad4889f14c80a2",
+      "pcm_i32_le_fnv1a64": "8f8d061ed1f929c9"
+    },
+    {
+      "name": "stereo-left-side",
+      "input_kind": "inline-hex",
+      "input_hex": "664c61438000002200c012000000000000000ac442f00000000400000000000000000000000000000000fff860800003e8020064ff9c0064ff9c02001e7fdd00119ffc4038c7",
+      "sample_rate": 44100,
+      "channels": 2,
+      "bits_per_sample": 16,
+      "total_samples": 4,
+      "decoded_samples": 8,
+      "samples_i32": [100, 40, -100, 40, 100, -40, -100, -40],
+      "pcm_i32_le_sha256": "ad4f6b88c82175e563cf7b84e4b7ba62e0d3ab97bd8447011c2ea4817c085d9f",
+      "pcm_i32_le_fnv1a64": "ff5258122066d21d"
+    }
+  ],
+  "error_vectors": [
+    {
+      "name": "not-a-flac-stream",
+      "input_kind": "inline-hex",
+      "input_hex": "6e6f7065",
+      "error": "invalid-magic"
+    },
+    {
+      "name": "headerless-stream",
+      "input_kind": "inline-hex",
+      "input_hex": "664c6143",
+      "error": "truncated"
+    }
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.