transcribe-cpp 0.0.0 → 0.0.3

package/dist/errors.d.ts

@@ -0,0 +1,49 @@
+/** Error hierarchy mapped from `transcribe_status`. Mirrors the Python binding. */
+import type { TranscriptionResult } from "./types.js";
+export declare class TranscribeError extends Error {
+    /** The `transcribe_status` value (0 for binding-side errors). */
+    readonly status: number;
+    /** Set on per-utterance failures from a batch run. */
+    utteranceIndex?: number;
+    /** Any partial transcript recovered before the error (set on Aborted / OutputTruncated). */
+    partialResult?: TranscriptionResult;
+    constructor(message: string, status?: number);
+}
+export declare class InvalidArgument extends TranscribeError {
+}
+export declare class NotImplementedByModel extends TranscribeError {
+}
+/**
+ * Raised when another compute already occupies the model. The C library allows
+ * at most one run / batch / active stream in flight per model across ALL of its
+ * sessions (transcribe.h); a sibling op while a stream is active is refused with
+ * this rather than allowed to race. Binding-side error, so `status` is 0.
+ */
+export declare class Busy extends TranscribeError {
+}
+export declare class ModelFileNotFound extends TranscribeError {
+}
+export declare class ModelLoadError extends TranscribeError {
+}
+export declare class OutOfMemory extends TranscribeError {
+}
+export declare class BackendError extends TranscribeError {
+}
+export declare class UnsupportedRequest extends TranscribeError {
+}
+export declare class AbiError extends TranscribeError {
+}
+export declare class InputTooLong extends TranscribeError {
+}
+export declare class VersionMismatch extends TranscribeError {
+}
+/** Raised when a run is cancelled; carries any partial transcript in `partialResult`. */
+export declare class Aborted extends TranscribeError {
+}
+/** Raised when decode hits the context/generation cap; carries the partial in `partialResult`. */
+export declare class OutputTruncated extends TranscribeError {
+}
+/** Build (do not throw) the mapped exception for a status. */
+export declare function exceptionForStatus(status: number, statusString: string, context?: string): TranscribeError;
+/** Throw the mapped exception unless the status is OK. */
+export declare function raiseForStatus(status: number, statusString: string, context?: string): void;

package/dist/errors.js

@@ -0,0 +1,83 @@
+/** Error hierarchy mapped from `transcribe_status`. Mirrors the Python binding. */
+import * as g from "./_generated.js";
+export class TranscribeError extends Error {
+    /** The `transcribe_status` value (0 for binding-side errors). */
+    status;
+    /** Set on per-utterance failures from a batch run. */
+    utteranceIndex;
+    /** Any partial transcript recovered before the error (set on Aborted / OutputTruncated). */
+    partialResult;
+    constructor(message, status = g.TRANSCRIBE_OK) {
+        super(message);
+        this.name = new.target.name;
+        this.status = status;
+    }
+}
+export class InvalidArgument extends TranscribeError {
+}
+export class NotImplementedByModel extends TranscribeError {
+}
+/**
+ * Raised when another compute already occupies the model. The C library allows
+ * at most one run / batch / active stream in flight per model across ALL of its
+ * sessions (transcribe.h); a sibling op while a stream is active is refused with
+ * this rather than allowed to race. Binding-side error, so `status` is 0.
+ */
+export class Busy extends TranscribeError {
+}
+export class ModelFileNotFound extends TranscribeError {
+}
+export class ModelLoadError extends TranscribeError {
+}
+export class OutOfMemory extends TranscribeError {
+}
+export class BackendError extends TranscribeError {
+}
+export class UnsupportedRequest extends TranscribeError {
+}
+export class AbiError extends TranscribeError {
+}
+export class InputTooLong extends TranscribeError {
+}
+export class VersionMismatch extends TranscribeError {
+}
+/** Raised when a run is cancelled; carries any partial transcript in `partialResult`. */
+export class Aborted extends TranscribeError {
+}
+/** Raised when decode hits the context/generation cap; carries the partial in `partialResult`. */
+export class OutputTruncated extends TranscribeError {
+}
+const STATUS_TO_EXC = {
+    [g.TRANSCRIBE_ERR_INVALID_ARG]: InvalidArgument,
+    [g.TRANSCRIBE_ERR_NOT_IMPLEMENTED]: NotImplementedByModel,
+    [g.TRANSCRIBE_ERR_FILE_NOT_FOUND]: ModelFileNotFound,
+    [g.TRANSCRIBE_ERR_GGUF]: ModelLoadError,
+    [g.TRANSCRIBE_ERR_UNSUPPORTED_ARCH]: ModelLoadError,
+    [g.TRANSCRIBE_ERR_UNSUPPORTED_VARIANT]: ModelLoadError,
+    [g.TRANSCRIBE_ERR_OOM]: OutOfMemory,
+    [g.TRANSCRIBE_ERR_BACKEND]: BackendError,
+    [g.TRANSCRIBE_ERR_SAMPLE_RATE]: InvalidArgument,
+    [g.TRANSCRIBE_ERR_UNSUPPORTED_LANGUAGE]: UnsupportedRequest,
+    [g.TRANSCRIBE_ERR_UNSUPPORTED_TASK]: UnsupportedRequest,
+    [g.TRANSCRIBE_ERR_UNSUPPORTED_TIMESTAMPS]: UnsupportedRequest,
+    [g.TRANSCRIBE_ERR_ABORTED]: Aborted,
+    [g.TRANSCRIBE_ERR_BAD_STRUCT_SIZE]: AbiError,
+    [g.TRANSCRIBE_ERR_UNSUPPORTED_PNC]: UnsupportedRequest,
+    [g.TRANSCRIBE_ERR_UNSUPPORTED_ITN]: UnsupportedRequest,
+    [g.TRANSCRIBE_ERR_INPUT_TOO_LONG]: InputTooLong,
+    [g.TRANSCRIBE_ERR_OUTPUT_TRUNCATED]: OutputTruncated,
+};
+/** Build (do not throw) the mapped exception for a status. */
+export function exceptionForStatus(status, statusString, context = "") {
+    const Cls = STATUS_TO_EXC[status] ?? TranscribeError;
+    const msg = context
+        ? `${context}: ${statusString} (status ${status})`
+        : `${statusString} (status ${status})`;
+    return new Cls(msg, status);
+}
+/** Throw the mapped exception unless the status is OK. */
+export function raiseForStatus(status, statusString, context = "") {
+    if (status === g.TRANSCRIBE_OK)
+        return;
+    throw exceptionForStatus(status, statusString, context);
+}

package/dist/ffi.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The koffi engine adapter: load the library and hand-bind the C functions
+ * with explicit in/out/inout direction (which a generic generator can't infer).
+ * Struct *layouts* come from the generated `defineTypes`; the drift gate covers
+ * signature changes via the pinned PUBLIC_HEADER_HASH.
+ *
+ * This is the one runtime-specific seam. A Bun/Deno adapter would re-implement
+ * this file against the same generated types and the same public shape.
+ */
+import koffi from "koffi";
+export interface Bound {
+    koffi: typeof koffi;
+    lib: ReturnType<typeof koffi.load>;
+    T: Record<string, any>;
+    F: Record<string, any>;
+}
+export declare function bindLibrary(libraryPath: string): Bound;
+/** koffi proto for the abort callback: `bool (void *userdata)`. */
+export declare function abortProto(): any;
+/** koffi proto for the log callback: `void (int level, const char *msg, void *ud)`. */
+export declare function logProto(): any;

package/dist/ffi.js

@@ -0,0 +1,219 @@
+/**
+ * The koffi engine adapter: load the library and hand-bind the C functions
+ * with explicit in/out/inout direction (which a generic generator can't infer).
+ * Struct *layouts* come from the generated `defineTypes`; the drift gate covers
+ * signature changes via the pinned PUBLIC_HEADER_HASH.
+ *
+ * This is the one runtime-specific seam. A Bun/Deno adapter would re-implement
+ * this file against the same generated types and the same public shape.
+ */
+import koffi from "koffi";
+import { defineTypes } from "./_generated.js";
+export function bindLibrary(libraryPath) {
+    const lib = koffi.load(libraryPath);
+    const T = defineTypes(koffi);
+    const inp = (t) => koffi.pointer(t); // const X * (marshalled in)
+    const outp = (t) => koffi.out(koffi.pointer(t)); // X * pure out (e.g. *_init)
+    // Accessors read struct_size on input then fill the rest: copy in AND back.
+    const iop = (t) => koffi.inout(koffi.pointer(t));
+    const handleOut = koffi.out(koffi.pointer("void *")); // X ** out
+    const F = {
+        // identity / diagnostics
+        version: lib.func("transcribe_version", "str", []),
+        versionCommit: lib.func("transcribe_version_commit", "str", []),
+        statusString: lib.func("transcribe_status_string", "str", ["int"]),
+        abiStructSize: lib.func("transcribe_abi_struct_size", "uint64", ["int"]),
+        abiStructAlign: lib.func("transcribe_abi_struct_align", "uint64", ["int"]),
+        // backends
+        initBackends: lib.func("transcribe_init_backends", "int", ["str"]),
+        initBackendsDefault: lib.func("transcribe_init_backends_default", "int", []),
+        backendDeviceCount: lib.func("transcribe_backend_device_count", "int", []),
+        backendDeviceInit: lib.func("transcribe_backend_device_init", "void", [
+            outp(T.transcribe_backend_device),
+        ]),
+        getBackendDevice: lib.func("transcribe_get_backend_device", "int", [
+            "int",
+            iop(T.transcribe_backend_device),
+        ]),
+        backendAvailable: lib.func("transcribe_backend_available", "bool", ["int"]),
+        // logging (callback pointer comes from koffi.register -> passed as void*)
+        logSet: lib.func("transcribe_log_set", "void", ["void *", "void *"]),
+        // model
+        modelLoadParamsInit: lib.func("transcribe_model_load_params_init", "void", [
+            outp(T.transcribe_model_load_params),
+        ]),
+        modelLoadFile: lib.func("transcribe_model_load_file", "int", [
+            "str",
+            inp(T.transcribe_model_load_params),
+            handleOut,
+        ]),
+        modelFree: lib.func("transcribe_model_free", "void", ["void *"]),
+        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 *"]),
+        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", [
+            outp(T.transcribe_capabilities),
+        ]),
+        modelGetCapabilities: lib.func("transcribe_model_get_capabilities", "int", [
+            "void *",
+            iop(T.transcribe_capabilities),
+        ]),
+        // session
+        sessionParamsInit: lib.func("transcribe_session_params_init", "void", [
+            outp(T.transcribe_session_params),
+        ]),
+        sessionInit: lib.func("transcribe_session_init", "int", [
+            "void *",
+            inp(T.transcribe_session_params),
+            handleOut,
+        ]),
+        sessionFree: lib.func("transcribe_session_free", "void", ["void *"]),
+        sessionLimitsInit: lib.func("transcribe_session_limits_init", "void", [
+            outp(T.transcribe_session_limits),
+        ]),
+        sessionGetLimits: lib.func("transcribe_session_get_limits", "int", [
+            "void *",
+            iop(T.transcribe_session_limits),
+        ]),
+        setAbortCallback: lib.func("transcribe_set_abort_callback", "void", [
+            "void *",
+            "void *",
+            "void *",
+        ]),
+        wasAborted: lib.func("transcribe_was_aborted", "bool", ["void *"]),
+        wasTruncated: lib.func("transcribe_was_truncated", "bool", ["void *"]),
+        // run (offline) + result accessors
+        runParamsInit: lib.func("transcribe_run_params_init", "void", [
+            outp(T.transcribe_run_params),
+        ]),
+        run: lib.func("transcribe_run", "int", [
+            "void *",
+            inp("float"),
+            "int",
+            inp(T.transcribe_run_params),
+        ]),
+        fullText: lib.func("transcribe_full_text", "str", ["void *"]),
+        detectedLanguage: lib.func("transcribe_detected_language", "str", ["void *"]),
+        returnedTimestampKind: lib.func("transcribe_returned_timestamp_kind", "int", ["void *"]),
+        nSegments: lib.func("transcribe_n_segments", "int", ["void *"]),
+        nWords: lib.func("transcribe_n_words", "int", ["void *"]),
+        nTokens: lib.func("transcribe_n_tokens", "int", ["void *"]),
+        segmentInit: lib.func("transcribe_segment_init", "void", [outp(T.transcribe_segment)]),
+        wordInit: lib.func("transcribe_word_init", "void", [outp(T.transcribe_word)]),
+        tokenInit: lib.func("transcribe_token_init", "void", [outp(T.transcribe_token)]),
+        getSegment: lib.func("transcribe_get_segment", "int", [
+            "void *",
+            "int",
+            iop(T.transcribe_segment),
+        ]),
+        getWord: lib.func("transcribe_get_word", "int", ["void *", "int", iop(T.transcribe_word)]),
+        getToken: lib.func("transcribe_get_token", "int", ["void *", "int", iop(T.transcribe_token)]),
+        timingsInit: lib.func("transcribe_timings_init", "void", [outp(T.transcribe_timings)]),
+        getTimings: lib.func("transcribe_get_timings", "int", ["void *", iop(T.transcribe_timings)]),
+        // family extensions
+        modelAcceptsExtKind: lib.func("transcribe_model_accepts_ext_kind", "bool", [
+            "void *",
+            "int",
+            "uint32",
+        ]),
+        whisperRunExtInit: lib.func("transcribe_whisper_run_ext_init", "void", [
+            outp(T.transcribe_whisper_run_ext),
+        ]),
+        moonshineStreamingStreamExtInit: lib.func("transcribe_moonshine_streaming_stream_ext_init", "void", [outp(T.transcribe_moonshine_streaming_stream_ext)]),
+        parakeetStreamExtInit: lib.func("transcribe_parakeet_stream_ext_init", "void", [
+            outp(T.transcribe_parakeet_stream_ext),
+        ]),
+        parakeetBufferedStreamExtInit: lib.func("transcribe_parakeet_buffered_stream_ext_init", "void", [
+            outp(T.transcribe_parakeet_buffered_stream_ext),
+        ]),
+        voxtralRealtimeStreamExtInit: lib.func("transcribe_voxtral_realtime_stream_ext_init", "void", [
+            outp(T.transcribe_voxtral_realtime_stream_ext),
+        ]),
+        // batch (offline)
+        runBatch: lib.func("transcribe_run_batch", "int", [
+            "void *",
+            "float **",
+            "int *",
+            "int",
+            inp(T.transcribe_run_params),
+        ]),
+        batchNResults: lib.func("transcribe_batch_n_results", "int", ["void *"]),
+        batchStatus: lib.func("transcribe_batch_status", "int", ["void *", "int"]),
+        batchNSegments: lib.func("transcribe_batch_n_segments", "int", ["void *", "int"]),
+        batchGetSegment: lib.func("transcribe_batch_get_segment", "int", [
+            "void *",
+            "int",
+            "int",
+            iop(T.transcribe_segment),
+        ]),
+        batchNWords: lib.func("transcribe_batch_n_words", "int", ["void *", "int"]),
+        batchGetWord: lib.func("transcribe_batch_get_word", "int", [
+            "void *",
+            "int",
+            "int",
+            iop(T.transcribe_word),
+        ]),
+        batchNTokens: lib.func("transcribe_batch_n_tokens", "int", ["void *", "int"]),
+        batchGetToken: lib.func("transcribe_batch_get_token", "int", [
+            "void *",
+            "int",
+            "int",
+            iop(T.transcribe_token),
+        ]),
+        batchFullText: lib.func("transcribe_batch_full_text", "str", ["void *", "int"]),
+        batchDetectedLanguage: lib.func("transcribe_batch_detected_language", "str", ["void *", "int"]),
+        batchReturnedTimestampKind: lib.func("transcribe_batch_returned_timestamp_kind", "int", [
+            "void *",
+            "int",
+        ]),
+        batchGetTimings: lib.func("transcribe_batch_get_timings", "int", [
+            "void *",
+            "int",
+            iop(T.transcribe_timings),
+        ]),
+        // streaming
+        streamParamsInit: lib.func("transcribe_stream_params_init", "void", [
+            outp(T.transcribe_stream_params),
+        ]),
+        streamUpdateInit: lib.func("transcribe_stream_update_init", "void", [
+            outp(T.transcribe_stream_update),
+        ]),
+        streamTextInit: lib.func("transcribe_stream_text_init", "void", [outp(T.transcribe_stream_text)]),
+        streamBegin: lib.func("transcribe_stream_begin", "int", [
+            "void *",
+            inp(T.transcribe_run_params),
+            inp(T.transcribe_stream_params),
+        ]),
+        streamFeed: lib.func("transcribe_stream_feed", "int", [
+            "void *",
+            inp("float"),
+            "int",
+            iop(T.transcribe_stream_update),
+        ]),
+        streamFinalize: lib.func("transcribe_stream_finalize", "int", [
+            "void *",
+            iop(T.transcribe_stream_update),
+        ]),
+        streamGetText: lib.func("transcribe_stream_get_text", "int", [
+            "void *",
+            iop(T.transcribe_stream_text),
+        ]),
+        streamReset: lib.func("transcribe_stream_reset", "void", ["void *"]),
+        streamGetState: lib.func("transcribe_stream_get_state", "int", ["void *"]),
+        streamRevision: lib.func("transcribe_stream_revision", "int", ["void *"]),
+        streamLastStatus: lib.func("transcribe_stream_last_status", "int", ["void *"]),
+    };
+    return { koffi, lib, T, F };
+}
+let abortProtoType = null;
+let logProtoType = null;
+/** koffi proto for the abort callback: `bool (void *userdata)`. */
+export function abortProto() {
+    return (abortProtoType ??= koffi.proto("bool TranscribeAbortCb(void *udata)"));
+}
+/** koffi proto for the log callback: `void (int level, const char *msg, void *ud)`. */
+export function logProto() {
+    return (logProtoType ??= koffi.proto("void TranscribeLogCb(int level, const char *msg, void *udata)"));
+}

package/dist/index.d.ts

@@ -1,10 +1,87 @@
 /**
- * TypeScript/Node.js bindings for transcribe.cpp.
+ * transcribe.cpp — TypeScript/Node.js bindings.
  *
- * This is a placeholder package that reserves the `transcribe-cpp` name on npm
- * while first-party bindings are developed. It ships no functionality yet.
- *
- * @see https://github.com/handy-computer/transcribe.cpp
+ * A koffi FFI binding over the shared native library: offline transcription and
+ * batch, streaming with committed/tentative text, typed per-family extensions,
+ * backend discovery, log routing, and cooperative cancellation.
  */
-/** Version of this placeholder package. */
-export declare const version = "0.0.0";
+import { setLogHandler, type LogHandler } from "./native.js";
+import { TranscribeError } from "./errors.js";
+import type { Backend, BackendInfo, BatchItem, Capabilities, FamilyExtension, Feature, ModelOptions, PcmLike, SessionLimits, SessionOptions, StreamOptions, StreamState, StreamText, StreamUpdate, TranscribeOptions, TranscriptionResult } from "./types.js";
+export * from "./types.js";
+export * from "./errors.js";
+export { setLogHandler, type LogHandler };
+export declare function version(): {
+    version: string;
+    commit: string;
+    headerHash: string;
+};
+export declare function libraryPath(): string;
+export declare function getAvailableBackends(): BackendInfo[];
+export declare function backendAvailable(backend: Backend): boolean;
+export declare class Session {
+    #private;
+    get limits(): SessionLimits;
+    /**
+     * Transcribe one clip. The input PCM is borrowed, not copied: native code
+     * reads it on a worker thread while this runs, so do not mutate the buffer
+     * (e.g. reuse a scratch array) until the returned promise resolves.
+     */
+    run(pcm: PcmLike, opts?: TranscribeOptions): Promise<TranscriptionResult>;
+    /**
+     * Offline batch transcription; each item carries its own success/failure.
+     * Inputs are borrowed, not copied: native code reads them on a worker thread
+     * while this runs, so do not mutate them until the returned promise resolves.
+     */
+    runBatch(pcms: PcmLike[], opts?: TranscribeOptions): Promise<BatchItem[]>;
+    /** Begin a streaming session. The returned Stream owns the begin params. */
+    stream(opts?: StreamOptions): Promise<Stream>;
+    get wasAborted(): boolean;
+    dispose(): void;
+    [Symbol.dispose](): void;
+}
+export declare class Stream {
+    #private;
+    /**
+     * Feed one chunk of PCM; returns the update snapshot. The chunk is borrowed,
+     * not copied: native code reads it on a worker thread while the feed runs, so
+     * do not mutate it (e.g. reuse a capture buffer) until the promise resolves.
+     */
+    feed(pcm: PcmLike): Promise<StreamUpdate>;
+    /** Flush remaining audio and commit the final text. */
+    finalize(): Promise<StreamUpdate>;
+    /** Current text snapshot (copied at the boundary). */
+    get text(): StreamText;
+    get state(): StreamState;
+    get revision(): number;
+    /**
+     * The stream's recorded terminal failure, or `null` while it is healthy. Set
+     * after a feed()/finalize() transitions the stream to `"failed"`; reset by a
+     * new stream. Inspect it when `state === "failed"`.
+     */
+    get lastStatus(): TranscribeError | null;
+    /** End the stream and return the session to idle. Idempotent. */
+    reset(): void;
+    [Symbol.dispose](): void;
+}
+export declare class TranscribeModel {
+    #private;
+    private constructor();
+    static load(path: string, opts?: ModelOptions): Promise<TranscribeModel>;
+    createSession(opts?: SessionOptions): Session;
+    /** Convenience: one session, one run, disposed after. */
+    transcribe(pcm: PcmLike, opts?: TranscribeOptions): Promise<TranscriptionResult>;
+    get capabilities(): Capabilities;
+    supports(feature: Feature): boolean;
+    /** Whether this model accepts the given family extension on its slot. */
+    accepts(family: FamilyExtension): boolean;
+    /** Tokenize plain UTF-8 text into the model's vocabulary (no special tokens). */
+    tokenize(text: string): Int32Array;
+    get arch(): string;
+    get variant(): string;
+    get backend(): string;
+    dispose(): void;
+    [Symbol.dispose](): void;
+}
+/** One-shot: load (or reuse) a model, transcribe, return the result. */
+export declare function transcribe(model: TranscribeModel | string, pcm: PcmLike, opts?: TranscribeOptions & ModelOptions): Promise<TranscriptionResult>;