@opengeni/api-router 0.21.14 → 0.22.2

package/src/routes/transcriptions.ts

@@ -5,8 +5,10 @@ import {
 import { type ApiRouteDeps, requireAccessGrant, TranscriptionServiceError } from "@opengeni/core";
 import { getWorkspace } from "@opengeni/db";
 import type { Hono } from "hono";
+import { registerResumableTranscriptionRoutes } from "./transcription-recordings";
 
 export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void {
+  registerResumableTranscriptionRoutes(app, deps);
   app.post("/v1/workspaces/:workspaceId/transcriptions", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:create");

package/src/transcription/providers/azure-openai.ts

@@ -13,13 +13,14 @@ export function createAzureOpenAiTranscriptionProvider(input: {
   const url = `${input.endpoint}/openai/deployments/${encodeURIComponent(input.deployment)}/audio/transcriptions?api-version=${encodeURIComponent(input.apiVersion)}`;
   return {
     id: "azure-openai",
+    supportsServerDeadline: true,
     available: () => Boolean(input.apiKey || input.adToken),
-    async transcribe({ audio, mimeType, filename, signal }) {
+    async transcribe({ audio, mimeType, filename, requestId, signal }) {
       const form = new FormData();
       form.append("file", new Blob([Uint8Array.from(audio).buffer], { type: mimeType }), filename);
       const headers: Record<string, string> = input.apiKey
-        ? { "api-key": input.apiKey }
-        : { Authorization: `Bearer ${input.adToken}` };
+        ? { "api-key": input.apiKey, "x-opengeni-request-id": requestId }
+        : { Authorization: `Bearer ${input.adToken}`, "x-opengeni-request-id": requestId };
       let response: Response;
       try {
         response = await fetchImpl(url, {

package/src/transcription/providers/codex-subscription.ts

@@ -36,9 +36,10 @@ export function createCodexSubscriptionTranscriptionProvider(input: {
     });
   return {
     id: "codex-subscription",
+    supportsServerDeadline: true,
     experimental: true,
     available: probe,
-    async transcribe({ audio, mimeType, filename, workspaceId, signal }) {
+    async transcribe({ audio, mimeType, filename, workspaceId, requestId, signal }) {
       const account = (await listCodexAccountStatuses(input.db, workspaceId)).find(
         (candidate) => candidate.isActive && candidate.status === "active",
       );
@@ -73,6 +74,8 @@ export function createCodexSubscriptionTranscriptionProvider(input: {
             originator: CODEX_ORIGINATOR,
             "User-Agent": `${CODEX_ORIGINATOR}/${CODEX_CLIENT_VERSION}`,
             version: CODEX_CLIENT_VERSION,
+            // Observability only; the upstream API is not treated as idempotent.
+            "x-opengeni-request-id": requestId,
           },
           body: form,
           ...(signal ? { signal } : {}),

package/src/transcription/providers/openai.ts

@@ -9,8 +9,9 @@ export function createOpenAiTranscriptionProvider(input: {
   const fetchImpl = input.fetch ?? fetch;
   return {
     id: "openai",
+    supportsServerDeadline: true,
     available: () => true,
-    async transcribe({ audio, mimeType, filename, signal }) {
+    async transcribe({ audio, mimeType, filename, requestId, signal }) {
       const form = new FormData();
       form.append("file", audioBlob(audio, mimeType), filename);
       form.append("model", input.model);
@@ -18,7 +19,11 @@ export function createOpenAiTranscriptionProvider(input: {
       try {
         response = await fetchImpl(`${input.baseUrl}/audio/transcriptions`, {
           method: "POST",
-          headers: { Authorization: `Bearer ${input.apiKey}` },
+          headers: {
+            Authorization: `Bearer ${input.apiKey}`,
+            // Observability only; the upstream API is not treated as idempotent.
+            "x-opengeni-request-id": requestId,
+          },
           body: form,
           ...(signal ? { signal } : {}),
         });

package/src/transcription/segmenter.ts

@@ -0,0 +1,260 @@
+import type { PreparedTranscriptionSegment, TranscriptionSegmenter } from "@opengeni/core";
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { once } from "node:events";
+
+const STDERR_MAX_BYTES = 64 * 1024;
+
+export class TranscriptionSegmenterError extends Error {
+  readonly name = "TranscriptionSegmenterError";
+
+  constructor(
+    message: string,
+    readonly code: "unavailable" | "invalid_audio" | "cancelled" | "too_large" | "unknown",
+    readonly retryable: boolean,
+  ) {
+    super(message);
+  }
+}
+
+export function createFfmpegTranscriptionSegmenter(input: {
+  ffmpegPath: string;
+}): TranscriptionSegmenter {
+  let availability: Promise<boolean> | null = null;
+  return {
+    available() {
+      availability ??= commandSucceeds(input.ffmpegPath, ["-version"]);
+      return availability;
+    },
+    async *segment(request): AsyncIterable<PreparedTranscriptionSegment> {
+      if (request.signal?.aborted) {
+        throw new TranscriptionSegmenterError(
+          "Audio segmentation was cancelled",
+          "cancelled",
+          true,
+        );
+      }
+      if (
+        !Number.isSafeInteger(request.providerSegmentSeconds) ||
+        request.providerSegmentSeconds <= 0 ||
+        !Number.isSafeInteger(request.totalDurationMilliseconds) ||
+        request.totalDurationMilliseconds <= 0
+      ) {
+        throw new TranscriptionSegmenterError(
+          "Audio segmentation bounds are invalid",
+          "invalid_audio",
+          false,
+        );
+      }
+      if (
+        Math.ceil(request.totalDurationMilliseconds / (request.providerSegmentSeconds * 1_000)) >
+        1_000
+      ) {
+        throw new TranscriptionSegmenterError(
+          "Audio exceeds the bounded segment projection",
+          "too_large",
+          false,
+        );
+      }
+      const directory = await mkdtemp(join(tmpdir(), "opengeni-transcription-"));
+      const inputPath = join(
+        directory,
+        `recording.${extensionForMimeType(request.sourceMimeType)}`,
+      );
+      const outputPattern = join(directory, "segment-%06d.wav");
+      try {
+        await writeChunks(inputPath, request.chunks, request.signal);
+        const result = await runCommand(
+          input.ffmpegPath,
+          [
+            "-nostdin",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y",
+            "-i",
+            inputPath,
+            "-map",
+            "0:a:0",
+            "-vn",
+            "-ac",
+            "1",
+            "-ar",
+            "16000",
+            "-c:a",
+            "pcm_s16le",
+            "-f",
+            "segment",
+            "-segment_time",
+            String(request.providerSegmentSeconds),
+            "-reset_timestamps",
+            "1",
+            outputPattern,
+          ],
+          request.signal,
+        );
+        if (result.cancelled) {
+          throw new TranscriptionSegmenterError(
+            "Audio segmentation was cancelled",
+            "cancelled",
+            true,
+          );
+        }
+        if (result.spawnError) {
+          throw new TranscriptionSegmenterError(
+            "Audio segmentation is unavailable",
+            "unavailable",
+            true,
+          );
+        }
+        if (result.exitCode !== 0) {
+          throw new TranscriptionSegmenterError(
+            result.stderr || "Audio could not be decoded",
+            "invalid_audio",
+            false,
+          );
+        }
+        const files = (await readdir(directory))
+          .filter((file) => /^segment-[0-9]{6}\.wav$/.test(file))
+          .sort();
+        if (files.length === 0 || files.length > 1_000) {
+          throw new TranscriptionSegmenterError(
+            "Audio did not produce a bounded segment set",
+            "invalid_audio",
+            false,
+          );
+        }
+        const segmentMilliseconds = request.providerSegmentSeconds * 1_000;
+        for (let segmentNumber = 0; segmentNumber < files.length; segmentNumber += 1) {
+          if (request.signal?.aborted) {
+            throw new TranscriptionSegmenterError(
+              "Audio segmentation was cancelled",
+              "cancelled",
+              true,
+            );
+          }
+          const bytes = new Uint8Array(await readFile(join(directory, files[segmentNumber]!)));
+          if (bytes.byteLength === 0) {
+            throw new TranscriptionSegmenterError(
+              "Audio produced an empty segment",
+              "invalid_audio",
+              false,
+            );
+          }
+          const startMilliseconds = segmentNumber * segmentMilliseconds;
+          const remaining = request.totalDurationMilliseconds - startMilliseconds;
+          if (remaining <= 0) {
+            throw new TranscriptionSegmenterError(
+              "Audio segment count exceeds the declared duration",
+              "invalid_audio",
+              false,
+            );
+          }
+          yield {
+            segmentNumber,
+            startMilliseconds,
+            durationMilliseconds: Math.min(segmentMilliseconds, remaining),
+            mimeType: "audio/wav",
+            bytes,
+          };
+        }
+      } catch (error) {
+        if (error instanceof TranscriptionSegmenterError) throw error;
+        throw new TranscriptionSegmenterError(
+          error instanceof Error ? error.message : "Audio segmentation failed",
+          request.signal?.aborted ? "cancelled" : "unknown",
+          true,
+        );
+      } finally {
+        await rm(directory, { recursive: true, force: true }).catch(() => undefined);
+      }
+    },
+  };
+}
+
+async function writeChunks(
+  path: string,
+  chunks: AsyncIterable<Uint8Array>,
+  signal?: AbortSignal,
+): Promise<void> {
+  const stream = createWriteStream(path, { flags: "wx" });
+  try {
+    for await (const chunk of chunks) {
+      if (signal?.aborted) {
+        throw new TranscriptionSegmenterError(
+          "Audio segmentation was cancelled",
+          "cancelled",
+          true,
+        );
+      }
+      if (!stream.write(chunk)) await once(stream, "drain");
+    }
+    stream.end();
+    await once(stream, "close");
+  } catch (error) {
+    stream.destroy();
+    throw error;
+  }
+}
+
+function extensionForMimeType(mimeType: string): string {
+  switch (mimeType.trim().toLowerCase().split(";", 1)[0]) {
+    case "audio/mp4":
+    case "audio/m4a":
+      return "mp4";
+    case "audio/ogg":
+      return "ogg";
+    case "audio/mpeg":
+    case "audio/mp3":
+      return "mp3";
+    case "audio/wav":
+    case "audio/x-wav":
+      return "wav";
+    case "audio/webm":
+    default:
+      return "webm";
+  }
+}
+
+async function commandSucceeds(command: string, args: string[]): Promise<boolean> {
+  const result = await runCommand(command, args);
+  return !result.spawnError && result.exitCode === 0;
+}
+
+async function runCommand(
+  command: string,
+  args: string[],
+  signal?: AbortSignal,
+): Promise<{ exitCode: number | null; stderr: string; spawnError: boolean; cancelled: boolean }> {
+  return await new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = Buffer.alloc(0);
+    let spawnError = false;
+    let settled = false;
+    const onAbort = () => child.kill("SIGKILL");
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+    child.stderr.on("data", (chunk: Uint8Array) => {
+      if (stderr.byteLength >= STDERR_MAX_BYTES) return;
+      const remaining = STDERR_MAX_BYTES - stderr.byteLength;
+      stderr = Buffer.concat([stderr, Buffer.from(chunk).subarray(0, remaining)]);
+    });
+    child.once("error", () => {
+      spawnError = true;
+    });
+    child.once("close", (exitCode) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      resolve({
+        exitCode,
+        stderr: stderr.toString("utf8").trim(),
+        spawnError,
+        cancelled: signal?.aborted ?? false,
+      });
+    });
+  });
+}

package/src/transcription/service.ts

@@ -4,6 +4,7 @@ import {
   filenameForMimeType,
   isAcceptedMimeType,
   normalizeMimeType,
+  TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS,
   type TranscriptionAvailabilityContext,
   type TranscriptionProvider,
   type TranscriptionService,
@@ -20,6 +21,10 @@ export function createTranscriptionService(input: {
   fetch?: typeof fetch;
   codexFetch?: typeof fetch;
   probeCodex?: (context?: TranscriptionAvailabilityContext) => boolean | Promise<boolean>;
+  /** Test seam for exercising timeout and late-completion behavior quickly. */
+  providerRequestTimeoutMilliseconds?: number;
+  /** Test seam for evaluating persisted absolute deadlines after delayed setup. */
+  now?: () => Date;
 }): TranscriptionService {
   const providers: TranscriptionProvider[] = resolveVoiceInputProviderRegistry(input.settings).map(
     (config) => {
@@ -51,6 +56,9 @@ export function createTranscriptionService(input: {
     maxSizeBytes: input.settings.voiceInputMaxSizeBytes,
     acceptedMimeTypes: [...VOICE_INPUT_ACCEPTED_MIME_TYPES],
   };
+  const providerRequestTimeoutMilliseconds =
+    input.providerRequestTimeoutMilliseconds ?? TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS;
+  const now = input.now ?? (() => new Date());
   return {
     limits: () => limits,
     async available(context) {
@@ -58,6 +66,9 @@ export function createTranscriptionService(input: {
         Boolean,
       );
     },
+    async selectProvider(context) {
+      return (await firstAvailable(providers, context))?.id ?? null;
+    },
     async transcribe(request) {
       const mimeType = normalizeMimeType(request.mimeType);
       if (!isAcceptedMimeType(mimeType, limits.acceptedMimeTypes)) {
@@ -83,23 +94,65 @@ export function createTranscriptionService(input: {
           message: "Invalid audio duration.",
         });
       }
-      const provider = await firstAvailable(providers, {
-        workspaceId: request.workspaceId,
-      });
+      const provider = request.providerId
+        ? await exactAvailable(providers, request.providerId, { workspaceId: request.workspaceId })
+        : await firstAvailable(providers, { workspaceId: request.workspaceId });
       if (!provider) {
         throw new TranscriptionServiceError({
           code: "unavailable",
           message: "Transcription is unavailable.",
         });
       }
+      if (provider.supportsServerDeadline !== true) {
+        throw new TranscriptionServiceError({
+          code: "unavailable",
+          message: "Transcription provider does not support bounded requests.",
+        });
+      }
       const startedAt = performance.now();
-      const result = await provider.transcribe({
-        audio: request.audio,
-        mimeType,
-        filename: filenameForMimeType(mimeType),
-        workspaceId: request.workspaceId,
-        signal: request.signal,
-      });
+      const remainingMilliseconds = request.providerDeadlineAt
+        ? remainingTranscriptionProviderRequestMilliseconds(request.providerDeadlineAt, now())
+        : providerRequestTimeoutMilliseconds;
+      if (
+        request.providerDeadlineAt &&
+        (!Number.isFinite(remainingMilliseconds) || remainingMilliseconds <= 0)
+      ) {
+        throw new TranscriptionServiceError({
+          code: "timeout",
+          message: "Transcription provider deadline expired.",
+          retryable: true,
+        });
+      }
+      const deadline = createProviderRequestDeadline(request.signal, remainingMilliseconds);
+      let result: { text: string; languages: string[] };
+      try {
+        result = await provider.transcribe({
+          audio: request.audio,
+          mimeType,
+          filename: filenameForMimeType(mimeType),
+          workspaceId: request.workspaceId,
+          requestId: request.requestId,
+          signal: deadline.signal,
+        });
+        if (deadline.timedOut && !request.signal?.aborted) {
+          throw new TranscriptionServiceError({
+            code: "timeout",
+            message: "Transcription provider timed out.",
+            retryable: true,
+          });
+        }
+      } catch (error) {
+        if (deadline.timedOut && !request.signal?.aborted) {
+          throw new TranscriptionServiceError({
+            code: "timeout",
+            message: "Transcription provider timed out.",
+            retryable: true,
+          });
+        }
+        throw error;
+      } finally {
+        deadline.dispose();
+      }
       return {
         ...result,
         providerId: provider.id,
@@ -110,6 +163,45 @@ export function createTranscriptionService(input: {
   };
 }
 
+export function remainingTranscriptionProviderRequestMilliseconds(
+  providerDeadlineAt: Date,
+  now: Date,
+): number {
+  return providerDeadlineAt.getTime() - now.getTime();
+}
+
+function createProviderRequestDeadline(
+  parentSignal: AbortSignal | undefined,
+  timeoutMilliseconds: number,
+): { signal: AbortSignal; readonly timedOut: boolean; dispose: () => void } {
+  const controller = new AbortController();
+  let timedOut = false;
+  const timeout = setTimeout(
+    () => {
+      timedOut = true;
+      controller.abort(new DOMException("Transcription provider timed out", "TimeoutError"));
+    },
+    Math.max(1, Math.ceil(timeoutMilliseconds)),
+  );
+  const abortFromParent = () => {
+    controller.abort(parentSignal?.reason);
+  };
+  if (parentSignal) {
+    if (parentSignal.aborted) abortFromParent();
+    else parentSignal.addEventListener("abort", abortFromParent, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    get timedOut() {
+      return timedOut;
+    },
+    dispose: () => {
+      clearTimeout(timeout);
+      parentSignal?.removeEventListener("abort", abortFromParent);
+    },
+  };
+}
+
 async function firstAvailable(
   providers: readonly TranscriptionProvider[],
   context: TranscriptionAvailabilityContext,
@@ -119,3 +211,12 @@ async function firstAvailable(
   }
   return null;
 }
+
+async function exactAvailable(
+  providers: readonly TranscriptionProvider[],
+  providerId: string,
+  context: TranscriptionAvailabilityContext,
+) {
+  const provider = providers.find((candidate) => candidate.id === providerId);
+  return provider && (await provider.available(context)) ? provider : null;
+}