@cleanfield/node 0.0.0-stage → 0.1.0

package/index.d.ts

@@ -0,0 +1,38 @@
+export type BackendPreference = 'auto' | 'scalar' | 'avx2';
+
+/** The backend the engine actually selected at load time. */
+export type LiveBackend = 'scalar' | 'avx2';
+
+export interface VoiceOptions {
+  /**
+   * Path to a `.cfwm` voice container. Defaults to the model bundled with the
+   * package, then to `CLEANFIELD_VOICE_MODEL`.
+   */
+  modelPath?: string;
+  /**
+   * Backend preference. `auto` picks AVX2+FMA when the CPU supports it and
+   * falls back to the scalar reference otherwise. `scalar` / `avx2` never fall
+   * back: an unavailable backend throws.
+   */
+  backend?: BackendPreference;
+}
+
+export interface Voice {
+  /** Backend the engine loaded with. */
+  readonly backend: LiveBackend;
+  /**
+   * Run one 513-value feature frame and return a new 1026-value mask frame.
+   * The returned array is freshly allocated on every call.
+   */
+  process(frame: Float32Array): Float32Array;
+  /** Reset the cross-frame state (history, LSTM cells, quantised state). */
+  reset(): void;
+  /** Release the engine immediately. Safe to call more than once. */
+  close(): void;
+}
+
+/**
+ * Create one voice engine instance. Each instance owns an independent model
+ * and workspace; calls on the same instance must not overlap.
+ */
+export function createVoice(options?: VoiceOptions): Voice;

package/index.js

@@ -0,0 +1,177 @@
+'use strict';
+
+/**
+ * CleanField voice engine for Node.js.
+ *
+ * The native addon (`cf-node.node`) is resolved in this order:
+ *
+ *   1. `CLEANFIELD_NODE_BINDING` (explicit path, for tests and custom builds);
+ *   2. `prebuilds/<platform>-<arch>/cf-node.node` (downloaded from the release
+ *      by `scripts/fetch-prebuilt.mjs`, or copied by `scripts/build-local.ps1`);
+ *   3. an optional platform package (`@cleanfield/node-<platform>-<arch>`);
+ *   4. `build/Release/cf_node.node` (a local CMake-style layout, if present);
+ *   5. a local Cargo build in `target/<triple>/release` or `target/release`.
+ *
+ * There is no node-gyp step: the addon is a plain Rust cdylib renamed to
+ * `.node`, and it resolves the N-API entry points from the host executable at
+ * load time.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RUST_TRIPLES = {
+  'win32-x64': 'x86_64-pc-windows-msvc',
+  'win32-arm64': 'aarch64-pc-windows-msvc',
+  'darwin-x64': 'x86_64-apple-darwin',
+  'darwin-arm64': 'aarch64-apple-darwin',
+  'linux-x64': 'x86_64-unknown-linux-gnu',
+  'linux-arm64': 'aarch64-unknown-linux-gnu',
+};
+
+const LIBRARY_SUFFIX =
+  process.platform === 'win32' ? '.dll' : process.platform === 'darwin' ? '.dylib' : '.so';
+
+function platformTag() {
+  const tag = `${process.platform}-${process.arch}`;
+  if (!RUST_TRIPLES[tag]) {
+    throw new Error(
+      `CleanField does not publish a prebuilt Node addon for ${process.platform}/${process.arch}. ` +
+        'Supported platforms: win32/linux x64 and arm64, darwin x64 and arm64. ' +
+        'Build from source with `cargo build --release -p cf-node`.'
+    );
+  }
+  return tag;
+}
+
+function bindingCandidates() {
+  const tag = platformTag();
+  const triple = RUST_TRIPLES[tag];
+  const root = path.join(__dirname, '..', '..');
+  const candidates = [];
+  if (process.env.CLEANFIELD_NODE_BINDING) {
+    candidates.push(process.env.CLEANFIELD_NODE_BINDING);
+  }
+  candidates.push(path.join(__dirname, 'prebuilds', tag, 'cf-node.node'));
+  candidates.push(path.join(__dirname, 'build', 'Release', 'cf-node.node'));
+  candidates.push(path.join(root, 'target', triple, 'release', `cf_node${LIBRARY_SUFFIX}`));
+  candidates.push(path.join(root, 'target', 'release', `cf_node${LIBRARY_SUFFIX}`));
+  return candidates;
+}
+
+/**
+ * Load a native addon from `filename`.
+ *
+ * `require()` only treats a file as an addon when its extension is `.node`, so
+ * a Cargo cdylib found in a build directory (`cf_node.dll`, `libcf_node.so`,
+ * `libcf_node.dylib`) is loaded through `process.dlopen`, which is exactly what
+ * `require()` uses for `.node` files.
+ */
+function loadNative(filename) {
+  if (filename.endsWith('.node')) return require(filename);
+  const loaded = new Module(filename, module);
+  loaded.filename = filename;
+  loaded.paths = Module._nodeModulePaths(path.dirname(filename));
+  process.dlopen(loaded, filename);
+  return loaded.exports;
+}
+
+function loadBinding() {
+  const attempts = [];
+  for (const candidate of bindingCandidates()) {
+    if (!fs.existsSync(candidate)) {
+      attempts.push(`${candidate} (missing)`);
+      continue;
+    }
+    try {
+      return loadNative(candidate);
+    } catch (error) {
+      attempts.push(`${candidate} (${error && error.message ? error.message : error})`);
+    }
+  }
+
+  const tag = platformTag();
+  const platformPackages = [`@cleanfield/node-${tag}`];
+  if (process.platform === 'darwin') platformPackages.push('@cleanfield/node-darwin-universal');
+  for (const name of platformPackages) {
+    try {
+      return require(name);
+    } catch (error) {
+      attempts.push(`${name} (${error && error.code ? error.code : error})`);
+    }
+  }
+
+  throw new Error(
+    'CleanField could not find its native addon. Tried:\n  ' +
+      attempts.join('\n  ') +
+      '\nBuild it with `cargo build --release -p cf-node`, copy it to ' +
+      `prebuilds/${tag}/cf-node.node, or set CLEANFIELD_NODE_BINDING to its path.`
+  );
+}
+
+function resolveModelPath(explicitPath) {
+  if (explicitPath !== undefined && explicitPath !== null) {
+    if (typeof explicitPath !== 'string' || explicitPath.length === 0) {
+      throw new TypeError('createVoice: options.modelPath must be a non-empty string');
+    }
+    if (!fs.existsSync(explicitPath)) {
+      throw new Error(`createVoice: the model file does not exist: ${explicitPath}`);
+    }
+    return explicitPath;
+  }
+  if (process.env.CLEANFIELD_VOICE_MODEL) {
+    if (!fs.existsSync(process.env.CLEANFIELD_VOICE_MODEL)) {
+      throw new Error(
+        `createVoice: CLEANFIELD_VOICE_MODEL points at a missing file: ${process.env.CLEANFIELD_VOICE_MODEL}`
+      );
+    }
+    return process.env.CLEANFIELD_VOICE_MODEL;
+  }
+  // 1. Bundled with the published package (copied by `npm pack`/prepack).
+  // 2. A workspace checkout: packages/node/../../models.
+  const candidates = [
+    path.join(__dirname, 'models', 'voice-default.cfwm'),
+    path.join(__dirname, '..', '..', 'models', 'voice-default.cfwm'),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error(
+    'createVoice: no voice model was found. Pass { modelPath } or set CLEANFIELD_VOICE_MODEL. ' +
+      'The default container is `models/voice-default.cfwm` in the CleanField distribution.'
+  );
+}
+
+const binding = loadBinding();
+
+if (!binding || typeof binding.createVoice !== 'function') {
+  throw new Error(
+    'CleanField loaded its native addon but the addon does not export createVoice(). ' +
+      'The binary and the JavaScript package versions may not match.'
+  );
+}
+
+/**
+ * Create one voice engine instance.
+ *
+ * @param {object} [options]
+ * @param {string} [options.modelPath] `.cfwm` container to load. Defaults to the
+ *   model bundled with the package (or `CLEANFIELD_VOICE_MODEL`).
+ * @param {'auto'|'scalar'|'avx2'} [options.backend] Backend selection. `auto`
+ *   uses AVX2+FMA when the CPU supports it and the scalar reference otherwise.
+ *   An explicitly requested backend never falls back silently.
+ * @returns {{ backend: string, process: (frame: Float32Array) => Float32Array, reset: () => void, close: () => void }}
+ */
+function createVoice(options = {}) {
+  if (options === null || typeof options !== 'object') {
+    throw new TypeError('createVoice(options) expects an options object');
+  }
+  const backend = options.backend === undefined ? 'auto' : options.backend;
+  if (backend !== 'auto' && backend !== 'scalar' && backend !== 'avx2') {
+    throw new TypeError('createVoice: options.backend must be "auto", "scalar" or "avx2"');
+  }
+  const modelPath = resolveModelPath(options.modelPath);
+  return binding.createVoice({ modelPath, backend });
+}
+
+module.exports = { createVoice };

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@cleanfield/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CleanField real-time speech enhancement engine for Node.js: prebuilt native addon, no node-gyp.",
+  "license": "MIT",
+  "author": "CleanField",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "scripts/",
+    "prebuilds/",
+    "models/voice-default.cfwm"
+  ],
+  "scripts": {
+    "prepack": "node scripts/prepare-model.mjs",
+    "postinstall": "node scripts/fetch-prebuilt.mjs",
+    "test": "node test/smoke.js"
+  },
+  "optionalDependencies": {
+    "@cleanfield/node-win32-x64": "0.1.0",
+    "@cleanfield/node-win32-arm64": "0.1.0",
+    "@cleanfield/node-darwin-x64": "0.1.0",
+    "@cleanfield/node-darwin-arm64": "0.1.0",
+    "@cleanfield/node-darwin-universal": "0.1.0",
+    "@cleanfield/node-linux-x64": "0.1.0",
+    "@cleanfield/node-linux-arm64": "0.1.0"
+  },
+  "cleanfield": {
+    "releaseBaseUrl": "https://github.com/CleanfieldVoice/Cleanfield/releases/download",
+    "model": "models/voice-default.cfwm"
+  },
+  "keywords": [
+    "audio",
+    "speech-enhancement",
+    "denoise",
+    "wasm",
+    "native-addon"
+  ]
+}
+

package/scripts/fetch-prebuilt.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * Fetch the prebuilt native addon for this platform from the GitHub Release
+ * that matches the package version.
+ *
+ * Resolution order in `index.js` is: explicit path, `prebuilds/`, platform
+ * package, local build.  This script only fills `prebuilds/`; it never fails an
+ * install.  Air-gapped machines can set `CLEANFIELD_SKIP_DOWNLOAD=1` (or pass
+ * `--ignore-scripts`) and provide the addon themselves.
+ *
+ * Integrity: when the release publishes `SHA256SUMS`, the downloaded binary is
+ * verified against it before it is moved into place.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(here, '..');
+const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+
+const SUPPORTED = new Set([
+  'win32-x64',
+  'win32-arm64',
+  'darwin-x64',
+  'darwin-arm64',
+  'linux-x64',
+  'linux-arm64',
+]);
+
+function skip(reason) {
+  console.log(`[cleanfield] prebuilt addon not downloaded: ${reason}`);
+  process.exit(0);
+}
+
+function warn(message) {
+  console.warn(`[cleanfield] ${message}`);
+  console.warn(
+    '[cleanfield] The JavaScript package is installed, but the native addon is missing. ' +
+      'Build it with `cargo build --release -p cf-node`, copy it to ' +
+      `prebuilds/${process.platform}-${process.arch}/cf-node.node, or set CLEANFIELD_NODE_BINDING.`
+  );
+  process.exit(0);
+}
+
+if (process.env.CLEANFIELD_SKIP_DOWNLOAD === '1') skip('CLEANFIELD_SKIP_DOWNLOAD=1');
+
+const tag = `${process.platform}-${process.arch}`;
+if (!SUPPORTED.has(tag)) skip(`unsupported platform ${tag}`);
+
+const asset =
+  process.platform === 'darwin' ? 'cf-node-darwin-universal.node' : `cf-node-${tag}.node`;
+const targetDir = path.join(packageRoot, 'prebuilds', tag);
+const target = path.join(targetDir, 'cf-node.node');
+
+if (fs.existsSync(target)) skip(`already present at ${path.relative(packageRoot, target)}`);
+
+// A workspace build is enough; do not touch the network for local development.
+const localCandidates = [
+  path.join(packageRoot, 'build', 'Release', 'cf_node.node'),
+  path.join(packageRoot, '..', '..', 'target', 'release', 'cf_node.dll'),
+  path.join(packageRoot, '..', '..', 'target', 'release', 'libcf_node.so'),
+  path.join(packageRoot, '..', '..', 'target', 'release', 'libcf_node.dylib'),
+];
+if (localCandidates.some((candidate) => fs.existsSync(candidate))) {
+  skip('a local Cargo build is present');
+}
+
+const baseUrl =
+  process.env.CLEANFIELD_RELEASE_BASE_URL ||
+  (manifest.cleanfield && manifest.cleanfield.releaseBaseUrl);
+if (!baseUrl) skip('no release base URL is configured');
+
+const releaseUrl = `${baseUrl.replace(/\/+$/, '')}/v${manifest.version}`;
+const assetUrl = `${releaseUrl}/${asset}`;
+
+async function download(url) {
+  const response = await fetch(url, { redirect: 'follow' });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} for ${url}`);
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+
+async function main() {
+  let bytes;
+  try {
+    bytes = await download(assetUrl);
+  } catch (error) {
+    warn(`could not download ${assetUrl}: ${error.message}`);
+    return;
+  }
+
+  try {
+    const sums = (await download(`${releaseUrl}/SHA256SUMS`)).toString('utf8');
+    const expected = sums
+      .split(/\r?\n/)
+      .map((line) => line.trim().split(/\s+/))
+      .find((parts) => parts.length >= 2 && parts[parts.length - 1] === asset);
+    if (expected) {
+      const actual = crypto.createHash('sha256').update(bytes).digest('hex');
+      if (actual !== expected[0].toLowerCase()) {
+        warn(`checksum mismatch for ${asset}: expected ${expected[0]}, got ${actual}`);
+        return;
+      }
+      console.log(`[cleanfield] SHA256 verified: ${actual}`);
+    } else {
+      console.warn(`[cleanfield] ${asset} is not listed in SHA256SUMS; installing unverified`);
+    }
+  } catch (error) {
+    console.warn(`[cleanfield] could not verify SHA256SUMS: ${error.message}`);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  const temporary = `${target}.download`;
+  fs.writeFileSync(temporary, bytes);
+  fs.renameSync(temporary, target);
+  console.log(
+    `[cleanfield] installed ${asset} (${(bytes.length / 1024).toFixed(1)} KiB) into prebuilds/${tag}/`
+  );
+}
+
+await main();

package/scripts/prepare-model.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * Copy the default voice container into the package before packing.
+ *
+ * The `.cfwm` container is 2.5 MB and is generated by the engine build, so it
+ * is not committed twice: the package directory only receives a copy at
+ * `npm pack` / `npm publish` time (this is the `prepack` hook) and, for local
+ * development, the loader can fall back to the workspace copy
+ * (`packages/node/../../models/voice-default.cfwm`).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(here, '..');
+const source = path.join(packageRoot, '..', '..', 'models', 'voice-default.cfwm');
+const target = path.join(packageRoot, 'models', 'voice-default.cfwm');
+
+if (fs.existsSync(target) && fs.statSync(target).size > 0) {
+  console.log(`[cleanfield] model already present: ${path.relative(process.cwd(), target)}`);
+  process.exit(0);
+}
+
+if (!fs.existsSync(source)) {
+  console.error(
+    `[cleanfield] cannot package without the voice container: ${source} is missing.\n` +
+      'Build it with `python tools/build_cfwm.py --blob <weights.bin>` from the workspace root.'
+  );
+  process.exit(1);
+}
+
+fs.mkdirSync(path.dirname(target), { recursive: true });
+fs.copyFileSync(source, target);
+console.log(
+  `[cleanfield] copied ${(fs.statSync(target).size / (1024 * 1024)).toFixed(2)} MiB model into the package`
+);

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.