transcribe-cpp 0.0.0 → 0.0.3

package/README.md

@@ -1,17 +1,215 @@
 # transcribe-cpp
 
 TypeScript/Node.js bindings for [transcribe.cpp](https://github.com/handy-computer/transcribe.cpp),
-a C/C++ speech-to-text library built on ggml.
+a C/C++ speech-to-text library built on ggml — Whisper, Parakeet, Moonshine,
+Voxtral, and more, on CPU, Metal, CUDA, and Vulkan.
 
-> **Status: placeholder.** This release reserves the `transcribe-cpp` name on
-> npm while the first-party bindings are developed. It ships no functionality
-> yet. Watch the repository for the first functional release.
+```sh
+npm install transcribe-cpp
+```
+
+A matching prebuilt native package is selected automatically for your
+platform (`@transcribe-cpp/<platform>`); there is nothing to compile and no
+environment variables to set.
+
+## Quickstart
+
+```ts
+import { TranscribeModel } from "transcribe-cpp";
+
+const model = await TranscribeModel.load("whisper-tiny-Q5_K_M.gguf");
+
+// 16 kHz mono float32 PCM (bring your own decoder).
+const result = await model.transcribe(pcm, { timestamps: "segment" });
+
+console.log(result.text);
+console.log(result.language); // detected or requested
+for (const seg of result.segments) {
+  console.log(`[${seg.t0Ms}–${seg.t1Ms}ms] ${seg.text}`);
+}
+
+model.dispose();
+```
+
+### Streaming
+
+```ts
+const session = model.createSession();
+const stream = await session.stream({ commitPolicy: "stable_prefix" });
+
+for (const chunk of pcmChunks) {
+  await stream.feed(chunk);
+  const { committed, tentative } = stream.text; // committed is append-only/stable
+  render(committed, tentative);
+}
+await stream.finalize();
+stream.reset();
+```
+
+### Batch
+
+```ts
+const items = await session.runBatch([pcmA, pcmB]);
+for (const item of items) {
+  if (item.ok) console.log(item.result.text);
+  else console.error(item.error.message); // per-utterance failure
+}
+```
+
+### Cancellation
+
+```ts
+const ac = new AbortController();
+setTimeout(() => ac.abort(), 5000);
+try {
+  await model.transcribe(pcm, { signal: ac.signal });
+} catch (e) {
+  if (e instanceof Aborted) console.log("partial:", e.partialResult?.text);
+}
+```
+
+### Family extensions
+
+Per-family options are a typed, discriminated union passed as `family`:
+
+```ts
+// Whisper is a run-slot extension:
+await model.transcribe(pcm, { family: { kind: "whisper", initialPrompt: "…" } });
+
+// Streaming families (moonshine, parakeet, voxtral) are stream-slot:
+const stream = await session.stream({ family: { kind: "moonshine" } });
+
+model.accepts({ kind: "whisper" }); // does this model take that extension?
+```
+
+### Resource management
+
+`TranscribeModel`, `Session`, and `Stream` all implement `Symbol.dispose`, so
+`using` works (TypeScript 5.2+ / Node 22+):
 
 ```ts
-import { version } from "transcribe-cpp";
+using model = await TranscribeModel.load("model.gguf");
+using session = model.createSession();
+// disposed automatically at block exit
+```
+
+Disposing a model disposes its sessions; disposing a stream resets it (releasing
+the model lease). Disposal is idempotent and order-independent.
+
+## Backend selection
+
+```ts
+import { getAvailableBackends, backendAvailable } from "transcribe-cpp";
+
+getAvailableBackends(); // [{ kind: "metal", name: "MTL0", description: "…" }, …]
+backendAvailable("cuda"); // boolean — never throws
+
+const model = await TranscribeModel.load("model.gguf", { backend: "metal" });
+```
+
+`backend` defaults to `"auto"` (best accelerator, else CPU). A missing Vulkan
+loader/driver degrades silently to CPU; an explicit backend that cannot be
+satisfied raises a `BackendError`.
+
+## Thread-safety
+
+Your JavaScript runs on one thread, but `run`/`feed`/`finalize` dispatch the
+native compute to a **libuv worker thread** (via koffi's async calls), so the
+event loop stays responsive while inference runs.
+
+The C library allows **one compute in flight per model** — a `run`, a `runBatch`,
+or an *active stream* — across all of its sessions. The binding enforces this:
+every compute call serializes through an internal model-wide mutex, and an active
+stream holds a model-wide lease for its whole lifetime. While a stream is active
+(after `stream()`, before `finalize()`/`reset()`), a `run`/`runBatch`/`stream` on
+any session of that model is refused with a `Busy` error rather than allowed to
+race. So to parallelize, load one model per worker; to share a model, finalize or
+reset the stream first. A single `Session` is single-use-at-a-time — don't call
+`run`/`feed` on the same session concurrently.
+
+Hand-offs are ordered, not racy: `finalize()`/`reset()`/`dispose()` release the
+lease only after the native teardown runs on the shared queue, so the slot is
+never freed early. Issue the teardown before the next `stream()`/`run()` and it
+is correctly serialized — `stream.reset(); const next = await session.stream()`
+works without awaiting the (void) `reset()`. The reverse order — beginning before
+the teardown — is refused with `Busy`, by design.
+
+Because the compute is genuinely on another thread, **do not touch a session
+while a call against it is in flight** — it is single-threaded in the C library:
+
+- Reading a stream's `text`/`state`/`revision`/`lastStatus`, or a session's
+  `limits`/`wasAborted`, during an un-awaited `feed`/`finalize`/`run` **throws**.
+- `reset()` and `dispose()` are safe to call any time: the native teardown is
+  deferred behind any in-flight call, so it never frees a session mid-compute.
+- Disposing a `Session` or `TranscribeModel` while a stream is still active
+  releases the lease and invalidates the stream — its later calls throw rather
+  than touch the freed handle.
+- The **input PCM is borrowed, not copied**: `run`/`runBatch`/`feed` hand the
+  buffer to native code that reads it on the worker thread, so do not mutate it
+  (e.g. reuse a scratch/capture buffer) until the returned promise resolves.
+  Pass a fresh buffer per call, or `await` before overwriting.
+
+The normal pattern is safe — `await` first, then read:
 
-console.log(version);
+```ts
+await stream.feed(chunk);
+const { committed, tentative } = stream.text; // ✓ feed has completed
+
+const p = stream.feed(chunk);
+stream.text;                                  // ✗ throws: read while feed in flight
+await p;
+```
+
+Since JavaScript has no destructors, a stream holds the model's lease until you
+`finalize()`, `reset()`, or let `using` dispose it — drop the reference without
+one and the model stays `Busy` until you dispose the session or model. Always
+finalize/reset (or use `using`).
+
+Result strings are copied at the boundary; the objects you get back are fully
+owned and outlive the model.
+
+## Runtime support
+
+The binding is one native artifact (koffi, an N-API addon) plus plain ESM, so any
+runtime with N-API support runs the same package — there is no per-runtime build.
+
+- **Node ≥ 22** — the primary, fully tested target.
+- **Deno ≥ 2** — runs the package unmodified via `deno run` (use `--allow-ffi
+  --allow-read --allow-env`, or `-A`). Note: `deno compile` does not bundle native
+  addons, so the compiled-binary path is unsupported.
+- **Bun** — not yet. Bun loads the addon and runs, but currently crashes in its
+  own N-API finalizer (`napi_reference_unref`); this is an upstream Bun bug, fixed
+  on Bun's side, not here.
+
+## Building from source
+
+The universal fallback when no prebuilt package exists for your platform (a new
+arch, a custom backend, or a single self-contained library):
+
+```sh
+# from a transcribe.cpp checkout:
+npm run build:native -- --source /path/to/transcribe.cpp
+# add --self-contained to link ggml into one libtranscribe
+
+# from a consumer project (the script ships in the package):
+node node_modules/transcribe-cpp/scripts/build-from-source.mjs --source /path/to/transcribe.cpp
 ```
 
-- Package: `transcribe-cpp`
-- License: MIT
+This drives CMake directly (the binding is FFI over a shared library, not an
+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.
+
+## Waived requirements
+
+- **Per-field ABI layout is not waived** (unlike Rust/Swift): TypeScript has no
+  compiler reading the C headers, so — like the Python ctypes binding — the
+  generated struct layout is verified at load against both the captured
+  C-compiler layout and the live library (`transcribe_abi_struct_size/_align`).
+- **Buffer model load** awaits `transcribe_model_load_buffer` in the C API; only
+  file load is exposed today.
+
+## License
+
+MIT. Bundled native packages include third-party license texts (ggml and any
+bundled backend runtimes).

package/dist/_generated.d.ts

@@ -0,0 +1,97 @@
+export declare const PUBLIC_HEADER_HASH = "2273744299e5aa65";
+export declare const TRANSCRIBE_OK = 0;
+export declare const TRANSCRIBE_ERR_INVALID_ARG = 1;
+export declare const TRANSCRIBE_ERR_NOT_IMPLEMENTED = 2;
+export declare const TRANSCRIBE_ERR_FILE_NOT_FOUND = 3;
+export declare const TRANSCRIBE_ERR_GGUF = 4;
+export declare const TRANSCRIBE_ERR_UNSUPPORTED_ARCH = 5;
+export declare const TRANSCRIBE_ERR_UNSUPPORTED_VARIANT = 6;
+export declare const TRANSCRIBE_ERR_OOM = 7;
+export declare const TRANSCRIBE_ERR_BACKEND = 8;
+export declare const TRANSCRIBE_ERR_SAMPLE_RATE = 9;
+export declare const TRANSCRIBE_ERR_UNSUPPORTED_LANGUAGE = 10;
+export declare const TRANSCRIBE_ERR_UNSUPPORTED_TASK = 11;
+export declare const TRANSCRIBE_ERR_UNSUPPORTED_TIMESTAMPS = 12;
+export declare const TRANSCRIBE_ERR_ABORTED = 13;
+export declare const TRANSCRIBE_ERR_BAD_STRUCT_SIZE = 14;
+export declare const TRANSCRIBE_ERR_UNSUPPORTED_PNC = 15;
+export declare const TRANSCRIBE_ERR_UNSUPPORTED_ITN = 16;
+export declare const TRANSCRIBE_ERR_INPUT_TOO_LONG = 17;
+export declare const TRANSCRIBE_ERR_OUTPUT_TRUNCATED = 18;
+export declare const TRANSCRIBE_ABI_MODEL_LOAD_PARAMS = 0;
+export declare const TRANSCRIBE_ABI_SESSION_PARAMS = 1;
+export declare const TRANSCRIBE_ABI_RUN_PARAMS = 2;
+export declare const TRANSCRIBE_ABI_STREAM_PARAMS = 3;
+export declare const TRANSCRIBE_ABI_CAPABILITIES = 4;
+export declare const TRANSCRIBE_ABI_TIMINGS = 5;
+export declare const TRANSCRIBE_ABI_SEGMENT = 6;
+export declare const TRANSCRIBE_ABI_WORD = 7;
+export declare const TRANSCRIBE_ABI_TOKEN = 8;
+export declare const TRANSCRIBE_ABI_STREAM_UPDATE = 9;
+export declare const TRANSCRIBE_ABI_STREAM_TEXT = 10;
+export declare const TRANSCRIBE_ABI_SESSION_LIMITS = 11;
+export declare const TRANSCRIBE_ABI_EXT = 12;
+export declare const TRANSCRIBE_ABI_BACKEND_DEVICE = 13;
+export declare const TRANSCRIBE_LOG_LEVEL_NONE = 0;
+export declare const TRANSCRIBE_LOG_LEVEL_INFO = 1;
+export declare const TRANSCRIBE_LOG_LEVEL_WARN = 2;
+export declare const TRANSCRIBE_LOG_LEVEL_ERROR = 3;
+export declare const TRANSCRIBE_LOG_LEVEL_DEBUG = 4;
+export declare const TRANSCRIBE_LOG_LEVEL_CONT = 5;
+export declare const TRANSCRIBE_TASK_TRANSCRIBE = 0;
+export declare const TRANSCRIBE_TASK_TRANSLATE = 1;
+export declare const TRANSCRIBE_TIMESTAMPS_NONE = 0;
+export declare const TRANSCRIBE_TIMESTAMPS_AUTO = 1;
+export declare const TRANSCRIBE_TIMESTAMPS_SEGMENT = 2;
+export declare const TRANSCRIBE_TIMESTAMPS_WORD = 3;
+export declare const TRANSCRIBE_TIMESTAMPS_TOKEN = 4;
+export declare const TRANSCRIBE_KV_TYPE_AUTO = 0;
+export declare const TRANSCRIBE_KV_TYPE_F32 = 1;
+export declare const TRANSCRIBE_KV_TYPE_F16 = 2;
+export declare const TRANSCRIBE_PNC_MODE_DEFAULT = 0;
+export declare const TRANSCRIBE_PNC_MODE_OFF = 1;
+export declare const TRANSCRIBE_PNC_MODE_ON = 2;
+export declare const TRANSCRIBE_ITN_MODE_DEFAULT = 0;
+export declare const TRANSCRIBE_ITN_MODE_OFF = 1;
+export declare const TRANSCRIBE_ITN_MODE_ON = 2;
+export declare const TRANSCRIBE_EXT_SLOT_RUN = 0;
+export declare const TRANSCRIBE_EXT_SLOT_STREAM = 1;
+export declare const TRANSCRIBE_BACKEND_AUTO = 0;
+export declare const TRANSCRIBE_BACKEND_CPU = 1;
+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_FEATURE_INITIAL_PROMPT = 0;
+export declare const TRANSCRIBE_FEATURE_TEMPERATURE_FALLBACK = 1;
+export declare const TRANSCRIBE_FEATURE_LONG_FORM = 2;
+export declare const TRANSCRIBE_FEATURE_CANCELLATION = 3;
+export declare const TRANSCRIBE_FEATURE_PNC = 4;
+export declare const TRANSCRIBE_FEATURE_ITN = 5;
+export declare const TRANSCRIBE_STREAM_IDLE = 0;
+export declare const TRANSCRIBE_STREAM_ACTIVE = 1;
+export declare const TRANSCRIBE_STREAM_FINISHED = 2;
+export declare const TRANSCRIBE_STREAM_FAILED = 3;
+export declare const TRANSCRIBE_STREAM_COMMIT_AUTO = 0;
+export declare const TRANSCRIBE_STREAM_COMMIT_ON_FINALIZE = 1;
+export declare const TRANSCRIBE_STREAM_COMMIT_STABLE_PREFIX = 2;
+export declare const TRANSCRIBE_WHISPER_PROMPT_FIRST_SEGMENT = 0;
+export declare const TRANSCRIBE_WHISPER_PROMPT_ALL_SEGMENTS = 1;
+export declare const TRANSCRIBE_EXT_KIND_MOONSHINE_STREAMING_STREAM = 1414746957;
+export declare const TRANSCRIBE_EXT_KIND_PARAKEET_BUFFERED_STREAM = 1396853584;
+export declare const TRANSCRIBE_EXT_KIND_PARAKEET_STREAM = 1414744912;
+export declare const TRANSCRIBE_EXT_KIND_VOXTRAL_REALTIME_STREAM = 1414746710;
+export declare const TRANSCRIBE_EXT_KIND_WHISPER_RUN = 1314015319;
+export interface StructLayout {
+    size: number;
+    align: number;
+    offsets: Record<string, number>;
+}
+export declare const STRUCT_LAYOUT: Record<string, StructLayout>;
+export declare const ABI_STRUCT_IDS: Record<string, number>;
+export declare function defineTypes(koffi: any): Record<string, any>;
+export interface FnSig {
+    ret: string;
+    args: string[];
+}
+export declare const FUNCTION_SIGNATURES: Record<string, FnSig>;

package/dist/_generated.js

@@ -0,0 +1,251 @@
+// Low-level koffi FFI surface for transcribe.cpp — AUTOGENERATED. DO NOT EDIT.
+//
+// Regenerate with:
+//   uv run --no-project --with 'libclang==18.1.1' \
+//     bindings/python/_generate/generate.py
+//
+// Source: include/transcribe/extensions.h
+// libclang: 18.1.1
+/* eslint-disable */
+// 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";
+// === enum constants ===
+export const TRANSCRIBE_OK = 0;
+export const TRANSCRIBE_ERR_INVALID_ARG = 1;
+export const TRANSCRIBE_ERR_NOT_IMPLEMENTED = 2;
+export const TRANSCRIBE_ERR_FILE_NOT_FOUND = 3;
+export const TRANSCRIBE_ERR_GGUF = 4;
+export const TRANSCRIBE_ERR_UNSUPPORTED_ARCH = 5;
+export const TRANSCRIBE_ERR_UNSUPPORTED_VARIANT = 6;
+export const TRANSCRIBE_ERR_OOM = 7;
+export const TRANSCRIBE_ERR_BACKEND = 8;
+export const TRANSCRIBE_ERR_SAMPLE_RATE = 9;
+export const TRANSCRIBE_ERR_UNSUPPORTED_LANGUAGE = 10;
+export const TRANSCRIBE_ERR_UNSUPPORTED_TASK = 11;
+export const TRANSCRIBE_ERR_UNSUPPORTED_TIMESTAMPS = 12;
+export const TRANSCRIBE_ERR_ABORTED = 13;
+export const TRANSCRIBE_ERR_BAD_STRUCT_SIZE = 14;
+export const TRANSCRIBE_ERR_UNSUPPORTED_PNC = 15;
+export const TRANSCRIBE_ERR_UNSUPPORTED_ITN = 16;
+export const TRANSCRIBE_ERR_INPUT_TOO_LONG = 17;
+export const TRANSCRIBE_ERR_OUTPUT_TRUNCATED = 18;
+export const TRANSCRIBE_ABI_MODEL_LOAD_PARAMS = 0;
+export const TRANSCRIBE_ABI_SESSION_PARAMS = 1;
+export const TRANSCRIBE_ABI_RUN_PARAMS = 2;
+export const TRANSCRIBE_ABI_STREAM_PARAMS = 3;
+export const TRANSCRIBE_ABI_CAPABILITIES = 4;
+export const TRANSCRIBE_ABI_TIMINGS = 5;
+export const TRANSCRIBE_ABI_SEGMENT = 6;
+export const TRANSCRIBE_ABI_WORD = 7;
+export const TRANSCRIBE_ABI_TOKEN = 8;
+export const TRANSCRIBE_ABI_STREAM_UPDATE = 9;
+export const TRANSCRIBE_ABI_STREAM_TEXT = 10;
+export const TRANSCRIBE_ABI_SESSION_LIMITS = 11;
+export const TRANSCRIBE_ABI_EXT = 12;
+export const TRANSCRIBE_ABI_BACKEND_DEVICE = 13;
+export const TRANSCRIBE_LOG_LEVEL_NONE = 0;
+export const TRANSCRIBE_LOG_LEVEL_INFO = 1;
+export const TRANSCRIBE_LOG_LEVEL_WARN = 2;
+export const TRANSCRIBE_LOG_LEVEL_ERROR = 3;
+export const TRANSCRIBE_LOG_LEVEL_DEBUG = 4;
+export const TRANSCRIBE_LOG_LEVEL_CONT = 5;
+export const TRANSCRIBE_TASK_TRANSCRIBE = 0;
+export const TRANSCRIBE_TASK_TRANSLATE = 1;
+export const TRANSCRIBE_TIMESTAMPS_NONE = 0;
+export const TRANSCRIBE_TIMESTAMPS_AUTO = 1;
+export const TRANSCRIBE_TIMESTAMPS_SEGMENT = 2;
+export const TRANSCRIBE_TIMESTAMPS_WORD = 3;
+export const TRANSCRIBE_TIMESTAMPS_TOKEN = 4;
+export const TRANSCRIBE_KV_TYPE_AUTO = 0;
+export const TRANSCRIBE_KV_TYPE_F32 = 1;
+export const TRANSCRIBE_KV_TYPE_F16 = 2;
+export const TRANSCRIBE_PNC_MODE_DEFAULT = 0;
+export const TRANSCRIBE_PNC_MODE_OFF = 1;
+export const TRANSCRIBE_PNC_MODE_ON = 2;
+export const TRANSCRIBE_ITN_MODE_DEFAULT = 0;
+export const TRANSCRIBE_ITN_MODE_OFF = 1;
+export const TRANSCRIBE_ITN_MODE_ON = 2;
+export const TRANSCRIBE_EXT_SLOT_RUN = 0;
+export const TRANSCRIBE_EXT_SLOT_STREAM = 1;
+export const TRANSCRIBE_BACKEND_AUTO = 0;
+export const TRANSCRIBE_BACKEND_CPU = 1;
+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_FEATURE_INITIAL_PROMPT = 0;
+export const TRANSCRIBE_FEATURE_TEMPERATURE_FALLBACK = 1;
+export const TRANSCRIBE_FEATURE_LONG_FORM = 2;
+export const TRANSCRIBE_FEATURE_CANCELLATION = 3;
+export const TRANSCRIBE_FEATURE_PNC = 4;
+export const TRANSCRIBE_FEATURE_ITN = 5;
+export const TRANSCRIBE_STREAM_IDLE = 0;
+export const TRANSCRIBE_STREAM_ACTIVE = 1;
+export const TRANSCRIBE_STREAM_FINISHED = 2;
+export const TRANSCRIBE_STREAM_FAILED = 3;
+export const TRANSCRIBE_STREAM_COMMIT_AUTO = 0;
+export const TRANSCRIBE_STREAM_COMMIT_ON_FINALIZE = 1;
+export const TRANSCRIBE_STREAM_COMMIT_STABLE_PREFIX = 2;
+export const TRANSCRIBE_WHISPER_PROMPT_FIRST_SEGMENT = 0;
+export const TRANSCRIBE_WHISPER_PROMPT_ALL_SEGMENTS = 1;
+// === macro constants (integer object-like macros) ===
+export const TRANSCRIBE_EXT_KIND_MOONSHINE_STREAMING_STREAM = 1414746957;
+export const TRANSCRIBE_EXT_KIND_PARAKEET_BUFFERED_STREAM = 1396853584;
+export const TRANSCRIBE_EXT_KIND_PARAKEET_STREAM = 1414744912;
+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_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 } },
+    'transcribe_capabilities': { size: 40, align: 8, offsets: { 'struct_size': 0, 'native_sample_rate': 8, 'n_languages': 12, 'languages': 16, 'max_timestamp_kind': 24, 'supports_language_detect': 28, 'supports_translate': 29, 'supports_streaming': 30, 'supports_spec_decode': 31, 'max_audio_ms': 32 } },
+    'transcribe_session_limits': { size: 32, align: 8, offsets: { 'struct_size': 0, 'effective_n_ctx': 8, 'effective_max_audio_ms': 16, 'max_kv_bytes': 24 } },
+    'transcribe_stream_params': { size: 24, align: 8, offsets: { 'struct_size': 0, 'family': 8, 'commit_policy': 16, 'stable_prefix_agreement_n': 20 } },
+    'transcribe_stream_update': { size: 48, align: 8, offsets: { 'struct_size': 0, 'result_changed': 8, 'is_final': 9, 'revision': 12, 'input_received_ms': 16, 'audio_committed_ms': 24, 'buffered_ms': 32, 'committed_changed': 40, 'tentative_changed': 41 } },
+    'transcribe_stream_text': { size: 64, align: 8, offsets: { 'struct_size': 0, 'full_text': 8, 'full_text_bytes': 16, 'committed_text': 24, 'committed_text_bytes': 32, 'tentative_text': 40, 'tentative_text_bytes': 48, 'raw_tentative_start_bytes': 56 } },
+    'transcribe_timings': { size: 24, align: 8, offsets: { 'struct_size': 0, 'load_ms': 8, 'mel_ms': 12, 'encode_ms': 16, 'decode_ms': 20 } },
+    'transcribe_segment': { size: 48, align: 8, offsets: { 'struct_size': 0, 't0_ms': 8, 't1_ms': 16, 'first_word': 24, 'n_words': 28, 'first_token': 32, 'n_tokens': 36, 'text': 40 } },
+    'transcribe_word': { size: 48, align: 8, offsets: { 'struct_size': 0, 't0_ms': 8, 't1_ms': 16, 'seg_index': 24, 'first_token': 28, 'n_tokens': 32, 'text': 40 } },
+    'transcribe_token': { size: 48, align: 8, offsets: { 'struct_size': 0, 'id': 8, 'p': 12, 't0_ms': 16, 't1_ms': 24, 'seg_index': 32, 'word_index': 36, 'text': 40 } },
+    'transcribe_moonshine_streaming_stream_ext': { size: 24, align: 8, offsets: { 'ext': 0, 'min_decode_interval_ms': 16 } },
+    'transcribe_parakeet_stream_ext': { size: 24, align: 8, offsets: { 'ext': 0, 'att_context_right': 16 } },
+    'transcribe_parakeet_buffered_stream_ext': { size: 32, align: 8, offsets: { 'ext': 0, 'left_ms': 16, 'chunk_ms': 20, 'right_ms': 24 } },
+    'transcribe_voxtral_realtime_stream_ext': { size: 24, align: 8, offsets: { 'ext': 0, 'num_delay_tokens': 16, 'min_decode_interval_ms': 20 } },
+    'transcribe_whisper_run_ext': { size: 80, align: 8, offsets: { 'ext': 0, 'initial_prompt': 16, 'prompt_tokens': 24, 'n_prompt_tokens': 32, 'prompt_condition': 40, 'condition_on_prev_tokens': 44, 'max_prev_context_tokens': 48, 'temperature': 52, 'temperature_inc': 56, 'compression_ratio_thold': 60, 'logprob_thold': 64, 'no_speech_thold': 68, 'seed': 72, 'max_initial_timestamp': 76 } },
+    'transcribe_whisper_chunk_trace': { size: 48, align: 8, offsets: { 'struct_size': 0, 't0_ms': 8, 't1_ms': 16, 'temperature_used': 24, 'compression_ratio': 28, 'avg_logprob': 32, 'no_speech_prob': 36, 'no_speech_triggered': 40, 'n_fallbacks': 44 } },
+};
+export const ABI_STRUCT_IDS = {
+    'transcribe_ext': 12,
+    'transcribe_backend_device': 13,
+    'transcribe_model_load_params': 0,
+    'transcribe_session_params': 1,
+    'transcribe_run_params': 2,
+    'transcribe_capabilities': 4,
+    'transcribe_session_limits': 11,
+    'transcribe_stream_params': 3,
+    'transcribe_stream_update': 9,
+    'transcribe_stream_text': 10,
+    'transcribe_timings': 5,
+    'transcribe_segment': 6,
+    'transcribe_word': 7,
+    'transcribe_token': 8,
+};
+// Build koffi struct types; returns a name -> koffi.IKoffiCType map.
+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_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' });
+    T['transcribe_capabilities'] = koffi.struct({ struct_size: 'uint64_t', native_sample_rate: 'int32_t', n_languages: 'int', languages: 'void *', max_timestamp_kind: 'int', supports_language_detect: 'bool', supports_translate: 'bool', supports_streaming: 'bool', supports_spec_decode: 'bool', max_audio_ms: 'int64_t' });
+    T['transcribe_session_limits'] = koffi.struct({ struct_size: 'uint64_t', effective_n_ctx: 'int32_t', effective_max_audio_ms: 'int64_t', max_kv_bytes: 'int64_t' });
+    T['transcribe_stream_params'] = koffi.struct({ struct_size: 'uint64_t', family: 'void *', commit_policy: 'int', stable_prefix_agreement_n: 'uint32_t' });
+    T['transcribe_stream_update'] = koffi.struct({ struct_size: 'uint64_t', result_changed: 'bool', is_final: 'bool', revision: 'int32_t', input_received_ms: 'int64_t', audio_committed_ms: 'int64_t', buffered_ms: 'int64_t', committed_changed: 'bool', tentative_changed: 'bool' });
+    T['transcribe_stream_text'] = koffi.struct({ struct_size: 'uint64_t', full_text: 'char *', full_text_bytes: 'uint64_t', committed_text: 'char *', committed_text_bytes: 'uint64_t', tentative_text: 'char *', tentative_text_bytes: 'uint64_t', raw_tentative_start_bytes: 'uint64_t' });
+    T['transcribe_timings'] = koffi.struct({ struct_size: 'uint64_t', load_ms: 'float', mel_ms: 'float', encode_ms: 'float', decode_ms: 'float' });
+    T['transcribe_segment'] = koffi.struct({ struct_size: 'uint64_t', t0_ms: 'int64_t', t1_ms: 'int64_t', first_word: 'int', n_words: 'int', first_token: 'int', n_tokens: 'int', text: 'char *' });
+    T['transcribe_word'] = koffi.struct({ struct_size: 'uint64_t', t0_ms: 'int64_t', t1_ms: 'int64_t', seg_index: 'int', first_token: 'int', n_tokens: 'int', text: 'char *' });
+    T['transcribe_token'] = koffi.struct({ struct_size: 'uint64_t', id: 'int', p: 'float', t0_ms: 'int64_t', t1_ms: 'int64_t', seg_index: 'int', word_index: 'int', text: 'char *' });
+    T['transcribe_moonshine_streaming_stream_ext'] = koffi.struct({ ext: T['transcribe_ext'], min_decode_interval_ms: 'int32_t' });
+    T['transcribe_parakeet_stream_ext'] = koffi.struct({ ext: T['transcribe_ext'], att_context_right: 'int32_t' });
+    T['transcribe_parakeet_buffered_stream_ext'] = koffi.struct({ ext: T['transcribe_ext'], left_ms: 'int32_t', chunk_ms: 'int32_t', right_ms: 'int32_t' });
+    T['transcribe_voxtral_realtime_stream_ext'] = koffi.struct({ ext: T['transcribe_ext'], num_delay_tokens: 'int32_t', min_decode_interval_ms: 'int32_t' });
+    T['transcribe_whisper_run_ext'] = koffi.struct({ ext: T['transcribe_ext'], initial_prompt: 'char *', prompt_tokens: 'void *', n_prompt_tokens: 'size_t', prompt_condition: 'int', condition_on_prev_tokens: 'bool', max_prev_context_tokens: 'int32_t', temperature: 'float', temperature_inc: 'float', compression_ratio_thold: 'float', logprob_thold: 'float', no_speech_thold: 'float', seed: 'uint32_t', max_initial_timestamp: 'float' });
+    T['transcribe_whisper_chunk_trace'] = koffi.struct({ struct_size: 'uint64_t', t0_ms: 'int64_t', t1_ms: 'int64_t', temperature_used: 'float', compression_ratio: 'float', avg_logprob: 'float', no_speech_prob: 'float', no_speech_triggered: 'bool', n_fallbacks: 'int32_t' });
+    return T;
+}
+export const FUNCTION_SIGNATURES = {
+    'transcribe_abi_struct_align': { ret: 'size_t', args: ['transcribe_abi_struct'] },
+    'transcribe_abi_struct_size': { ret: 'size_t', args: ['transcribe_abi_struct'] },
+    'transcribe_backend_available': { ret: '_Bool', args: ['transcribe_backend_request'] },
+    'transcribe_backend_device_count': { ret: 'int', args: [] },
+    'transcribe_backend_device_init': { ret: 'void', args: ['struct transcribe_backend_device *'] },
+    'transcribe_batch_detected_language': { ret: 'const char *', args: ['const struct transcribe_session *', 'int'] },
+    'transcribe_batch_full_text': { ret: 'const char *', args: ['const struct transcribe_session *', 'int'] },
+    'transcribe_batch_get_segment': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'int', 'int', 'struct transcribe_segment *'] },
+    'transcribe_batch_get_timings': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'int', 'struct transcribe_timings *'] },
+    'transcribe_batch_get_token': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'int', 'int', 'struct transcribe_token *'] },
+    'transcribe_batch_get_word': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'int', 'int', 'struct transcribe_word *'] },
+    'transcribe_batch_n_results': { ret: 'int', args: ['const struct transcribe_session *'] },
+    'transcribe_batch_n_segments': { ret: 'int', args: ['const struct transcribe_session *', 'int'] },
+    'transcribe_batch_n_tokens': { ret: 'int', args: ['const struct transcribe_session *', 'int'] },
+    'transcribe_batch_n_words': { ret: 'int', args: ['const struct transcribe_session *', 'int'] },
+    'transcribe_batch_returned_timestamp_kind': { ret: 'transcribe_timestamp_kind', args: ['const struct transcribe_session *', 'int'] },
+    'transcribe_batch_status': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'int'] },
+    'transcribe_capabilities_init': { ret: 'void', args: ['struct transcribe_capabilities *'] },
+    'transcribe_close': { ret: 'void', args: ['struct transcribe_session *'] },
+    'transcribe_detected_language': { ret: 'const char *', args: ['const struct transcribe_session *'] },
+    'transcribe_ext_check': { ret: 'transcribe_status', args: ['const struct transcribe_ext *', 'uint32_t', 'uint64_t'] },
+    'transcribe_full_text': { ret: 'const char *', args: ['const struct transcribe_session *'] },
+    'transcribe_get_backend_device': { ret: 'transcribe_status', args: ['int', 'struct transcribe_backend_device *'] },
+    'transcribe_get_model': { ret: 'const struct transcribe_model *', args: ['const struct transcribe_session *'] },
+    'transcribe_get_segment': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'int', 'struct transcribe_segment *'] },
+    'transcribe_get_timings': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'struct transcribe_timings *'] },
+    'transcribe_get_token': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'int', 'struct transcribe_token *'] },
+    'transcribe_get_whisper_chunk_count': { ret: 'int', args: ['const struct transcribe_session *'] },
+    'transcribe_get_whisper_chunk_trace': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'int', 'struct transcribe_whisper_chunk_trace *'] },
+    'transcribe_get_word': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'int', 'struct transcribe_word *'] },
+    'transcribe_init_backends': { ret: 'transcribe_status', args: ['const char *'] },
+    'transcribe_init_backends_default': { ret: 'transcribe_status', args: [] },
+    'transcribe_log_set': { ret: 'void', args: ['transcribe_log_callback', 'void *'] },
+    'transcribe_model_accepts_ext_kind': { ret: '_Bool', args: ['const struct transcribe_model *', 'transcribe_ext_slot', 'uint32_t'] },
+    'transcribe_model_arch_string': { ret: 'const char *', args: ['const struct transcribe_model *'] },
+    '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_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'] },
+    'transcribe_model_variant_string': { ret: 'const char *', args: ['const struct transcribe_model *'] },
+    'transcribe_moonshine_streaming_stream_ext_init': { ret: 'void', args: ['struct transcribe_moonshine_streaming_stream_ext *'] },
+    'transcribe_n_segments': { ret: 'int', args: ['const struct transcribe_session *'] },
+    'transcribe_n_tokens': { ret: 'int', args: ['const struct transcribe_session *'] },
+    'transcribe_n_words': { ret: 'int', args: ['const struct transcribe_session *'] },
+    'transcribe_open': { ret: 'transcribe_status', args: ['const char *', 'const struct transcribe_model_load_params *', 'const struct transcribe_session_params *', 'struct transcribe_session **'] },
+    'transcribe_parakeet_buffered_stream_ext_init': { ret: 'void', args: ['struct transcribe_parakeet_buffered_stream_ext *'] },
+    'transcribe_parakeet_stream_ext_init': { ret: 'void', args: ['struct transcribe_parakeet_stream_ext *'] },
+    'transcribe_print_timings': { ret: 'void', args: ['const struct transcribe_session *'] },
+    'transcribe_reset_timings': { ret: 'void', args: ['struct transcribe_session *'] },
+    'transcribe_returned_timestamp_kind': { ret: 'transcribe_timestamp_kind', args: ['const struct transcribe_session *'] },
+    'transcribe_run': { ret: 'transcribe_status', args: ['struct transcribe_session *', 'const float *', 'int', 'const struct transcribe_run_params *'] },
+    'transcribe_run_batch': { ret: 'transcribe_status', args: ['struct transcribe_session *', 'const float *const *', 'const int *', 'int', 'const struct transcribe_run_params *'] },
+    'transcribe_run_params_init': { ret: 'void', args: ['struct transcribe_run_params *'] },
+    'transcribe_segment_init': { ret: 'void', args: ['struct transcribe_segment *'] },
+    'transcribe_session_free': { ret: 'void', args: ['struct transcribe_session *'] },
+    'transcribe_session_get_limits': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'struct transcribe_session_limits *'] },
+    'transcribe_session_init': { ret: 'transcribe_status', args: ['struct transcribe_model *', 'const struct transcribe_session_params *', 'struct transcribe_session **'] },
+    'transcribe_session_limits_init': { ret: 'void', args: ['struct transcribe_session_limits *'] },
+    'transcribe_session_params_init': { ret: 'void', args: ['struct transcribe_session_params *'] },
+    'transcribe_set_abort_callback': { ret: 'void', args: ['struct transcribe_session *', 'transcribe_abort_callback', 'void *'] },
+    'transcribe_status_string': { ret: 'const char *', args: ['int'] },
+    'transcribe_stream_begin': { ret: 'transcribe_status', args: ['struct transcribe_session *', 'const struct transcribe_run_params *', 'const struct transcribe_stream_params *'] },
+    'transcribe_stream_feed': { ret: 'transcribe_status', args: ['struct transcribe_session *', 'const float *', 'int', 'struct transcribe_stream_update *'] },
+    'transcribe_stream_finalize': { ret: 'transcribe_status', args: ['struct transcribe_session *', 'struct transcribe_stream_update *'] },
+    'transcribe_stream_get_state': { ret: 'enum transcribe_stream_state', args: ['const struct transcribe_session *'] },
+    'transcribe_stream_get_text': { ret: 'transcribe_status', args: ['const struct transcribe_session *', 'struct transcribe_stream_text *'] },
+    'transcribe_stream_last_status': { ret: 'transcribe_status', args: ['const struct transcribe_session *'] },
+    'transcribe_stream_n_committed_segments': { ret: 'int', args: ['const struct transcribe_session *'] },
+    'transcribe_stream_n_committed_tokens': { ret: 'int', args: ['const struct transcribe_session *'] },
+    'transcribe_stream_n_committed_words': { ret: 'int', args: ['const struct transcribe_session *'] },
+    'transcribe_stream_params_init': { ret: 'void', args: ['struct transcribe_stream_params *'] },
+    'transcribe_stream_reset': { ret: 'void', args: ['struct transcribe_session *'] },
+    'transcribe_stream_revision': { ret: 'int', args: ['const struct transcribe_session *'] },
+    'transcribe_stream_text_init': { ret: 'void', args: ['struct transcribe_stream_text *'] },
+    'transcribe_stream_update_init': { ret: 'void', args: ['struct transcribe_stream_update *'] },
+    'transcribe_timings_init': { ret: 'void', args: ['struct transcribe_timings *'] },
+    'transcribe_token_init': { ret: 'void', args: ['struct transcribe_token *'] },
+    'transcribe_tokenize': { ret: 'int', args: ['const struct transcribe_model *', 'const char *', 'int32_t *', 'size_t'] },
+    'transcribe_version': { ret: 'const char *', args: [] },
+    'transcribe_version_commit': { ret: 'const char *', args: [] },
+    'transcribe_voxtral_realtime_stream_ext_init': { ret: 'void', args: ['struct transcribe_voxtral_realtime_stream_ext *'] },
+    'transcribe_was_aborted': { ret: '_Bool', args: ['const struct transcribe_session *'] },
+    'transcribe_was_truncated': { ret: '_Bool', args: ['const struct transcribe_session *'] },
+    'transcribe_whisper_chunk_trace_init': { ret: 'void', args: ['struct transcribe_whisper_chunk_trace *'] },
+    'transcribe_whisper_run_ext_init': { ret: 'void', args: ['struct transcribe_whisper_run_ext *'] },
+    'transcribe_word_init': { ret: 'void', args: ['struct transcribe_word *'] },
+};

package/dist/abi.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Load-time ABI verification. TypeScript has no C compiler to check struct
+ * layout at build time (unlike Rust/Swift), so — like the Python ctypes
+ * binding — we verify the generated layout twice before constructing anything:
+ *
+ *   1. self-check: koffi's computed size/align/offsets vs the layout the C
+ *      compiler captured at generation time (STRUCT_LAYOUT).
+ *   2. native-agreement: koffi's size/align vs the loaded library via
+ *      transcribe_abi_struct_size/_align (catches a binding/library skew).
+ */
+import type { Bound } from "./ffi.js";
+export declare function verifyLayouts({ koffi, T, F }: Bound): void;

package/dist/abi.js

@@ -0,0 +1,55 @@
+/**
+ * Load-time ABI verification. TypeScript has no C compiler to check struct
+ * layout at build time (unlike Rust/Swift), so — like the Python ctypes
+ * binding — we verify the generated layout twice before constructing anything:
+ *
+ *   1. self-check: koffi's computed size/align/offsets vs the layout the C
+ *      compiler captured at generation time (STRUCT_LAYOUT).
+ *   2. native-agreement: koffi's size/align vs the loaded library via
+ *      transcribe_abi_struct_size/_align (catches a binding/library skew).
+ */
+import { ABI_STRUCT_IDS, STRUCT_LAYOUT } from "./_generated.js";
+import * as g from "./_generated.js";
+import { AbiError } from "./errors.js";
+export function verifyLayouts({ koffi, T, F }) {
+    const mismatches = [];
+    for (const [name, lo] of Object.entries(STRUCT_LAYOUT)) {
+        const type = T[name];
+        if (!type)
+            continue;
+        const size = koffi.sizeof(type);
+        const align = koffi.alignof(type);
+        if (size !== lo.size)
+            mismatches.push(`${name}: size ${size} != captured ${lo.size}`);
+        if (align !== lo.align)
+            mismatches.push(`${name}: align ${align} != captured ${lo.align}`);
+        for (const [field, off] of Object.entries(lo.offsets)) {
+            const actual = koffi.offsetof(type, field);
+            if (actual !== off) {
+                mismatches.push(`${name}.${field}: offset ${actual} != captured ${off}`);
+            }
+        }
+    }
+    for (const [name, id] of Object.entries(ABI_STRUCT_IDS)) {
+        const type = T[name];
+        if (!type)
+            continue;
+        const nativeSize = Number(F.abiStructSize(id));
+        const nativeAlign = Number(F.abiStructAlign(id));
+        if (nativeSize === 0) {
+            mismatches.push(`${name}: native size 0 (loaded library is older than this binding)`);
+            continue;
+        }
+        const size = koffi.sizeof(type);
+        const align = koffi.alignof(type);
+        if (size !== nativeSize)
+            mismatches.push(`${name}: size ${size} != native ${nativeSize}`);
+        if (align !== nativeAlign)
+            mismatches.push(`${name}: align ${align} != native ${nativeAlign}`);
+    }
+    if (mismatches.length) {
+        throw new AbiError("transcribe_cpp ABI layout check failed — this is a version/build skew between the " +
+            "binding and the native library:\n  " +
+            mismatches.join("\n  "), g.TRANSCRIBE_ERR_BAD_STRUCT_SIZE);
+    }
+}