transcribe-cpp 0.0.3 → 0.0.5

package/README.md

@@ -200,6 +200,45 @@ N-API addon, so `cmake-js` does not apply) and installs into `prebuilds/<tuple>/
 which the loader finds automatically. Requires `cmake` and a C/C++ toolchain.
 You can also point `TRANSCRIBE_LIBRARY` at any `libtranscribe` you built.
 
+## Packaging an app (Electron / Tauri)
+
+The native code ships as a self-contained `@transcribe-cpp/<platform>` package
+(the shared library plus its sibling ggml libs / backend modules, in one
+directory). Because npm resolution is transitive, your app can locate that
+directory at *build* time — there is nothing special to wire through.
+`artifactDir()` returns it **without loading the library** (no dlopen), which is
+exactly what a bundler/pack step needs:
+
+```js
+import { artifactDir } from "transcribe-cpp";
+import * as fs from "node:fs";
+
+const dir = artifactDir();
+const lib =
+  process.platform === "win32" ? "transcribe.dll"
+  : process.platform === "darwin" ? "libtranscribe.dylib"
+  : "libtranscribe.so";
+
+// HARD-FAIL if the artifact is missing/empty: better to break the build than
+// ship a silently broken installer that crashes at first transcribe() call.
+if (!fs.existsSync(`${dir}/${lib}`)) {
+  throw new Error(`native library not found in ${dir}; the platform package is not bundled`);
+}
+// copy `dir` into your app resources, or feed it to your bundler config…
+```
+
+The native files are real binaries, so they must not be packed into an asar
+archive. With **electron-builder**, unpack the platform packages:
+
+```jsonc
+// package.json → "build"
+{ "asarUnpack": ["node_modules/@transcribe-cpp/**"] }
+```
+
+For a **Tauri** app whose native bits come from the Rust crate instead, see that
+crate's "Packaging a distributable" section — there the artifact dir is exposed
+to your `build.rs` as `DEP_TRANSCRIBE_CPP_RUNTIME_DIR`.
+
 ## Waived requirements
 
 - **Per-field ABI layout is not waived** (unlike Rust/Swift): TypeScript has no
@@ -211,5 +250,5 @@ You can also point `TRANSCRIBE_LIBRARY` at any `libtranscribe` you built.
 
 ## License
 
-MIT. Bundled native packages include third-party license texts (ggml and any
-bundled backend runtimes).
+MIT. Bundled native packages include third-party license texts (ggml, miniz,
+and any bundled backend runtimes).

package/dist/_generated.d.ts

@@ -1,4 +1,4 @@
-export declare const PUBLIC_HEADER_HASH = "2273744299e5aa65";
+export declare const PUBLIC_HEADER_HASH = "ebe6a6816e34a24e";
 export declare const TRANSCRIBE_OK = 0;
 export declare const TRANSCRIBE_ERR_INVALID_ARG = 1;
 export declare const TRANSCRIBE_ERR_NOT_IMPLEMENTED = 2;
@@ -62,6 +62,10 @@ export declare const TRANSCRIBE_BACKEND_METAL = 2;
 export declare const TRANSCRIBE_BACKEND_VULKAN = 3;
 export declare const TRANSCRIBE_BACKEND_CPU_ACCEL = 4;
 export declare const TRANSCRIBE_BACKEND_CUDA = 5;
+export declare const TRANSCRIBE_DEVICE_TYPE_CPU = 0;
+export declare const TRANSCRIBE_DEVICE_TYPE_GPU = 1;
+export declare const TRANSCRIBE_DEVICE_TYPE_IGPU = 2;
+export declare const TRANSCRIBE_DEVICE_TYPE_ACCEL = 3;
 export declare const TRANSCRIBE_FEATURE_INITIAL_PROMPT = 0;
 export declare const TRANSCRIBE_FEATURE_TEMPERATURE_FALLBACK = 1;
 export declare const TRANSCRIBE_FEATURE_LONG_FORM = 2;

package/dist/_generated.js

@@ -10,7 +10,7 @@
 // Stable digest of the ABI surface (structs, enums, macros, layout,
 // prototypes), computed by the Python oracle and pinned here so a header
 // ABI change turns this binding's drift check red for conscious review.
-export const PUBLIC_HEADER_HASH = "2273744299e5aa65";
+export const PUBLIC_HEADER_HASH = "ebe6a6816e34a24e";
 // === enum constants ===
 export const TRANSCRIBE_OK = 0;
 export const TRANSCRIBE_ERR_INVALID_ARG = 1;
@@ -75,6 +75,10 @@ export const TRANSCRIBE_BACKEND_METAL = 2;
 export const TRANSCRIBE_BACKEND_VULKAN = 3;
 export const TRANSCRIBE_BACKEND_CPU_ACCEL = 4;
 export const TRANSCRIBE_BACKEND_CUDA = 5;
+export const TRANSCRIBE_DEVICE_TYPE_CPU = 0;
+export const TRANSCRIBE_DEVICE_TYPE_GPU = 1;
+export const TRANSCRIBE_DEVICE_TYPE_IGPU = 2;
+export const TRANSCRIBE_DEVICE_TYPE_ACCEL = 3;
 export const TRANSCRIBE_FEATURE_INITIAL_PROMPT = 0;
 export const TRANSCRIBE_FEATURE_TEMPERATURE_FALLBACK = 1;
 export const TRANSCRIBE_FEATURE_LONG_FORM = 2;
@@ -98,7 +102,7 @@ export const TRANSCRIBE_EXT_KIND_VOXTRAL_REALTIME_STREAM = 1414746710;
 export const TRANSCRIBE_EXT_KIND_WHISPER_RUN = 1314015319;
 export const STRUCT_LAYOUT = {
     'transcribe_ext': { size: 16, align: 8, offsets: { 'size': 0, 'kind': 8 } },
-    'transcribe_backend_device': { size: 32, align: 8, offsets: { 'struct_size': 0, 'name': 8, 'description': 16, 'kind': 24 } },
+    'transcribe_backend_device': { size: 64, align: 8, offsets: { 'struct_size': 0, 'name': 8, 'description': 16, 'kind': 24, 'device_id': 32, 'memory_total': 40, 'memory_free': 48, 'device_type': 56 } },
     'transcribe_model_load_params': { size: 16, align: 8, offsets: { 'struct_size': 0, 'backend': 8, 'gpu_device': 12 } },
     'transcribe_session_params': { size: 24, align: 8, offsets: { 'struct_size': 0, 'n_threads': 8, 'kv_type': 12, 'n_ctx': 16 } },
     'transcribe_run_params': { size: 64, align: 8, offsets: { 'struct_size': 0, 'task': 8, 'timestamps': 12, 'pnc': 16, 'itn': 20, 'language': 24, 'target_language': 32, 'keep_special_tags': 40, 'family': 48, 'spec_k_drafts': 56 } },
@@ -138,7 +142,7 @@ export const ABI_STRUCT_IDS = {
 export function defineTypes(koffi) {
     const T = {};
     T['transcribe_ext'] = koffi.struct({ size: 'uint64_t', kind: 'uint32_t' });
-    T['transcribe_backend_device'] = koffi.struct({ struct_size: 'uint64_t', name: 'char *', description: 'char *', kind: 'char *' });
+    T['transcribe_backend_device'] = koffi.struct({ struct_size: 'uint64_t', name: 'char *', description: 'char *', kind: 'char *', device_id: 'char *', memory_total: 'uint64_t', memory_free: 'uint64_t', device_type: 'int' });
     T['transcribe_model_load_params'] = koffi.struct({ struct_size: 'uint64_t', backend: 'int', gpu_device: 'int' });
     T['transcribe_session_params'] = koffi.struct({ struct_size: 'uint64_t', n_threads: 'int', kv_type: 'int', n_ctx: 'int32_t' });
     T['transcribe_run_params'] = koffi.struct({ struct_size: 'uint64_t', task: 'int', timestamps: 'int', pnc: 'int', itn: 'int', language: 'char *', target_language: 'char *', keep_special_tags: 'bool', family: 'void *', spec_k_drafts: 'int32_t' });
@@ -198,6 +202,7 @@ export const FUNCTION_SIGNATURES = {
     'transcribe_model_backend': { ret: 'const char *', args: ['const struct transcribe_model *'] },
     'transcribe_model_free': { ret: 'void', args: ['struct transcribe_model *'] },
     'transcribe_model_get_capabilities': { ret: 'transcribe_status', args: ['const struct transcribe_model *', 'struct transcribe_capabilities *'] },
+    'transcribe_model_get_device': { ret: 'transcribe_status', args: ['const struct transcribe_model *', 'struct transcribe_backend_device *'] },
     'transcribe_model_load_file': { ret: 'transcribe_status', args: ['const char *', 'const struct transcribe_model_load_params *', 'struct transcribe_model **'] },
     'transcribe_model_load_params_init': { ret: 'void', args: ['struct transcribe_model_load_params *'] },
     'transcribe_model_supports': { ret: '_Bool', args: ['const struct transcribe_model *', 'transcribe_feature'] },

package/dist/ffi.js

@@ -51,6 +51,10 @@ export function bindLibrary(libraryPath) {
         modelArch: lib.func("transcribe_model_arch_string", "str", ["void *"]),
         modelVariant: lib.func("transcribe_model_variant_string", "str", ["void *"]),
         modelBackend: lib.func("transcribe_model_backend", "str", ["void *"]),
+        modelGetDevice: lib.func("transcribe_model_get_device", "int", [
+            "void *",
+            iop(T.transcribe_backend_device),
+        ]),
         modelSupports: lib.func("transcribe_model_supports", "bool", ["void *", "int"]),
         tokenize: lib.func("transcribe_tokenize", "int", ["void *", "str", "int32_t *", "size_t"]),
         capabilitiesInit: lib.func("transcribe_capabilities_init", "void", [

package/dist/index.d.ts

@@ -17,6 +17,19 @@ export declare function version(): {
     headerHash: string;
 };
 export declare function libraryPath(): string;
+/**
+ * The directory holding the native library and its sibling ggml libs / backend
+ * modules — resolved WITHOUT loading the library (no dlopen, no ABI check, no
+ * backend init), unlike every other entry point here.
+ *
+ * This is the build/packaging hook: call it from a bundler config or pack step
+ * to copy the native artifacts into your installer (Electron `asarUnpack`, Tauri
+ * `resources`, etc.). Resolution follows the same order as the runtime loader
+ * (`TRANSCRIBE_LIBRARY` → the `@transcribe-cpp/<platform>` package → a local
+ * prebuild → the dev tree) and throws if nothing is found. For runtime use,
+ * `libraryPath()` returns the resolved library path of the *loaded* binding.
+ */
+export declare function artifactDir(): string;
 export declare function getAvailableBackends(): BackendInfo[];
 export declare function backendAvailable(backend: Backend): boolean;
 export declare class Session {
@@ -80,6 +93,10 @@ export declare class TranscribeModel {
     get arch(): string;
     get variant(): string;
     get backend(): string;
+    /** The compute device this model is running on. `memoryFree` is a live
+     *  snapshot, so read this again to poll how much device memory is left
+     *  after the model loaded. */
+    get device(): BackendInfo;
     dispose(): void;
     [Symbol.dispose](): void;
 }

package/dist/index.js

@@ -6,6 +6,7 @@
  * backend discovery, log routing, and cooperative cancellation.
  */
 import { native, setLogHandler } from "./native.js";
+import { resolveLibrary } from "./loader.js";
 import * as g from "./_generated.js";
 import { Aborted, Busy, exceptionForStatus, InvalidArgument, ModelLoadError, NotImplementedByModel, OutputTruncated, TranscribeError, UnsupportedRequest, } from "./errors.js";
 export * from "./types.js";
@@ -216,6 +217,42 @@ export function version() {
 export function libraryPath() {
     return native().libraryPath;
 }
+/**
+ * The directory holding the native library and its sibling ggml libs / backend
+ * modules — resolved WITHOUT loading the library (no dlopen, no ABI check, no
+ * backend init), unlike every other entry point here.
+ *
+ * This is the build/packaging hook: call it from a bundler config or pack step
+ * to copy the native artifacts into your installer (Electron `asarUnpack`, Tauri
+ * `resources`, etc.). Resolution follows the same order as the runtime loader
+ * (`TRANSCRIBE_LIBRARY` → the `@transcribe-cpp/<platform>` package → a local
+ * prebuild → the dev tree) and throws if nothing is found. For runtime use,
+ * `libraryPath()` returns the resolved library path of the *loaded* binding.
+ */
+export function artifactDir() {
+    return resolveLibrary().artifactDir;
+}
+const DEVICE_TYPE_NAMES = {
+    [g.TRANSCRIBE_DEVICE_TYPE_CPU]: "cpu",
+    [g.TRANSCRIBE_DEVICE_TYPE_GPU]: "gpu",
+    [g.TRANSCRIBE_DEVICE_TYPE_IGPU]: "igpu",
+    [g.TRANSCRIBE_DEVICE_TYPE_ACCEL]: "accel",
+};
+// Decode a koffi-filled transcribe_backend_device struct into a BackendInfo.
+// memory_* are uint64 (bigint from koffi) but stay well under 2^53 for any
+// real device, so num() narrows them losslessly.
+function deviceFromRaw(dev, index = null) {
+    return {
+        name: dev.name ?? "",
+        description: dev.description ?? "",
+        kind: dev.kind ?? "",
+        deviceType: DEVICE_TYPE_NAMES[dev.device_type] ?? "unknown",
+        deviceId: dev.device_id ?? null,
+        memoryTotal: num(dev.memory_total),
+        memoryFree: num(dev.memory_free),
+        index,
+    };
+}
 export function getAvailableBackends() {
     const n = native();
     const count = n.F.backendDeviceCount();
@@ -224,7 +261,7 @@ export function getAvailableBackends() {
         const dev = {};
         n.F.backendDeviceInit(dev);
         check(n, n.F.getBackendDevice(i, dev), `reading backend device ${i}`);
-        out.push({ name: dev.name ?? "", description: dev.description ?? "", kind: dev.kind ?? "" });
+        out.push(deviceFromRaw(dev, i));
     }
     return out;
 }
@@ -1049,6 +1086,15 @@ export class TranscribeModel {
     get backend() {
         return this.#n.F.modelBackend(this.handle) ?? "";
     }
+    /** The compute device this model is running on. `memoryFree` is a live
+     *  snapshot, so read this again to poll how much device memory is left
+     *  after the model loaded. */
+    get device() {
+        const dev = {};
+        this.#n.F.backendDeviceInit(dev);
+        check(this.#n, this.#n.F.modelGetDevice(this.handle, dev), "reading model device");
+        return deviceFromRaw(dev);
+    }
     dispose() {
         if (this.#disposed)
             return;

package/dist/types.d.ts

@@ -65,15 +65,37 @@ export interface TranscriptionResult {
     aborted: boolean;
     truncated: boolean;
 }
+/** Vendor-agnostic device class, orthogonal to {@link BackendInfo.kind}.
+ *  `"unknown"` is reported for a device-type value newer than this binding —
+ *  distinguish such devices by {@link BackendInfo.deviceId} / name, not this axis. */
+export type DeviceType = "cpu" | "gpu" | "igpu" | "accel" | "unknown";
 export interface BackendInfo {
     name: string;
     description: string;
     kind: string;
+    /** The CPU/GPU/IGPU/ACCEL axis, orthogonal to `kind`. */
+    deviceType: DeviceType;
+    /** Stable hardware id (PCI bus id) when the backend reports one, else null
+     *  (e.g. Metal). */
+    deviceId: string | null;
+    /** Reported device memory capacity in bytes, or 0 if unreported. */
+    memoryTotal: number;
+    /** Available device memory in bytes — a snapshot at query time, or 0 if
+     *  unreported. Re-query (via {@link getAvailableBackends} or `model.device`)
+     *  to refresh; backend-defined and not comparable across device kinds. */
+    memoryFree: number;
+    /** Registry index of this device — the value to pass as
+     *  {@link ModelOptions.gpuDevice} to select it (0 selects the auto / first
+     *  device). `null` when this came from `model.device`, since
+     *  `transcribe_model_get_device` does not expose an index; correlate such a
+     *  device back to {@link getAvailableBackends} by `deviceId` / `name`
+     *  instead. Order-dependent and not stable across driver updates or hosts. */
+    index: number | null;
 }
 export interface ModelOptions {
     /** "auto" (default), or an explicit backend. */
     backend?: Backend;
-    /** GPU device ordinal for multi-GPU hosts. */
+    /** GPU device registry index. 0 means auto / first matching device. */
     gpuDevice?: number;
 }
 export interface SessionOptions {
@@ -96,9 +118,6 @@ export interface TranscribeOptions {
     /** 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transcribe-cpp",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "TypeScript/Node.js bindings for transcribe.cpp — a C/C++ speech-to-text library built on ggml",
   "type": "module",
   "exports": {
@@ -51,11 +51,11 @@
     "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"
+    "@transcribe-cpp/darwin-arm64-metal": "0.0.5",
+    "@transcribe-cpp/darwin-x64-cpu": "0.0.5",
+    "@transcribe-cpp/linux-x64-cpu-vulkan": "0.0.5",
+    "@transcribe-cpp/linux-arm64-cpu-vulkan": "0.0.5",
+    "@transcribe-cpp/win32-x64-cpu-vulkan": "0.0.5"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",