transcribe-cpp 0.0.0 → 0.0.3

package/dist/loader.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve the native transcribe.cpp library. Resolution order (mirrors the
+ * Python provider choke point in `_library.py`):
+ *
+ *   1. TRANSCRIBE_LIBRARY  — explicit path (developer escape hatch).
+ *   2. A per-platform npm package `@transcribe-cpp/<tuple>` (the prebuilt
+ *      bundle wrapping the shared `transcribe-native-<tuple>` bytes).
+ *   3. A dev build tree (build-shared/src, build/src, …) found by walking up.
+ *
+ * Before dlopen of a platform package, its `contract.json` is validated
+ * (version base-match + header_hash equals our PUBLIC_HEADER_HASH).
+ */
+export interface Resolved {
+    libraryPath: string;
+    /** Directory holding the library and any ggml backend modules. */
+    artifactDir: string;
+    /** Provider package name, or null for env/dev resolution. */
+    provider: string | null;
+}
+export declare function resolveLibrary(): Resolved;

package/dist/loader.js

@@ -0,0 +1,140 @@
+/**
+ * Resolve the native transcribe.cpp library. Resolution order (mirrors the
+ * Python provider choke point in `_library.py`):
+ *
+ *   1. TRANSCRIBE_LIBRARY  — explicit path (developer escape hatch).
+ *   2. A per-platform npm package `@transcribe-cpp/<tuple>` (the prebuilt
+ *      bundle wrapping the shared `transcribe-native-<tuple>` bytes).
+ *   3. A dev build tree (build-shared/src, build/src, …) found by walking up.
+ *
+ * Before dlopen of a platform package, its `contract.json` is validated
+ * (version base-match + header_hash equals our PUBLIC_HEADER_HASH).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import * as g from "./_generated.js";
+import { OUR_VERSION, baseVersion } from "./version.js";
+import { AbiError, BackendError, TranscribeError, VersionMismatch } from "./errors.js";
+const LIB_NAME = process.platform === "darwin"
+    ? "libtranscribe.dylib"
+    : process.platform === "win32"
+        ? "transcribe.dll"
+        : "libtranscribe.so";
+/**
+ * The platform-package tuple for this host, or null if unsupported. Uses the
+ * Node platform-arch convention (matches npm os/cpu fields), e.g.
+ * `darwin-arm64-metal`. The release workflow maps each shared
+ * `transcribe-native-<build-tuple>` bundle onto its tuple here.
+ */
+function platformTuple() {
+    const { platform, arch } = process;
+    if (platform === "darwin") {
+        if (arch === "arm64")
+            return "darwin-arm64-metal";
+        if (arch === "x64")
+            return "darwin-x64-cpu";
+    }
+    else if (platform === "linux") {
+        if (arch === "x64")
+            return "linux-x64-cpu-vulkan";
+        if (arch === "arm64")
+            return "linux-arm64-cpu-vulkan";
+    }
+    else if (platform === "win32") {
+        if (arch === "x64")
+            return "win32-x64-cpu-vulkan";
+    }
+    return null;
+}
+/** Validate a bundle's contract.json. Throws on a real mismatch. */
+function validateContract(dir, provider) {
+    const file = path.join(dir, "contract.json");
+    let contract;
+    try {
+        contract = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        throw new BackendError(`provider ${provider} is missing a readable contract.json at ${file}: ${String(e)}`);
+    }
+    if (contract.header_hash !== g.PUBLIC_HEADER_HASH) {
+        throw new AbiError(`provider ${provider} was built against header hash ${contract.header_hash} ` +
+            `but this binding expects ${g.PUBLIC_HEADER_HASH}. Reinstall matching packages.`);
+    }
+    if (contract.version && baseVersion(contract.version) !== OUR_VERSION) {
+        throw new VersionMismatch(`provider ${provider} is version ${contract.version} but this binding is ${OUR_VERSION}. ` +
+            `Pre-1.0 requires an exact base-version match.`);
+    }
+}
+function tryPlatformPackage() {
+    const tuple = platformTuple();
+    if (!tuple)
+        return null;
+    const provider = `@transcribe-cpp/${tuple}`;
+    const require = createRequire(import.meta.url);
+    let dir;
+    try {
+        dir = path.dirname(require.resolve(`${provider}/package.json`));
+    }
+    catch {
+        return null; // package not installed — fall through to dev tree
+    }
+    validateContract(dir, provider); // a contract mismatch is fatal, not a fall-through
+    return { libraryPath: path.join(dir, LIB_NAME), artifactDir: dir, provider };
+}
+/** A library produced by the source build (`npm run build:native`). */
+function tryLocalPrebuild() {
+    const tuple = platformTuple();
+    if (!tuple)
+        return null;
+    // <package>/prebuilds/<tuple>/lib/<lib> (build-from-source installs here).
+    const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    const dir = path.join(pkgRoot, "prebuilds", tuple, "lib");
+    const cand = path.join(dir, LIB_NAME);
+    return fs.existsSync(cand)
+        ? { libraryPath: cand, artifactDir: dir, provider: `source-build:${tuple}` }
+        : null;
+}
+/** Walk up to the repo root, then probe known build trees. */
+function tryDevTree() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    let root = null;
+    for (let i = 0; i < 12; i++) {
+        if (fs.existsSync(path.join(dir, "CMakeLists.txt")) &&
+            fs.existsSync(path.join(dir, "include", "transcribe.h"))) {
+            root = dir;
+            break;
+        }
+        const up = path.dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    if (!root)
+        return null;
+    for (const rel of ["build-shared/src", "build-shared/bin", "build/src", "build/bin"]) {
+        const cand = path.join(root, rel, LIB_NAME);
+        if (fs.existsSync(cand)) {
+            return { libraryPath: cand, artifactDir: path.dirname(cand), provider: null };
+        }
+    }
+    return null;
+}
+export function resolveLibrary() {
+    const override = process.env.TRANSCRIBE_LIBRARY;
+    if (override) {
+        if (!fs.existsSync(override)) {
+            throw new TranscribeError(`TRANSCRIBE_LIBRARY points at a missing file: ${override}`);
+        }
+        return { libraryPath: override, artifactDir: path.dirname(override), provider: null };
+    }
+    return (tryPlatformPackage() ??
+        tryLocalPrebuild() ??
+        tryDevTree() ??
+        (() => {
+            throw new BackendError("No transcribe.cpp native library found. Set TRANSCRIBE_LIBRARY, install a " +
+                "matching @transcribe-cpp/<platform> package, run `npm run build:native` to " +
+                `build from source, or build the shared library (build-shared/src/${LIB_NAME}).`);
+        })());
+}

package/dist/native.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Native bootstrap: resolve -> load -> bind -> verify ABI -> version-gate ->
+ * init backends. The single choke point both the public API and tests go
+ * through. Lazy and memoized: nothing loads until the first call.
+ */
+import { type Bound } from "./ffi.js";
+export interface Native extends Bound {
+    libraryPath: string;
+    provider: string | null;
+    abortProto: any;
+    logProto: any;
+}
+export type LogHandler = (level: number, message: string) => void;
+export declare function native(): Native;
+/**
+ * Route native (and ggml) diagnostics to `handler`, or pass null to disable.
+ * The callback may fire from ggml worker threads; koffi marshals it to the
+ * event-loop thread (proven by the M2 spike), so the handler runs on the main
+ * thread. Exceptions thrown by the handler are swallowed (never re-enter C).
+ *
+ * The native callback is installed once during lazy bootstrap, before backend
+ * initialization. Later calls only swap this JS handler; they never call
+ * transcribe_log_set again.
+ */
+export declare function setLogHandler(handler: LogHandler | null): void;

package/dist/native.js

@@ -0,0 +1,77 @@
+/**
+ * Native bootstrap: resolve -> load -> bind -> verify ABI -> version-gate ->
+ * init backends. The single choke point both the public API and tests go
+ * through. Lazy and memoized: nothing loads until the first call.
+ */
+import { resolveLibrary } from "./loader.js";
+import { abortProto, bindLibrary, logProto } from "./ffi.js";
+import { verifyLayouts } from "./abi.js";
+import { BackendError, VersionMismatch } from "./errors.js";
+import { OUR_VERSION, baseVersion } from "./version.js";
+import * as g from "./_generated.js";
+let cached = null;
+let logHandler = null;
+let logRegistered = null;
+function ensureLogCallback(bound) {
+    if (logRegistered)
+        return;
+    const thunk = (level, msg) => {
+        const h = logHandler;
+        if (!h)
+            return;
+        try {
+            h(level, msg ?? "");
+        }
+        catch {
+            /* a logging handler must never propagate into native code */
+        }
+    };
+    logRegistered = bound.koffi.register(thunk, bound.koffi.pointer(logProto()));
+    bound.F.logSet(logRegistered, null);
+}
+export function native() {
+    if (cached)
+        return cached;
+    const resolved = resolveLibrary();
+    const bound = bindLibrary(resolved.libraryPath);
+    verifyLayouts(bound);
+    const nativeVersion = bound.F.version();
+    if (baseVersion(nativeVersion) !== OUR_VERSION) {
+        throw new VersionMismatch(`native library is version ${nativeVersion} but this binding is ${OUR_VERSION} ` +
+            `(pre-1.0 requires an exact base-version match)`);
+    }
+    // transcribe_log_set is only supported as a startup-time install. Register a
+    // stable JS dispatch callback once, before backend init can create worker
+    // threads; setLogHandler later only swaps the JS target.
+    ensureLogCallback(bound);
+    // Register backend modules package-local. On a compiled-in build this is a
+    // near no-op; on a dynamic-backend bundle it scans the artifact dir.
+    let st = bound.F.initBackends(resolved.artifactDir);
+    if (st !== g.TRANSCRIBE_OK)
+        st = bound.F.initBackendsDefault();
+    if (st !== g.TRANSCRIBE_OK) {
+        throw new BackendError(`transcribe_init_backends found no usable compute device in ${resolved.artifactDir}: ` +
+            `${bound.F.statusString(st)} (status ${st})`);
+    }
+    cached = {
+        ...bound,
+        libraryPath: resolved.libraryPath,
+        provider: resolved.provider,
+        abortProto: abortProto(),
+        logProto: logProto(),
+    };
+    return cached;
+}
+/**
+ * Route native (and ggml) diagnostics to `handler`, or pass null to disable.
+ * The callback may fire from ggml worker threads; koffi marshals it to the
+ * event-loop thread (proven by the M2 spike), so the handler runs on the main
+ * thread. Exceptions thrown by the handler are swallowed (never re-enter C).
+ *
+ * The native callback is installed once during lazy bootstrap, before backend
+ * initialization. Later calls only swap this JS handler; they never call
+ * transcribe_log_set again.
+ */
+export function setLogHandler(handler) {
+    logHandler = handler;
+}

package/dist/types.d.ts

@@ -0,0 +1,181 @@
+/** Public value types for the transcribe.cpp TypeScript binding. */
+import type { TranscribeError } from "./errors.js";
+export type Backend = "auto" | "cpu" | "cpu_accel" | "cuda" | "vulkan" | "metal";
+export type KvType = "auto" | "f32" | "f16";
+export type Task = "transcribe" | "translate";
+export type TimestampKind = "none" | "auto" | "segment" | "word" | "token";
+export type Feature = "initial_prompt" | "temperature_fallback" | "long_form" | "cancellation" | "pnc" | "itn";
+/** Mono float32 PCM at the model's native sample rate (16 kHz for v1). */
+export type PcmLike = Float32Array | number[] | ArrayBuffer | Buffer;
+export interface Segment {
+    text: string;
+    t0Ms: number;
+    t1Ms: number;
+    firstWord: number;
+    nWords: number;
+    firstToken: number;
+    nTokens: number;
+}
+export interface Word {
+    text: string;
+    t0Ms: number;
+    t1Ms: number;
+    segIndex: number;
+    firstToken: number;
+    nTokens: number;
+}
+export interface Token {
+    text: string;
+    id: number;
+    p: number;
+    t0Ms: number;
+    t1Ms: number;
+    segIndex: number;
+    wordIndex: number;
+}
+export interface Timings {
+    loadMs: number;
+    melMs: number;
+    encodeMs: number;
+    decodeMs: number;
+}
+export interface Capabilities {
+    nativeSampleRate: number;
+    languages: string[];
+    maxTimestampKind: TimestampKind;
+    supportsLanguageDetect: boolean;
+    supportsTranslate: boolean;
+    supportsStreaming: boolean;
+    supportsSpecDecode: boolean;
+    maxAudioMs: number;
+}
+export interface SessionLimits {
+    effectiveNCtx: number;
+    effectiveMaxAudioMs: number;
+    maxKvBytes: number;
+}
+export interface TranscriptionResult {
+    text: string;
+    language: string;
+    timestampKind: TimestampKind;
+    segments: Segment[];
+    words: Word[];
+    tokens: Token[];
+    timings: Timings;
+    aborted: boolean;
+    truncated: boolean;
+}
+export interface BackendInfo {
+    name: string;
+    description: string;
+    kind: string;
+}
+export interface ModelOptions {
+    /** "auto" (default), or an explicit backend. */
+    backend?: Backend;
+    /** GPU device ordinal for multi-GPU hosts. */
+    gpuDevice?: number;
+}
+export interface SessionOptions {
+    /** CPU threads for CPU-side ops; 0 = library default. */
+    nThreads?: number;
+    kvType?: KvType;
+    /** Context-token cap; 0 = model default. */
+    nCtx?: number;
+}
+export interface TranscribeOptions {
+    task?: Task;
+    language?: string;
+    targetLanguage?: string;
+    timestamps?: TimestampKind;
+    keepSpecialTags?: boolean;
+    /** Speculative-decode draft count; -1 = family default. */
+    specKDrafts?: number;
+    /** Cancel the run cooperatively. */
+    signal?: AbortSignal;
+    /** A run-slot family extension (e.g. whisper). */
+    family?: FamilyExtension;
+}
+/** A native compute device the runtime discovered. */
+export interface DeviceInfo extends BackendInfo {
+}
+/** One result of a batch run: success carries the transcript, failure the error.
+ *  On failure, `error.utteranceIndex` is set, and `error.partialResult` carries any
+ *  recovered transcript when the failure was an abort/truncation. */
+export type BatchItem = {
+    ok: true;
+    result: TranscriptionResult;
+} | {
+    ok: false;
+    error: TranscribeError;
+};
+export type CommitPolicy = "auto" | "on_finalize" | "stable_prefix";
+export type StreamState = "idle" | "active" | "finished" | "failed";
+export type ExtSlot = "run" | "stream";
+export interface StreamUpdate {
+    resultChanged: boolean;
+    isFinal: boolean;
+    revision: number;
+    inputReceivedMs: number;
+    audioCommittedMs: number;
+    bufferedMs: number;
+    committedChanged: boolean;
+    tentativeChanged: boolean;
+}
+export interface StreamText {
+    /** Raw model hypothesis. */
+    full: string;
+    /** Append-only, stable prefix. */
+    committed: string;
+    /** Volatile suffix. */
+    tentative: string;
+}
+export interface StreamOptions {
+    task?: Task;
+    language?: string;
+    targetLanguage?: string;
+    timestamps?: TimestampKind;
+    keepSpecialTags?: boolean;
+    commitPolicy?: CommitPolicy;
+    stablePrefixAgreementN?: number;
+    /** A stream-slot family extension (moonshine, parakeet, voxtral). */
+    family?: FamilyExtension;
+}
+export interface WhisperRunOptions {
+    initialPrompt?: string;
+    conditionOnPrevTokens?: boolean;
+    temperature?: number;
+    temperatureInc?: number;
+    compressionRatioThold?: number;
+    logprobThold?: number;
+    noSpeechThold?: number;
+    maxPrevContextTokens?: number;
+    seed?: number;
+    maxInitialTimestamp?: number;
+}
+export interface MoonshineStreamingOptions {
+    minDecodeIntervalMs?: number;
+}
+export interface ParakeetStreamOptions {
+    attContextRight?: number;
+}
+export interface ParakeetBufferedStreamOptions {
+    leftMs?: number;
+    chunkMs?: number;
+    rightMs?: number;
+}
+export interface VoxtralRealtimeStreamOptions {
+    numDelayTokens?: number;
+    minDecodeIntervalMs?: number;
+}
+export type FamilyExtension = ({
+    kind: "whisper";
+} & WhisperRunOptions) | ({
+    kind: "moonshine";
+} & MoonshineStreamingOptions) | ({
+    kind: "parakeet";
+} & ParakeetStreamOptions) | ({
+    kind: "parakeet_buffered";
+} & ParakeetBufferedStreamOptions) | ({
+    kind: "voxtral";
+} & VoxtralRealtimeStreamOptions);

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Public value types for the transcribe.cpp TypeScript binding. */
+export {};

package/dist/version.d.ts

@@ -0,0 +1,18 @@
+/**
+ * This binding's own version, and the base-version helper the load gates use.
+ *
+ * `OUR_VERSION` is read from the API package's `package.json` at runtime — NOT
+ * from the generated FFI macros. The generators stopped emitting
+ * `TRANSCRIBE_VERSION_*` so a version-only bump no longer churns generated
+ * files or the abihash (notes/releasing.md §8 P0 #1). `package.json` is always
+ * present in the published tarball and sits one directory above the compiled
+ * `dist/` output, so a runtime `require("../package.json")` resolves it.
+ *
+ * A runtime `createRequire(...)` is used rather than `import "../package.json"`:
+ * tsconfig sets `rootDir: "src"` with no `resolveJsonModule`, so a static JSON
+ * import would break the emit layout.
+ */
+/** Leading dotted-numeric release segment, suffix stripped: "0.0.1.post3" -> "0.0.1". */
+export declare function baseVersion(v: string): string;
+/** The base `MAJOR.MINOR.PATCH` this binding was built as. */
+export declare const OUR_VERSION: string;

package/dist/version.js

@@ -0,0 +1,30 @@
+/**
+ * This binding's own version, and the base-version helper the load gates use.
+ *
+ * `OUR_VERSION` is read from the API package's `package.json` at runtime — NOT
+ * from the generated FFI macros. The generators stopped emitting
+ * `TRANSCRIBE_VERSION_*` so a version-only bump no longer churns generated
+ * files or the abihash (notes/releasing.md §8 P0 #1). `package.json` is always
+ * present in the published tarball and sits one directory above the compiled
+ * `dist/` output, so a runtime `require("../package.json")` resolves it.
+ *
+ * A runtime `createRequire(...)` is used rather than `import "../package.json"`:
+ * tsconfig sets `rootDir: "src"` with no `resolveJsonModule`, so a static JSON
+ * import would break the emit layout.
+ */
+import { createRequire } from "node:module";
+/** Leading dotted-numeric release segment, suffix stripped: "0.0.1.post3" -> "0.0.1". */
+export function baseVersion(v) {
+    const m = /^\d+(?:\.\d+)*/.exec(v.trim());
+    return m ? m[0] : v.trim();
+}
+function readPackageVersion() {
+    const require = createRequire(import.meta.url);
+    const pkg = require("../package.json");
+    if (!pkg.version) {
+        throw new Error("transcribe-cpp: package.json is missing a version field");
+    }
+    return pkg.version;
+}
+/** The base `MAJOR.MINOR.PATCH` this binding was built as. */
+export const OUR_VERSION = baseVersion(readPackageVersion());

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "transcribe-cpp",
-  "version": "0.0.0",
-  "description": "TypeScript/Node.js bindings for transcribe.cpp (pre-release name reservation placeholder)",
+  "version": "0.0.3",
+  "description": "TypeScript/Node.js bindings for transcribe.cpp — a C/C++ speech-to-text library built on ggml",
   "type": "module",
   "exports": {
     ".": {
@@ -12,7 +12,12 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "scripts/build-from-source.mjs"
+  ],
   "license": "MIT",
   "author": "The transcribe.cpp authors",
   "homepage": "https://github.com/handy-computer/transcribe.cpp#readme",
@@ -23,15 +28,37 @@
   "bugs": {
     "url": "https://github.com/handy-computer/transcribe.cpp/issues"
   },
-  "keywords": ["transcription", "speech-to-text", "asr", "stt", "ggml", "whisper", "parakeet"],
+  "keywords": [
+    "transcription",
+    "speech-to-text",
+    "asr",
+    "stt",
+    "ggml",
+    "whisper",
+    "parakeet"
+  ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "bun run build"
+    "build:native": "node scripts/build-from-source.mjs",
+    "pretest": "npm run build",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "koffi": "^3.0.2"
+  },
+  "optionalDependencies": {
+    "@transcribe-cpp/darwin-arm64-metal": "0.0.3",
+    "@transcribe-cpp/darwin-x64-cpu": "0.0.3",
+    "@transcribe-cpp/linux-x64-cpu-vulkan": "0.0.3",
+    "@transcribe-cpp/linux-arm64-cpu-vulkan": "0.0.3",
+    "@transcribe-cpp/win32-x64-cpu-vulkan": "0.0.3"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "typescript": "^5.6.0"
   }
 }

package/scripts/build-from-source.mjs

@@ -0,0 +1,90 @@
+// Build libtranscribe from source — the universal fallback when no prebuilt
+// @transcribe-cpp/<platform> package exists for the host (a new arch, a custom
+// backend, a self-contained library). The result installs into
+// `prebuilds/<tuple>/`, which the loader probes automatically — no env var.
+//
+//   node scripts/build-from-source.mjs [--source <repo>] [--self-contained]
+//
+//   --source           Path to a transcribe.cpp checkout (default:
+//                      $TRANSCRIBE_SOURCE_DIR, else walk up to find the repo).
+//   --self-contained   Link ggml statically into one libtranscribe (no sibling
+//                      ggml libraries). Otherwise ggml ships as sibling shared
+//                      libs alongside libtranscribe.
+//
+// This drives CMake directly (the binding is FFI over a shared library, not an
+// N-API addon — so cmake-js, which builds .node addons, is not the right tool).
+// Requires cmake + a C/C++ toolchain (Ninja recommended). On macOS Metal is
+// enabled and embedded; on Linux the default CPU backend builds (add your own
+// -D flags via TRANSCRIBE_CMAKE_FLAGS for CUDA/Vulkan/etc.).
+
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? (process.argv[i + 1]?.startsWith("--") ? true : process.argv[i + 1] ?? true) : undefined;
+}
+
+function tuple() {
+  const { platform, arch } = process;
+  const a = arch === "x64" ? "x64" : arch;
+  if (platform === "darwin") return arch === "arm64" ? "darwin-arm64-metal" : "darwin-x64-cpu";
+  if (platform === "linux") return `linux-${a}-cpu-vulkan`;
+  if (platform === "win32") return `win32-${a}-cpu-vulkan`;
+  throw new Error(`unsupported platform ${platform}/${arch}`);
+}
+
+function findSource() {
+  const explicit = arg("source") || process.env.TRANSCRIBE_SOURCE_DIR;
+  const start = typeof explicit === "string" ? explicit : PKG_ROOT;
+  let dir = path.resolve(start);
+  for (let i = 0; i < 12; i++) {
+    if (
+      fs.existsSync(path.join(dir, "CMakeLists.txt")) &&
+      fs.existsSync(path.join(dir, "include", "transcribe.h"))
+    ) {
+      return dir;
+    }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  throw new Error(
+    "could not locate a transcribe.cpp source tree. Pass --source <repo> or set " +
+      "TRANSCRIBE_SOURCE_DIR (the published npm package ships no C++ sources).",
+  );
+}
+
+function run(cmd, args) {
+  console.log(`$ ${cmd} ${args.join(" ")}`);
+  const r = spawnSync(cmd, args, { stdio: "inherit" });
+  if (r.status !== 0) {
+    throw new Error(`${cmd} exited with ${r.status ?? r.signal}`);
+  }
+}
+
+const src = findSource();
+const t = tuple();
+const buildDir = path.join(PKG_ROOT, "build-from-source");
+const prefix = path.join(PKG_ROOT, "prebuilds", t);
+const selfContained = Boolean(arg("self-contained"));
+
+console.log(`building libtranscribe for ${t}`);
+console.log(`  source: ${src}`);
+console.log(`  install prefix: ${prefix}${selfContained ? " (self-contained)" : ""}`);
+
+const flags = ["-DTRANSCRIBE_BUILD_SHARED=ON"];
+if (process.platform === "darwin") flags.push("-DGGML_METAL=ON", "-DGGML_METAL_EMBED_LIBRARY=ON");
+if (selfContained) flags.push("-DBUILD_SHARED_LIBS=OFF"); // ggml static -> one libtranscribe
+if (process.env.TRANSCRIBE_CMAKE_FLAGS) flags.push(...process.env.TRANSCRIBE_CMAKE_FLAGS.split(" ").filter(Boolean));
+
+fs.rmSync(prefix, { recursive: true, force: true });
+run("cmake", ["-B", buildDir, "-S", src, "-G", "Ninja", ...flags]);
+run("cmake", ["--build", buildDir, "--target", "transcribe"]);
+run("cmake", ["--install", buildDir, "--prefix", prefix]);
+
+console.log(`\ndone. The loader will find prebuilds/${t}/lib/ automatically.`);