@qvac/sdk 0.9.2 → 0.10.1

package/dist/client/api/transcribe.d.ts

@@ -1,14 +1,22 @@
-import { type TranscribeClientParams, type RPCOptions, type TranscribeStreamClientParams, type TranscribeStreamSession } from "../../schemas/index";
+import { type TranscribeClientParams, type RPCOptions, type TranscribeSegment, type TranscribeStreamClientParams, type TranscribeStreamSession, type TranscribeStreamMetadataSession } from "../../schemas/index";
 /**
  * Transcribe audio and return the complete text. Accepts either a file
  * path or an audio buffer.
  *
+ * @param params - Transcription parameters.
  * @param params.modelId - The identifier of the transcription model to use
  * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
  * @param params.prompt - Optional initial prompt to guide the transcription
+ * @param params.metadata - When true, resolves to an array of transcript
+ *                          segments (`{ text, startMs, endMs, append, id }`)
+ *                          instead of joined text. Whisper engine only.
  * @param options - Optional RPC options including per-call profiling
- * @returns The complete transcribed text
+ * @returns The complete transcribed text, or — when `metadata` is true —
+ *          the list of transcript segments in emission order.
  */
+export declare function transcribe(params: TranscribeClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<TranscribeSegment[]>;
 export declare function transcribe(params: TranscribeClientParams, options?: RPCOptions): Promise<string>;
 /**
  * @deprecated Pass audio via `transcribe()` instead. This overload will be
@@ -16,7 +24,15 @@ export declare function transcribe(params: TranscribeClientParams, options?: RPC
  *
  * Streaming transcription with upfront audio: sends full audio, yields text
  * chunks as they arrive.
+ *
+ * @overloadLabel "Upfront audio (deprecated)"
+ * @param params - Transcription parameters including audio source.
+ * @param options - Optional RPC options including per-call profiling.
+ * @returns An async generator yielding text chunks as they become available.
  */
+export declare function transcribeStream(params: TranscribeClientParams & {
+    metadata: true;
+}, options?: RPCOptions): AsyncGenerator<TranscribeSegment>;
 export declare function transcribeStream(params: TranscribeClientParams, options?: RPCOptions): AsyncGenerator<string>;
 /**
  * Opens a bidirectional streaming transcription session. Audio is streamed
@@ -26,11 +42,20 @@ export declare function transcribeStream(params: TranscribeClientParams, options
  * The returned session is single-use. Attempting to iterate a second
  * time will throw a `TranscriptionFailedError`.
  *
+ * @overloadLabel "Bidirectional session"
+ * @param params - Streaming transcription parameters.
  * @param params.modelId - The loaded transcription model to use
  * @param params.prompt - Optional initial prompt to guide transcription
+ * @param params.metadata - When true, the session yields transcript segment
+ *                          objects (`{ text, startMs, endMs, append, id }`)
+ *                          instead of plain text. Whisper engine only.
+ * @param options - Optional RPC options including per-call profiling.
  * @returns A session object: call `write(buffer)` to feed audio,
- *          iterate with `for await (const text of session)` to receive
- *          transcription, and `end()` to signal end of audio.
+ *          iterate with `for await (...)` to receive transcription,
+ *          and `end()` to signal end of audio.
  */
+export declare function transcribeStream(params: TranscribeStreamClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<TranscribeStreamMetadataSession>;
 export declare function transcribeStream(params: TranscribeStreamClientParams, options?: RPCOptions): Promise<TranscribeStreamSession>;
 //# sourceMappingURL=transcribe.d.ts.map

package/dist/client/api/transcribe.js

@@ -11,20 +11,26 @@ function buildTranscribeRequest(params) {
             ? { type: "filePath", value: params.audioChunk }
             : { type: "base64", value: params.audioChunk.toString("base64") },
         ...(params.prompt && { prompt: params.prompt }),
+        ...(params.metadata === true && { metadata: true }),
     };
 }
-/**
- * Transcribe audio and return the complete text. Accepts either a file
- * path or an audio buffer.
- *
- * @param params.modelId - The identifier of the transcription model to use
- * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
- * @param params.prompt - Optional initial prompt to guide the transcription
- * @param options - Optional RPC options including per-call profiling
- * @returns The complete transcribed text
- */
 export async function transcribe(params, options) {
     const request = buildTranscribeRequest(params);
+    if (params.metadata === true) {
+        const segments = [];
+        for await (const response of stream(request, options)) {
+            if (response.type === "transcribe") {
+                const parsed = transcribeResponseSchema.parse(response);
+                if (parsed.segment) {
+                    segments.push(parsed.segment);
+                }
+                if (parsed.done) {
+                    break;
+                }
+            }
+        }
+        return segments;
+    }
     let fullText = "";
     for await (const response of stream(request, options)) {
         if (response.type === "transcribe") {
@@ -42,30 +48,57 @@ export async function transcribe(params, options) {
 export function transcribeStream(params, options) {
     if ("audioChunk" in params && params.audioChunk !== undefined) {
         logger.warn("transcribeStream() with audioChunk is deprecated — use transcribe() instead.");
+        if (params.metadata === true) {
+            return transcribeStreamWithAudioMetadata(params, options);
+        }
         return transcribeStreamWithAudio(params, options);
     }
-    return transcribeStreamDuplex(params, options);
+    const streamParams = params;
+    if (streamParams.metadata === true) {
+        return transcribeStreamDuplexMetadata(streamParams, options);
+    }
+    return transcribeStreamDuplex(streamParams, options);
 }
-async function* transcribeStreamWithAudio(params, options) {
+/**
+ * Streams `transcribe` wire responses for an upfront-audio request and yields
+ * the value extracted from each response frame until `done` is seen.
+ */
+async function* streamTranscribeValues(params, options, extract) {
     const request = buildTranscribeRequest(params);
     for await (const response of stream(request, options)) {
         if (response.type === "transcribe") {
             const parsed = transcribeResponseSchema.parse(response);
-            if (parsed.text)
-                yield parsed.text;
+            const value = extract(parsed);
+            if (value !== undefined)
+                yield value;
             if (parsed.done)
                 break;
         }
     }
 }
-async function transcribeStreamDuplex(params, options) {
-    const request = {
+function transcribeStreamWithAudio(params, options) {
+    return streamTranscribeValues(params, options, (parsed) => parsed.text ? parsed.text : undefined);
+}
+function transcribeStreamWithAudioMetadata(params, options) {
+    return streamTranscribeValues(params, options, (parsed) => parsed.segment);
+}
+function buildTranscribeStreamRequest(params) {
+    return {
         type: "transcribeStream",
         modelId: params.modelId,
         ...(params.prompt && { prompt: params.prompt }),
+        ...(params.metadata === true && { metadata: true }),
     };
+}
+/**
+ * Shared duplex session factory. The per-call line processor decides whether
+ * to surface strings or segments; `sessionName` is only used to label the
+ * "already iterated" error so callers see the correct session type.
+ */
+async function createTranscribeStreamSession(params, options, process, sessionName) {
+    const request = buildTranscribeStreamRequest(params);
     const { requestStream, responseStream } = await duplex(request, options);
-    const responses = parseResponseLines(responseStream);
+    const responses = parseLines(responseStream, process);
     let consumed = false;
     return {
         write(audioChunk) {
@@ -80,21 +113,32 @@ async function transcribeStreamDuplex(params, options) {
         },
         [Symbol.asyncIterator]() {
             if (consumed) {
-                throw new TranscriptionFailedError("TranscribeStreamSession can only be iterated once");
+                throw new TranscriptionFailedError(`${sessionName} can only be iterated once`);
             }
             consumed = true;
             return responses;
         },
     };
 }
-async function* parseResponseLines(responseStream) {
+function transcribeStreamDuplex(params, options) {
+    return createTranscribeStreamSession(params, options, processLine, "TranscribeStreamSession");
+}
+function transcribeStreamDuplexMetadata(params, options) {
+    return createTranscribeStreamSession(params, options, processLineMetadata, "TranscribeStreamMetadataSession");
+}
+/**
+ * Line-delimited parser: reads newline-separated frames from a duplex
+ * response stream, passes each non-empty line through `process`, and yields
+ * whatever values it returns. `null` from `process` terminates the stream.
+ */
+async function* parseLines(responseStream, process) {
     let buf = "";
     for await (const chunk of responseStream) {
         buf += chunk.toString();
         const lines = buf.split("\n");
         buf = lines.pop() || "";
         for (const line of lines) {
-            const result = processLine(line);
+            const result = process(line);
             if (result === null)
                 return;
             if (result !== undefined)
@@ -103,32 +147,46 @@ async function* parseResponseLines(responseStream) {
     }
     // Process any residual data after stream ends
     if (buf.trim()) {
-        const result = processLine(buf);
+        const result = process(buf);
         if (result !== null && result !== undefined)
             yield result;
     }
 }
-function processLine(line) {
+function parseResponseLine(line) {
     if (!line.trim())
-        return undefined;
+        return null;
     let parsed;
     try {
         parsed = JSON.parse(line);
     }
     catch {
         logger.warn("transcribeStream: malformed JSON from server:", line);
-        return undefined;
+        return null;
     }
     const obj = parsed;
     if (obj["type"] === "error") {
         throw new TranscriptionFailedError(obj["message"] ?? "Unknown server error");
     }
-    const response = transcribeStreamResponseSchema.parse(parsed);
+    return transcribeStreamResponseSchema.parse(parsed);
+}
+/**
+ * Shared wire-frame decoder. Returns `null` for the terminal `done` frame,
+ * `undefined` for frames the caller should skip, or the value extracted from
+ * the frame.
+ */
+function processWith(line, extract) {
+    const response = parseResponseLine(line);
+    if (response === null)
+        return undefined;
     if (response.error)
         throw new TranscriptionFailedError(response.error);
     if (response.done)
         return null;
-    if (response.text?.trim())
-        return response.text;
-    return undefined;
+    return extract(response);
+}
+function processLine(line) {
+    return processWith(line, (response) => response.text?.trim() ? response.text : undefined);
+}
+function processLineMetadata(line) {
+    return processWith(line, (response) => response.segment);
 }

package/dist/client/api/translate.d.ts

@@ -9,6 +9,7 @@ import { type TranslateClientParams, type TranslationStats, type RPCOptions } fr
  * @param params.from - Source language code (optional)
  * @param params.to - Target language code
  * @param params.stream - Whether to stream tokens (true) or return complete response (false). Defaults to true.
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @returns Object with tokenStream generator and text/stats properties
  * @throws {QvacErrorBase} When translation fails with an error message or when language detection fails
  * @example

package/dist/client/api/translate.js

@@ -12,6 +12,7 @@ import { TranslationFailedError } from "../../utils/errors-client.js";
  * @param params.from - Source language code (optional)
  * @param params.to - Target language code
  * @param params.stream - Whether to stream tokens (true) or return complete response (false). Defaults to true.
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @returns Object with tokenStream generator and text/stats properties
  * @throws {QvacErrorBase} When translation fails with an error message or when language detection fails
  * @example

package/dist/client/rpc/bare-client.js

@@ -11,7 +11,8 @@ import { resolveModelConfig } from "../../server/bare/registry/model-config-regi
 import { resolveConfig } from "../config-loader/resolve-config.bare.js";
 import { getClientLogger } from "../../logging/index.js";
 import { getAllPlugins } from "../../server/plugins/index.js";
-import { initializeWorkerCore, shutdownBareDirectWorker, } from "../../server/worker-core.js";
+import { initializeWorkerCore, shutdownBareDirectWorker, cleanupForTerminate, } from "../../server/worker-core.js";
+import { assertLifecycleAllowed } from "../../server/bare/runtime-lifecycle.js";
 const logger = getClientLogger();
 /**
  * Load worker entry to register plugins before any SDK calls.
@@ -101,6 +102,7 @@ async function* streamWithProgress(request, handler) {
     }
 }
 export async function send(request) {
+    assertLifecycleAllowed(request);
     const handler = getHandler(request.type);
     if (!handler)
         throw new RPCNoHandlerError(request.type);
@@ -108,6 +110,7 @@ export async function send(request) {
     return (await handler(processedRequest));
 }
 async function* stream(request) {
+    assertLifecycleAllowed(request);
     const handler = getHandler(request.type);
     if (!handler)
         throw new RPCNoHandlerError(request.type);
@@ -160,6 +163,23 @@ function createMockRPCRequest() {
                     }));
                 }
             }
+            // Handle special pre-terminate cleanup signal. In direct mode the
+            // bare runtime is the host JS context, so we run cleanup but never
+            // exit the process here.
+            if (typeof requestData === "object" &&
+                "type" in requestData &&
+                requestData.type === "__shutdown__") {
+                try {
+                    await cleanupForTerminate();
+                    return Buffer.from(JSON.stringify({ success: true }));
+                }
+                catch (error) {
+                    return Buffer.from(JSON.stringify({
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    }));
+                }
+            }
             const response = await send(requestData);
             return Buffer.from(JSON.stringify(response));
         },
@@ -203,6 +223,7 @@ export async function createDuplexSession(payload, _commandId) {
     await getRPC();
     const { PassThrough } = await import("bare-stream");
     const request = JSON.parse(payload);
+    assertLifecycleAllowed(request);
     const entry = registry[request.type];
     if (!entry || entry.type !== "duplex") {
         throw new RPCNoHandlerError(request.type);

package/dist/client/rpc/expo-rpc-client.d.ts

@@ -1,6 +1,6 @@
 import RPC from "bare-rpc";
 export declare function getRPC(): Promise<RPC>;
-export declare function close(): void;
+export declare function close(): Promise<void>;
 export declare function createDuplexSession(payload: string, commandId: number): Promise<{
     requestStream: RPC.OutgoingStream;
     responseStream: RPC.IncomingStream;

package/dist/client/rpc/expo-rpc-client.js

@@ -10,6 +10,10 @@ let rpcPromise = null;
 let workletInstance = null;
 let workletInitialized = false;
 let cachedRuntimeContext;
+// Set while close() is in flight. Concurrent callers share the same
+// promise instead of double-sending __shutdown__ or re-entering the
+// terminate block on already-null state.
+let closingPromise = null;
 logger.debug("EXPO RPC Client bundle");
 async function getRuntimeContext() {
     if (cachedRuntimeContext) {
@@ -93,10 +97,98 @@ export async function getRPC() {
         rpcPromise = null;
     }
 }
-export function close() {
-    logger.info("🧹 Closing RPC client (Expo)");
-    rpcInstance = null;
-    rpcPromise = null;
+const SHUTDOWN_RPC_TIMEOUT_MS = 10_000;
+/**
+ * Pre-terminate cleanup roundtrip. Sends an internal `__shutdown__` message
+ * to the worker so it can clear addon plugin registries (calls each addon's
+ * `releaseLogger` → frees env-bound js_ref_t state) and unload all model
+ * instances BEFORE we kill the worklet.
+ *
+ * Without this, the worklet's V8 isolate dies while addon static state still
+ * holds js_ref_t handles into it; the next worklet's first `setLogger` call
+ * trips a V8 GlobalHandle assertion (brk 0 / SIGTRAP) and the iOS app dies.
+ *
+ * Best-effort: never throws. Falls through to terminate even on timeout.
+ */
+async function sendShutdownMessage(rpc) {
+    let timer;
+    try {
+        await Promise.race([
+            (async () => {
+                const req = rpc.request(1);
+                req.send(JSON.stringify({ type: "__shutdown__" }), "utf8");
+                const response = await req.reply("utf8");
+                const parsed = JSON.parse(String(response));
+                if (!parsed.success) {
+                    throw new Error(parsed.error ?? "Worker reported cleanup failure");
+                }
+            })(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Worker did not ack __shutdown__ within ${SHUTDOWN_RPC_TIMEOUT_MS}ms`)), SHUTDOWN_RPC_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    catch (error) {
+        // Best-effort: log but don't block termination if cleanup fails.
+        logger.warn(`⚠️ Pre-terminate worker cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export async function close() {
+    // Concurrent callers (or a getRPC retry that overlaps with a manual
+    // close) share the in-flight close promise instead of each sending
+    // their own __shutdown__ and racing on the terminate block.
+    if (closingPromise)
+        return closingPromise;
+    closingPromise = (async () => {
+        logger.info("🧹 Closing RPC client (Expo)");
+        // terminate() crashes on Android (addon dlclose leaves pthread_key_t
+        // destructors dangling); iOS dyld no-ops dlclose so it's safe there.
+        // Non-iOS: drop refs only -- sending __shutdown__ without a follow-up
+        // terminate would clear the worker plugin registry.
+        let platform;
+        try {
+            platform = (await getRuntimeContext()).platform;
+        }
+        catch (err) {
+            logger.debug("Failed to resolve runtime context for close()", { err });
+        }
+        if (platform !== "ios") {
+            rpcInstance = null;
+            rpcPromise = null;
+            return;
+        }
+        // iOS: existing pre-terminate cleanup + terminate.
+        if (rpcInstance) {
+            logger.info("🧹 Requesting worker pre-terminate cleanup");
+            await sendShutdownMessage(rpcInstance);
+        }
+        rpcInstance = null;
+        rpcPromise = null;
+        if (workletInstance) {
+            logger.info("🐻🔫 Terminating bare worklet");
+            try {
+                workletInstance.terminate();
+            }
+            catch (error) {
+                logger.debug("Failed to terminate worklet", { error });
+            }
+            workletInstance = null;
+            workletInitialized = false;
+        }
+    })();
+    try {
+        await closingPromise;
+    }
+    finally {
+        // Reset so a subsequent close() (e.g. after a fresh getRPC spawned
+        // a new worklet) can run again. Body guards on rpcInstance / workletInstance
+        // make a redundant call a no-op if state is already cleared.
+        closingPromise = null;
+    }
 }
 export async function createDuplexSession(payload, commandId) {
     const rpc = await getRPC();

package/dist/client/rpc/node-rpc-client.js

@@ -10,6 +10,8 @@ import { fileURLToPath } from "node:url";
 import { initializeConfig } from "../init-hooks.js";
 import { resolveConfig } from "../config-loader/resolve-config.node.js";
 import { getClientLogger } from "../../logging/index.js";
+import { RPCInitTimeoutError } from "../../utils/errors-client.js";
+const RPC_INIT_TIMEOUT_MS = 30_000;
 const logger = getClientLogger();
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -168,11 +170,31 @@ async function ensureRPC() {
     const socketPath = createSocketPath();
     currentSocketPath = socketPath;
     rpcPromise = new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            rpcPromise = null;
+            rpcInstance = null;
+            bareWorkerProc = null;
+            ipcServer = null;
+            currentSocketPath = null;
+            reject(new RPCInitTimeoutError(RPC_INIT_TIMEOUT_MS));
+        }, RPC_INIT_TIMEOUT_MS);
         ipcServer = createServer((socket) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
             rpcInstance = new RPC(socket, () => { });
             resolve(rpcInstance);
         });
         ipcServer.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
             rpcPromise = null;
             rpcInstance = null;
             bareWorkerProc = null;
@@ -191,6 +213,20 @@ async function ensureRPC() {
                 ],
                 stdio: ["inherit", "inherit", "inherit"],
             });
+            if (bareWorkerProc) {
+                bareWorkerProc.on("exit", (code) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    rpcPromise = null;
+                    rpcInstance = null;
+                    bareWorkerProc = null;
+                    ipcServer = null;
+                    currentSocketPath = null;
+                    reject(new RPCInitTimeoutError(RPC_INIT_TIMEOUT_MS, new Error(`Worker process exited with code ${code} before IPC connection was established`)));
+                });
+            }
         });
     });
     const rpc = await rpcPromise;

package/dist/examples/audio/mic-input.d.ts

@@ -0,0 +1,9 @@
+export type MicFormat = "f32le" | "s16le";
+export declare function listWindowsAudioDevices(): string[];
+export declare function getAudioInputArgs(): string[];
+export interface StartMicrophoneOptions {
+    sampleRate: number;
+    format: MicFormat;
+}
+export declare function startMicrophone(options: StartMicrophoneOptions): import("child_process").ChildProcessByStdio<null, import("stream").Readable, null>;
+//# sourceMappingURL=mic-input.d.ts.map

package/dist/examples/audio/mic-input.js

@@ -0,0 +1,111 @@
+/**
+ * Shared microphone-capture helpers for the transcription and
+ * voice-assistant examples. Wraps ffmpeg so the examples don't each
+ * re-implement device selection.
+ *
+ * The default device is the system default mic. Override on any OS
+ * with the MIC_DEVICE environment variable. On Windows, if no override
+ * is set, the first DirectShow audio device reported by ffmpeg is used.
+ */
+import { spawn, spawnSync } from "child_process";
+import { platform } from "os";
+// Parses the DirectShow audio device list printed by:
+//   ffmpeg -hide_banner -f dshow -list_devices true -i dummy
+// Output goes to stderr; ffmpeg always exits non-zero because `-i dummy`
+// isn't a real device — that's expected.
+//
+// Handles both ffmpeg output formats:
+//
+// Old (ffmpeg ≤ 4.3):
+//   [dshow @ ...] DirectShow audio devices
+//   [dshow @ ...]  "Microphone (Realtek Audio)"
+//   [dshow @ ...]     Alternative name "@device_cm_..."
+//
+// New (ffmpeg ≥ 4.4):
+//   [dshow @ ...] "Integrated Camera" (video)
+//   [dshow @ ...]   Alternative name "@device_pnp_..."
+//   [dshow @ ...] "Microphone (Realtek Audio)" (audio)
+//   [dshow @ ...]   Alternative name "@device_cm_..."
+//
+// The newer format dropped the "DirectShow audio devices" header and tags
+// each device line with `(audio)` or `(video)` instead.
+export function listWindowsAudioDevices() {
+    const result = spawnSync("ffmpeg", ["-hide_banner", "-f", "dshow", "-list_devices", "true", "-i", "dummy"], { encoding: "utf8" });
+    const stderr = result.stderr ?? "";
+    const devices = [];
+    let section = null;
+    for (const line of stderr.split(/\r?\n/)) {
+        // Old-format section headers.
+        if (line.includes("DirectShow audio devices")) {
+            section = "audio";
+            continue;
+        }
+        if (line.includes("DirectShow video devices")) {
+            section = "video";
+            continue;
+        }
+        // New-format per-line tag wins over the section state.
+        const hasAudioTag = /\(audio\)/.test(line);
+        const hasVideoTag = /\(video\)/.test(line);
+        const lineSection = hasAudioTag ? "audio" : hasVideoTag ? "video" : section;
+        if (lineSection !== "audio")
+            continue;
+        // First quoted token is the device name. Alternative-name lines start
+        // with `@device_...` and are filtered out.
+        const match = line.match(/"([^"]+)"/);
+        if (!match)
+            continue;
+        const name = match[1];
+        if (!name || name.startsWith("@device"))
+            continue;
+        devices.push(name);
+    }
+    return devices;
+}
+export function getAudioInputArgs() {
+    const env = process.env;
+    const override = env["MIC_DEVICE"];
+    switch (platform()) {
+        case "darwin":
+            // AVFoundation device spec is `<video>:<audio>`. `:0` = default audio.
+            // Override with e.g. MIC_DEVICE=":1" to pick another device, or run
+            // `ffmpeg -f avfoundation -list_devices true -i ""` to enumerate.
+            return ["-f", "avfoundation", "-i", override ?? ":0"];
+        case "linux":
+            // PulseAudio source name. `default` follows the system default mic.
+            // Override with MIC_DEVICE="alsa_input.pci-..." etc.; list with
+            // `pactl list short sources`.
+            return ["-f", "pulse", "-i", override ?? "default"];
+        case "win32": {
+            if (override)
+                return ["-f", "dshow", "-i", `audio=${override}`];
+            const devices = listWindowsAudioDevices();
+            const deviceName = devices[0];
+            if (!deviceName) {
+                throw new Error("No Windows audio input device found. List devices with:\n" +
+                    "  ffmpeg -hide_banner -f dshow -list_devices true -i dummy\n" +
+                    'Then set MIC_DEVICE="Your Device Name" and retry.');
+            }
+            return ["-f", "dshow", "-i", `audio=${deviceName}`];
+        }
+        default:
+            throw new Error(`Unsupported platform: ${platform()}`);
+    }
+}
+export function startMicrophone(options) {
+    const formatArgs = options.format === "f32le"
+        ? ["-sample_fmt", "flt", "-f", "f32le"]
+        : ["-sample_fmt", "s16", "-f", "s16le"];
+    const ffmpeg = spawn("ffmpeg", [
+        ...getAudioInputArgs(),
+        "-ar",
+        String(options.sampleRate),
+        "-ac",
+        "1",
+        ...formatArgs,
+        "pipe:1",
+    ], { stdio: ["ignore", "pipe", "ignore"] });
+    if (!ffmpeg.stdout)
+        throw new Error("Failed to open microphone");
+    return ffmpeg;
+}

package/dist/examples/completion-events.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Event-driven completion — demonstrates the unified `CompletionEvent` stream.
+ *
+ * `completion()` returns a `CompletionRun` with two primary surfaces:
+ *
+ *  - `events`  — an `AsyncIterable<CompletionEvent>` of ordered, typed events
+ *                (`contentDelta`, `thinkingDelta`, `toolCall`, `toolError`,
+ *                 `completionStats`, `completionDone`, `rawDelta`).
+ *  - `final`   — a `Promise<CompletionFinal>` that resolves once the stream
+ *                ends, providing aggregated `contentText`, `thinkingText`,
+ *                `toolCalls`, `stats`, and `raw.fullText`.
+ *
+ * Set `captureThinking: true` to attempt best-effort `<think>` block parsing
+ * into dedicated `thinkingDelta` events. `final.raw.fullText` keeps the exact
+ * model output.
+ */
+export {};
+//# sourceMappingURL=completion-events.d.ts.map