@wirecat/cli-core 0.498.0 → 0.500.0

package/dist/meetings/transcription.js

@@ -11,6 +11,8 @@ const identifier = (value) => {
         throw new CliError("validation_error", "transcription identifiers must be bounded nonempty strings");
     return value;
 };
+/** Recognized off this machine: the stored source names the provider rather than `local/`. */
+const REMOTE_ENGINES = new Set(["openai"]);
 const cancelled = (signal) => {
     if (signal?.aborted) {
         if (signal.reason instanceof CliError)
@@ -64,21 +66,33 @@ export const transcribeMeeting = async (source, store, target, options = {}) =>
     const outcome = await dispatchMeetingMutation(mutation, async () => {
         const rows = [];
         let textBytes = 0;
-        let end = 0;
+        let start = 0;
+        const ends = new Map();
         let provided = 0;
         for await (const segment of source.segments(media, context)) {
             cancelled(context.signal);
             provided++;
+            const given = segment.speaker ?? undefined;
+            if (given !== undefined &&
+                (typeof given !== "string" || !given.trim() || given.length > 200 || /[\0\r\n]/.test(given)))
+                throw new CliError("invalid_response", "invalid recognition segment speaker");
+            const speaker = given?.trim();
+            // Without speakers, nothing may overlap; with them, only one speaker's own segments may not.
+            const overlapping = speaker === undefined
+                ? [...ends.values()].reduce((latest, end) => Math.max(latest, end), 0)
+                : Math.max(ends.get(undefined) ?? 0, ends.get(speaker) ?? 0);
             if (provided > maxSegments ||
                 !Number.isSafeInteger(segment.startMs) ||
                 !Number.isSafeInteger(segment.endMs) ||
-                segment.startMs < end ||
+                segment.startMs < start ||
+                segment.startMs < overlapping ||
                 segment.endMs <= segment.startMs ||
                 segment.endMs > media.durationMs ||
                 typeof segment.text !== "string" ||
                 segment.text.includes("\0"))
                 throw new CliError("invalid_response", "invalid or excessive recognition segments");
-            end = segment.endMs;
+            start = segment.startMs;
+            ends.set(speaker, Math.max(ends.get(speaker) ?? 0, segment.endMs));
             const text = segment.text.trim();
             if (text.length > maxTextBytes - textBytes)
                 throw new CliError("validation_error", "transcript exceeds its byte limit");
@@ -90,7 +104,7 @@ export const transcribeMeeting = async (source, store, target, options = {}) =>
                     position: rows.length,
                     startMs: segment.startMs,
                     endMs: segment.endMs,
-                    speakerName: null,
+                    speakerName: speaker ?? null,
                     text,
                     normalizedText: null,
                     metadata: null,
@@ -114,8 +128,15 @@ export const transcribeMeeting = async (source, store, target, options = {}) =>
             now,
             transcripts: [
                 {
-                    source: `local/${encodeURIComponent(media.recognition.engine)}/${encodeURIComponent(media.recognition.model)}`,
-                    format: "local-transcription",
+                    ...(REMOTE_ENGINES.has(media.recognition.engine)
+                        ? {
+                            source: `${encodeURIComponent(media.recognition.engine)}/${encodeURIComponent(media.recognition.model)}`,
+                            format: `${media.recognition.engine}-transcription`,
+                        }
+                        : {
+                            source: `local/${encodeURIComponent(media.recognition.engine)}/${encodeURIComponent(media.recognition.model)}`,
+                            format: "local-transcription",
+                        }),
                     language: null,
                     contentHash: hash,
                     externalCreatedAt: null,

package/dist/speech/decode.d.ts

@@ -13,9 +13,19 @@ export declare const formatOf: (bytes: Uint8Array) => Format;
  * the GPL. From a file rather than a pipe: an MP4 whose index sits at the end cannot be read from a pipe.
  */
 export declare const runFfmpeg: Ffmpeg;
+export interface DecodedChannels {
+    channels: Pcm[];
+    /** True when ffmpeg read the file: whatever channels it had arrive mixed into one, so one speaker per channel is lost. */
+    mixed: boolean;
+}
+/**
+ * Every channel the file has, one `Pcm` each: a phone call recorded in stereo keeps one speaker per channel.
+ * Only the bundled decoders keep channels apart; what ffmpeg reads arrives mixed down to one, and says so.
+ */
+export declare const decodeChannels: (bytes: Uint8Array, ffmpeg?: Ffmpeg) => Promise<DecodedChannels>;
 /**
  * Opus, Vorbis, FLAC and MP3 by the bundled decoders; anything else, or what one of them could not read, by ffmpeg
- * when the machine has it. The bundled decoder's error wins: it names the file's own problem.
+ * when the machine has it. The bundled decoder's error wins: it names the file's own problem. The first channel only.
  */
 export declare const decodeAudio: (bytes: Uint8Array, ffmpeg?: Ffmpeg) => Promise<Pcm>;
 export {};

package/dist/speech/decode.js

@@ -33,11 +33,10 @@ export const formatOf = (bytes) => {
         return "mp3";
     return "other";
 };
-const firstChannel = (decoded) => {
-    const samples = decoded.channelData[0];
-    if (!samples || decoded.samplesDecoded === 0)
+const everyChannel = (decoded) => {
+    if (!decoded.channelData[0] || decoded.samplesDecoded === 0)
         throw new CliError("validation_error", "no audio in that file");
-    return { samples, rate: decoded.sampleRate };
+    return decoded.channelData.map((samples) => ({ samples, rate: decoded.sampleRate }));
 };
 /**
  * Found from cli-core's own place and imported by URL, so a CLI's bundler leaves the decoder whole: bundled, it looks
@@ -49,7 +48,7 @@ const decodeVorbis = async (bytes) => {
     const decoder = new OggVorbisDecoder();
     await decoder.ready;
     try {
-        return firstChannel(await decoder.decodeFile(bytes));
+        return everyChannel(await decoder.decodeFile(bytes));
     }
     finally {
         decoder.free();
@@ -60,7 +59,7 @@ const decodeFlac = async (bytes) => {
     const decoder = new FLACDecoder();
     await decoder.ready;
     try {
-        return firstChannel(await decoder.decodeFile(bytes));
+        return everyChannel(await decoder.decodeFile(bytes));
     }
     finally {
         decoder.free();
@@ -71,7 +70,7 @@ const decodeMp3 = async (bytes) => {
     const decoder = new MPEGDecoder();
     await decoder.ready;
     try {
-        return firstChannel(decoder.decode(bytes));
+        return everyChannel(decoder.decode(bytes));
     }
     finally {
         decoder.free();
@@ -147,18 +146,24 @@ const BUNDLED = {
     flac: decodeFlac,
     mp3: decodeMp3,
 };
+const tooLong = (pcm) => pcm.samples.length / pcm.rate > LONGEST_AUDIO_SECONDS;
 /**
- * Opus, Vorbis, FLAC and MP3 by the bundled decoders; anything else, or what one of them could not read, by ffmpeg
- * when the machine has it. The bundled decoder's error wins: it names the file's own problem.
+ * Every channel the file has, one `Pcm` each: a phone call recorded in stereo keeps one speaker per channel.
+ * Only the bundled decoders keep channels apart; what ffmpeg reads arrives mixed down to one, and says so.
  */
-export const decodeAudio = async (bytes, ffmpeg = runFfmpeg) => {
+export const decodeChannels = async (bytes, ffmpeg = runFfmpeg) => {
     const format = formatOf(bytes);
-    const pcm = format === "other"
-        ? await ffmpeg(bytes)
-        : await BUNDLED[format](bytes).catch((error) => ffmpeg(bytes).catch(() => {
+    const decoded = format === "other"
+        ? { channels: [await ffmpeg(bytes)], mixed: true }
+        : await BUNDLED[format](bytes).then((channels) => ({ channels, mixed: false }), (error) => ffmpeg(bytes).then((pcm) => ({ channels: [pcm], mixed: true }), () => {
             throw error;
         }));
-    if (pcm.samples.length / pcm.rate > LONGEST_AUDIO_SECONDS)
+    if (decoded.channels.some(tooLong))
         throw new CliError("validation_error", `the audio is longer than ${LONGEST_AUDIO_SECONDS / 60} minutes`);
-    return pcm;
+    return decoded;
 };
+/**
+ * Opus, Vorbis, FLAC and MP3 by the bundled decoders; anything else, or what one of them could not read, by ffmpeg
+ * when the machine has it. The bundled decoder's error wins: it names the file's own problem. The first channel only.
+ */
+export const decodeAudio = async (bytes, ffmpeg = runFfmpeg) => (await decodeChannels(bytes, ffmpeg)).channels[0];

package/dist/speech/hearing.d.ts

@@ -1,3 +1,4 @@
+import { type KeyringStore } from "@wirecat/cli-base";
 import type { Missing } from "@wirecat/cli-base/standards";
 import type { Messenger } from "../cli/messenger/context.js";
 import type { Settings } from "../cli/settings.js";
@@ -60,9 +61,10 @@ export declare const spoken: <T extends Message & {
     transcript?: string;
 }>({ transcript, ...message }: T) => Message;
 /** For an MCP tool: the same hearing, over the session's own connection. */
-export declare const hearForTool: (messenger: Messenger, connect: <T>(work: (adapter: MessengerAdapter) => Promise<T>) => Promise<T>, messages: readonly Message[], transcribe: boolean, { settings, env }: {
+export declare const hearForTool: (messenger: Messenger, connect: <T>(work: (adapter: MessengerAdapter) => Promise<T>) => Promise<T>, messages: readonly Message[], transcribe: boolean, { settings, env, keyring, }: {
     settings: Pick<Settings, "configured" | "shared" | "profile">;
     env: NodeJS.ProcessEnv;
+    keyring?: KeyringStore;
 }, model?: string) => Promise<Hearing | undefined>;
 /** Messages with their transcripts; `unheard` as well when `--transcribe` was asked for. */
 export declare const heard: <T extends Message>(messages: readonly T[], hearing: Hearing | undefined) => T[];

package/dist/speech/hearing.js

@@ -1,7 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { recalledAccount } from "../cli/messenger/accounts.js";
 import { openStore } from "../store/store.js";
-import { choose, hearLocally, hearOnline, isAudioFile } from "./transcribe.js";
+import { choose, hearLocally, hearOnline, isAudioFile, keptSource } from "./transcribe.js";
 /** `--model` chooses who hears what `--transcribe` asks for; alone it would quietly do nothing. */
 export const modelWith = (transcribe, model) => {
     if (model !== undefined && transcribe !== true) {
@@ -73,7 +73,7 @@ export const hearVoices = async (messenger, messages, kept, transcribe) => {
             if (heard.pending || heard.text.trim() === "")
                 continue;
             transcripts.set(keyOf(voice), heard.text);
-            await kept.keep(voice, heard.text, heard.model ?? heard.via);
+            await kept.keep(voice, heard.text, keptSource(heard));
         }
         catch (error) {
             problem ??= error instanceof Error ? error.message : String(error);
@@ -92,14 +92,14 @@ export const spoken = ({ transcript, ...message }) => transcript === undefined
     ? message
     : { ...message, text: [message.text, `🎤 ${transcript}`].filter(Boolean).join("\n") };
 /** For an MCP tool: the same hearing, over the session's own connection. */
-export const hearForTool = async (messenger, connect, messages, transcribe, { settings, env }, model) => {
+export const hearForTool = async (messenger, connect, messages, transcribe, { settings, env, keyring, }, model) => {
     if (!messages.some(hasAudio))
         return undefined;
     const kept = await openKept(messenger, settings.profile, env);
     try {
         return await hearVoices(messenger, messages, kept, transcribe
             ? {
-                choice: choose(messenger, settings, model === undefined ? {} : { model }, env),
+                choice: choose(messenger, settings, model === undefined ? {} : { model }, env, keyring),
                 connect,
             }
             : undefined);

package/dist/speech/index.d.ts

@@ -1,3 +1,6 @@
+export { decodeAudio, decodeChannels, type Ffmpeg, type Pcm, runFfmpeg, } from "./decode.js";
 export { type Fetch, install, installedBytes, isInstalled, megabytes, modelPath, modelsDirectory, sharedModelsDirectory, vadPath, } from "./install.js";
-export { type LocalSpeechBackend, type LocalSpeechRecognitionModel, type LocalSpeechRecognizer, type LocalSpeechRecognizerOptions, localSpeechRecognitionModel, openLocalSpeechRecognizer, } from "./local.js";
-export { DEFAULT_ORDER, findModel, MODELS, type ModelFile, orderedModels, type SpeechModel, speechModel, VAD, } from "./models.js";
+export { type LocalSpeechBackend, type LocalSpeechRecognitionModel, type LocalSpeechRecognizer, type LocalSpeechRecognizerOptions, localSpeechRecognitionModel, openLocalSpeechRecognizer, recognizeLocalPieces, } from "./local.js";
+export { DEFAULT_ORDER, findModel, MODELS, type ModelFile, OPENAI_TRANSCRIBE_MODEL, orderedModels, type SpeechModel, speechModel, VAD, } from "./models.js";
+export { LONGEST_REQUEST_SECONDS, type OpenAITranscription, transcribeOpenAI } from "./openai.js";
+export type { TimedText } from "./recognize.js";

package/dist/speech/index.js

@@ -1,3 +1,5 @@
+export { decodeAudio, decodeChannels, runFfmpeg, } from "./decode.js";
 export { install, installedBytes, isInstalled, megabytes, modelPath, modelsDirectory, sharedModelsDirectory, vadPath, } from "./install.js";
-export { localSpeechRecognitionModel, openLocalSpeechRecognizer, } from "./local.js";
-export { DEFAULT_ORDER, findModel, MODELS, orderedModels, speechModel, VAD, } from "./models.js";
+export { localSpeechRecognitionModel, openLocalSpeechRecognizer, recognizeLocalPieces, } from "./local.js";
+export { DEFAULT_ORDER, findModel, MODELS, OPENAI_TRANSCRIBE_MODEL, orderedModels, speechModel, VAD, } from "./models.js";
+export { LONGEST_REQUEST_SECONDS, transcribeOpenAI } from "./openai.js";

package/dist/speech/local.d.ts

@@ -1,4 +1,6 @@
+import type { Pcm } from "./decode.js";
 import { type SpeechModel } from "./models.js";
+import type { TimedText } from "./recognize.js";
 export interface LocalSpeechRecognitionModel {
     engine: "sherpa-onnx";
     model: string;
@@ -8,6 +10,7 @@ export interface LocalSpeechRecognitionModel {
 }
 export interface LocalSpeechBackend {
     recognize(pcm: Float32Array): string;
+    pieces?(pcm: Float32Array): TimedText[];
     free(): void;
 }
 export interface LocalSpeechRecognizer extends LocalSpeechRecognitionModel {
@@ -25,5 +28,10 @@ export interface LocalSpeechRecognizerOptions {
 }
 /** A pinned registry descriptor; no model files, credentials or network are accessed. */
 export declare const localSpeechRecognitionModel: (id: string) => Readonly<LocalSpeechRecognitionModel>;
+/**
+ * A whole recording, one channel of it, cut at pauses by the voice detector: each piece's text with where it lies,
+ * in seconds. Two channels heard this way merge into a dialogue by `start`. Existing installed models only.
+ */
+export declare const recognizeLocalPieces: (id: string, audio: Pcm, options?: Pick<LocalSpeechRecognizerOptions, "directory" | "env" | "open">) => Promise<TimedText[]>;
 /** Existing installed models only. Synchronous inference cancels between bounded windows. */
 export declare const openLocalSpeechRecognizer: (id: string, input?: LocalSpeechRecognizerOptions) => Promise<LocalSpeechRecognizer>;

package/dist/speech/local.js

@@ -25,6 +25,27 @@ export const localSpeechRecognitionModel = (id) => {
         .digest("hex");
     return Object.freeze({ engine: "sherpa-onnx", model: model.id, version, sampleRate: 16000, maxChunkSamples: 480000 });
 };
+const notInstalled = (id) => new CliError("not_found", `speech model ${id} is not installed; download it explicitly with a WireCat messenger's models download command`, { reason: "model.not-downloaded", model: id });
+/**
+ * A whole recording, one channel of it, cut at pauses by the voice detector: each piece's text with where it lies,
+ * in seconds. Two channels heard this way merge into a dialogue by `start`. Existing installed models only.
+ */
+export const recognizeLocalPieces = async (id, audio, options = {}) => {
+    const model = speechModel(id);
+    const directory = options.directory ?? modelsDirectory(options.env);
+    if (!isInstalled(model, directory))
+        throw notInstalled(model.id);
+    const { openRecognizer, toModelRate } = await import("./recognize.js");
+    const engine = (options.open ?? openRecognizer)(model, modelPath(directory, model), vadPath(directory));
+    try {
+        if (!engine.pieces)
+            throw new CliError("configuration_error", "this speech backend gives no timed pieces");
+        return engine.pieces(toModelRate(audio.samples, audio.rate));
+    }
+    finally {
+        engine.free();
+    }
+};
 /** Existing installed models only. Synchronous inference cancels between bounded windows. */
 export const openLocalSpeechRecognizer = async (id, input = {}) => {
     const options = { ...input };
@@ -41,7 +62,7 @@ export const openLocalSpeechRecognizer = async (id, input = {}) => {
         throw new CliError("validation_error", "local speech requires an absolute model directory and bounded output bytes");
     cancelled(options.signal);
     if (!isInstalled(model, directory))
-        throw new CliError("not_found", `speech model ${description.model} is not installed; download it explicitly with a WireCat messenger's models download command`, { reason: "model.not-downloaded", model: description.model });
+        throw notInstalled(description.model);
     const { openRecognizer, toModelRate } = await import("./recognize.js");
     cancelled(options.signal);
     const engine = (options.open ?? openRecognizer)(model, modelPath(directory, model), vadPath(directory));

package/dist/speech/models.d.ts

@@ -24,6 +24,8 @@ export interface SpeechModel {
     featureDim: number;
 }
 export declare const MODELS: SpeechModel[];
+/** OpenAI's recommended transcription model (speech-to-text guide, read 2026-10-31). */
+export declare const OPENAI_TRANSCRIBE_MODEL = "gpt-transcribe";
 /** Cuts speech at pauses. Every model needs it: five minutes in one piece crash the WebAssembly build. */
 export declare const VAD: ModelFile;
 /**

package/dist/speech/models.js

@@ -105,6 +105,8 @@ export const MODELS = [
         }),
     },
 ];
+/** OpenAI's recommended transcription model (speech-to-text guide, read 2026-10-31). */
+export const OPENAI_TRANSCRIBE_MODEL = "gpt-transcribe";
 /** Cuts speech at pauses. Every model needs it: five minutes in one piece crash the WebAssembly build. */
 export const VAD = {
     name: "silero_vad.onnx",

package/dist/speech/openai.d.ts

@@ -0,0 +1,54 @@
+import { type RetryConfig } from "@wirecat/cli-base";
+import { type Fetch } from "../embeddings/remote.js";
+import type { Pcm } from "./decode.js";
+import { type SpeechCutter, type TimedText } from "./recognize.js";
+/**
+ * Ten minutes of 16 kHz PCM16 is 19.2 MB: under OpenAI's 25 MB per file (speech-to-text guide, read 2026-10-31)
+ * whichever megabyte it means, with room for the multipart body around it.
+ */
+export declare const LONGEST_REQUEST_SECONDS = 600;
+export interface OpenAITranscription {
+    apiKey: string;
+    /** `gpt-transcribe` when not given. */
+    model?: string;
+    /** ISO-639-1 codes the speech may be in. Sent as `languages`; the singular `language` is never sent with it. */
+    languages?: readonly string[];
+    prompt?: string;
+    /** Literal terms expected in the speech; OpenAI refuses the whole request if one holds `<`, `>` or a line break. */
+    keywords?: readonly string[];
+    baseUrl?: string;
+    signal?: AbortSignal;
+    fetch?: Fetch;
+    /**
+     * Fewer, longer requests for a caller that wants the text and not the turns: a recording of up to ten minutes in
+     * one request, a longer one in pieces of up to ten minutes joined across pauses. Each piece then spans the silence
+     * between its utterances, so two channels heard this way do not merge into a dialogue.
+     */
+    bundle?: boolean;
+    /** The voice detector model; the shared models directory's when not given. */
+    vadModel?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Seams for tests: the detector, the retry policy and the clock. */
+    cutter?: (vadModel: string) => SpeechCutter;
+    retry?: RetryConfig;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    random?: () => number;
+}
+/**
+ * Each stretch of speech the detector found is a piece of its own: on one channel of a call, a pause is often the
+ * other person talking. Two stretches the detector split without a pause stay one. With `limit`, neighbours are also
+ * joined across pauses while the piece stays within it.
+ */
+export declare const piecesOf: (spans: readonly {
+    start: number;
+    end: number;
+}[], limit?: number) => {
+    start: number;
+    end: number;
+}[];
+/**
+ * Speech to text by OpenAI's `/audio/transcriptions`, from one channel's samples: one piece per stretch of speech the
+ * voice detector found, each sent alone, with where it lies in seconds. Two channels heard this way merge into a
+ * dialogue by `start`. `gpt-transcribe` gives no timestamps of its own, so the times are the detector's.
+ */
+export declare const transcribeOpenAI: (audio: Pcm, options: OpenAITranscription) => Promise<TimedText[]>;

package/dist/speech/openai.js

@@ -0,0 +1,199 @@
+import { setTimeout as wait } from "node:timers/promises";
+import { backoffMs, CliError, DEFAULT_RETRY } from "@wirecat/cli-base";
+import { providerWaitMs } from "@wirecat/cli-base/http";
+import { OPENAI_URL } from "../embeddings/remote.js";
+import { filesPresent, modelsDirectory, vadPath } from "./install.js";
+import { OPENAI_TRANSCRIBE_MODEL, VAD } from "./models.js";
+import { SAMPLE_RATE, toModelRate } from "./recognize.js";
+import { encodeWav } from "./wav.js";
+/**
+ * Ten minutes of 16 kHz PCM16 is 19.2 MB: under OpenAI's 25 MB per file (speech-to-text guide, read 2026-10-31)
+ * whichever megabyte it means, with room for the multipart body around it.
+ */
+export const LONGEST_REQUEST_SECONDS = 600;
+/**
+ * The detector cuts speech that runs past 20 seconds with no pause; on real speech that cut left 0.074 s between the
+ * two stretches, and the shortest real pause it found was 0.43 s. Below this the two are one stretch, cut mid-word.
+ */
+const JOINED_SECONDS = 0.2;
+/** Kept around each piece so its first and last sounds are not clipped; never reaches into the next piece. */
+const PAD_SECONDS = 0.2;
+const LEAD = SAMPLE_RATE / 2;
+/** OpenAI's codes for money or limits run out (error-codes guide, read 2026-10-31): waiting does not help. */
+const EXHAUSTED = new Set([
+    "insufficient_quota",
+    "credit_balance_exhausted",
+    "organization_spend_limit_exceeded",
+    "project_spend_limit_exceeded",
+    "organization_usage_limit_exceeded",
+]);
+const RETRY = { ...DEFAULT_RETRY, retries: 4 };
+const interrupted = (signal) => {
+    if (!signal?.aborted)
+        return;
+    if (signal.reason instanceof CliError)
+        throw signal.reason;
+    const timeout = signal.reason instanceof Error && signal.reason.name === "TimeoutError";
+    throw new CliError(timeout ? "timeout" : "cancelled", "the transcription was interrupted");
+};
+const sleeping = (ms, signal) => wait(ms, undefined, signal ? { signal } : {}).then(() => undefined, (error) => {
+    interrupted(signal);
+    throw error;
+});
+const formOf = (wav, options) => {
+    const form = new FormData();
+    form.append("file", new Blob([wav], { type: "audio/wav" }), "audio.wav");
+    form.append("model", options.model ?? OPENAI_TRANSCRIBE_MODEL);
+    // Repeated `name[]` fields: how OpenAI's own SDK sends an array in a multipart body.
+    for (const language of options.languages ?? [])
+        form.append("languages[]", language);
+    for (const keyword of options.keywords ?? [])
+        form.append("keywords[]", keyword);
+    if (options.prompt)
+        form.append("prompt", options.prompt);
+    return form;
+};
+const safe = (value) => typeof value === "string" && /^[\w.-]{1,64}$/.test(value) ? value : undefined;
+/** OpenAI's error code and type, never its message: a message can quote the request. */
+const failureOf = async (response) => {
+    try {
+        const body = (await response.json());
+        const code = safe(body.error?.code);
+        const type = safe(body.error?.type);
+        return { ...(code ? { code } : {}), ...(type ? { type } : {}) };
+    }
+    catch {
+        return {};
+    }
+};
+/** One file, one request. 429, 408 and server errors are tried again; the provider's `Retry-After` beats our backoff. */
+const send = async (wav, options) => {
+    const post = options.fetch ?? fetch;
+    const retry = options.retry ?? RETRY;
+    const sleep = options.sleep ?? sleeping;
+    const random = options.random ?? Math.random;
+    const url = `${(options.baseUrl ?? OPENAI_URL).replace(/\/+$/, "")}/audio/transcriptions`;
+    for (let attempt = 1;; attempt++) {
+        interrupted(options.signal);
+        let response;
+        try {
+            response = await post(url, {
+                method: "POST",
+                headers: { authorization: `Bearer ${options.apiKey}` },
+                body: formOf(wav, options),
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+        }
+        catch {
+            interrupted(options.signal);
+            if (attempt > retry.retries)
+                throw new CliError("network_error", "OpenAI could not be reached", { reason: "network.failed" });
+            await sleep(backoffMs(attempt, retry, random), options.signal);
+            continue;
+        }
+        if (response.ok) {
+            const body = (await response.json().catch(() => interrupted(options.signal)));
+            if (typeof body?.text !== "string")
+                throw new CliError("invalid_response", "OpenAI answered without a transcript", {
+                    reason: "provider.invalid-response",
+                });
+            return body.text.trim();
+        }
+        const { code, type } = await failureOf(response);
+        const status = response.status;
+        const said = `HTTP ${status}${code ? `, ${code}` : type ? `, ${type}` : ""}`;
+        if (status === 401)
+            throw new CliError("authentication_error", `OpenAI refused the key (${said}) — set it again with \`models keys set openai\``, { reason: "auth.failed" });
+        if (status === 403)
+            throw new CliError("permission_error", `OpenAI refused the request (${said}) — it answers this when the country or region is not supported, or the key's project may not use the model`, { reason: "access.denied" });
+        if (status === 413)
+            throw new CliError("validation_error", `OpenAI refused the audio as too large (${said})`, {
+                reason: "transcription.too-large",
+            });
+        if (EXHAUSTED.has(code ?? "") || EXHAUSTED.has(type ?? ""))
+            throw new CliError("permission_error", `OpenAI refused: the account's credit, spend limit or usage limit is used up (${said}) — see the billing page`, { reason: "transcription.quota-exhausted" });
+        const again = status === 408 || status === 429 || status >= 500;
+        const asked = providerWaitMs(response.headers, () => new Date());
+        if (again && attempt <= retry.retries && (asked === undefined || asked <= retry.maxRetryAfterMs)) {
+            await sleep(asked ?? backoffMs(attempt, retry, random), options.signal);
+            continue;
+        }
+        if (status === 429)
+            throw new CliError("rate_limited", `OpenAI answered ${said}`, {
+                reason: "provider.rate-limited",
+                ...(asked === undefined ? {} : { retry_after_ms: asked }),
+            });
+        if (status >= 500)
+            throw new CliError([502, 503, 504].includes(status) ? "provider_unavailable" : "provider_error", `OpenAI answered ${said}`, { reason: [502, 503, 504].includes(status) ? "provider.unavailable" : "provider.refused" });
+        throw new CliError("provider_error", `OpenAI answered ${said}`, { reason: "provider.refused" });
+    }
+};
+/**
+ * Each stretch of speech the detector found is a piece of its own: on one channel of a call, a pause is often the
+ * other person talking. Two stretches the detector split without a pause stay one. With `limit`, neighbours are also
+ * joined across pauses while the piece stays within it.
+ */
+export const piecesOf = (spans, limit) => {
+    const pieces = [];
+    for (const span of spans) {
+        const last = pieces.at(-1);
+        const joined = last !== undefined && span.start - last.end < JOINED_SECONDS;
+        const fits = last !== undefined && limit !== undefined && span.end - last.start <= limit;
+        if (last && (fits || (joined && span.end - last.start <= LONGEST_REQUEST_SECONDS)))
+            last.end = span.end;
+        else
+            pieces.push({ start: span.start, end: span.end });
+    }
+    return pieces;
+};
+const openCutter = async (vadModel) => {
+    const { openSpeechCutter } = await import("./recognize.js");
+    return openSpeechCutter(vadModel);
+};
+const checkKeywords = (keywords = []) => {
+    const bad = keywords.find((keyword) => typeof keyword !== "string" || !keyword.trim() || /[<>\r\n]/.test(keyword));
+    if (bad !== undefined)
+        throw new CliError("validation_error", "a keyword must be a non-empty single line without < or > — OpenAI refuses the whole request otherwise");
+};
+/**
+ * Speech to text by OpenAI's `/audio/transcriptions`, from one channel's samples: one piece per stretch of speech the
+ * voice detector found, each sent alone, with where it lies in seconds. Two channels heard this way merge into a
+ * dialogue by `start`. `gpt-transcribe` gives no timestamps of its own, so the times are the detector's.
+ */
+export const transcribeOpenAI = async (audio, options) => {
+    if (!options.apiKey)
+        throw new CliError("authentication_error", "no OpenAI key — `models keys set openai`, or OPENAI_API_KEY", {
+            reason: "transcription.no-key",
+        });
+    checkKeywords(options.keywords);
+    interrupted(options.signal);
+    const pcm = toModelRate(audio.samples, audio.rate);
+    const duration = (pcm.length - LEAD) / SAMPLE_RATE;
+    if (options.bundle && duration <= LONGEST_REQUEST_SECONDS) {
+        const text = await send(encodeWav(pcm.subarray(LEAD)), options);
+        return text ? [{ start: 0, end: duration, text }] : [];
+    }
+    const vadModel = options.vadModel ?? vadPath(modelsDirectory(options.env));
+    if (!options.cutter && !filesPresent([[VAD, vadModel]]))
+        throw new CliError("not_found", "the voice detector that finds the speech is not on this machine — it comes with any speech model: `models download`", { reason: "model.not-downloaded", model: "silero_vad" });
+    const cutter = await (options.cutter ?? openCutter)(vadModel);
+    let spans;
+    try {
+        spans = cutter.cut(pcm);
+    }
+    finally {
+        cutter.free();
+    }
+    const pieces = piecesOf(spans, options.bundle ? LONGEST_REQUEST_SECONDS : undefined);
+    const heard = [];
+    for (const [index, piece] of pieces.entries()) {
+        const end = Math.min(piece.end, duration);
+        const from = Math.max(piece.start - PAD_SECONDS, pieces[index - 1]?.end ?? 0);
+        const to = Math.min(end + PAD_SECONDS, pieces[index + 1]?.start ?? duration);
+        const samples = pcm.subarray(LEAD + Math.floor(from * SAMPLE_RATE), LEAD + Math.ceil(to * SAMPLE_RATE));
+        const text = await send(encodeWav(samples), options);
+        if (text)
+            heard.push({ start: Math.min(piece.start, end), end, text });
+    }
+    return heard;
+};

package/dist/speech/recognize.d.ts

@@ -1,7 +1,15 @@
 import type { SpeechModel } from "./models.js";
+/** Seconds from the start of the recording. */
+export interface TimedText {
+    start: number;
+    end: number;
+    text: string;
+}
 /** What transcription needs from a speech engine — small enough for a test to stand in for it. */
 export interface Recognizer {
     recognize(pcm: Float32Array): string;
+    /** Each stretch of speech the voice detector cut, with where it lies; the same input as `recognize`. */
+    pieces?(pcm: Float32Array): TimedText[];
     free(): void;
 }
 export declare const SAMPLE_RATE = 16000;
@@ -13,7 +21,7 @@ export declare const toModelRate: (samples: Float32Array, rate: number) => Float
 export declare const decodeOgg: (bytes: Uint8Array) => Promise<{
     samples: Float32Array;
     rate: number;
-}>;
+}[]>;
 interface SherpaStream {
     acceptWaveform(rate: number, samples: Float32Array): void;
     free(): void;
@@ -31,6 +39,7 @@ interface Sherpa {
         acceptWaveform(samples: Float32Array): void;
         isEmpty(): boolean;
         front(): {
+            start: number;
             samples: Float32Array;
         };
         pop(): void;
@@ -55,6 +64,21 @@ export declare const detector: (vadModel: string) => {
     debug: number;
     bufferSizeInSeconds: number;
 };
+export interface SpeechSpan {
+    start: number;
+    end: number;
+    samples: Float32Array;
+}
+export interface SpeechCutter {
+    /** Where the speech is, in seconds of the recording; `pcm` as `toModelRate` made it. */
+    cut(pcm: Float32Array): {
+        start: number;
+        end: number;
+    }[];
+    free(): void;
+}
+/** The voice detector alone, for a recognizer that is not on this machine. */
+export declare const openSpeechCutter: (vadModel: string) => SpeechCutter;
 /**
  * The engine's WebAssembly writes its logs (a growing buffer says "Overflow! … No data loss!") with
  * `printf`, which its file system sends straight to file descriptor 1 and so into `--json` output.