egaki 0.5.0 → 0.7.0

package/src/cli/speech-provider.test.ts

@@ -0,0 +1,226 @@
+// Tests for the speech provider timestamp parsing logic.
+// Tests pure functions (no API calls): ElevenLabs character-to-word grouping,
+// ElevenLabs NDJSON stream parsing, and Cartesia SSE stream parsing.
+
+import { describe, it, expect } from 'vitest'
+import { groupCharactersToWords, parseElevenLabsStream } from './elevenlabs-speech-provider.js'
+import { parseCartesiaSseStream } from './cartesia-provider.js'
+
+describe('ElevenLabs groupCharactersToWords', () => {
+  it('groups simple words separated by spaces', () => {
+    const result = groupCharactersToWords({
+      characters: ['H', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd'],
+      character_start_times_seconds: [0, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5],
+      character_end_times_seconds: [0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5, 0.55],
+    })
+    expect(result).toMatchInlineSnapshot(`
+      [
+        {
+          "endSecond": 0.25,
+          "startSecond": 0,
+          "word": "Hello",
+        },
+        {
+          "endSecond": 0.55,
+          "startSecond": 0.3,
+          "word": "world",
+        },
+      ]
+    `)
+  })
+
+  it('handles multiple spaces between words', () => {
+    const result = groupCharactersToWords({
+      characters: ['a', ' ', ' ', 'b'],
+      character_start_times_seconds: [0, 0.1, 0.2, 0.3],
+      character_end_times_seconds: [0.1, 0.2, 0.3, 0.4],
+    })
+    expect(result).toEqual([
+      { word: 'a', startSecond: 0, endSecond: 0.1 },
+      { word: 'b', startSecond: 0.3, endSecond: 0.4 },
+    ])
+  })
+
+  it('handles punctuation attached to words', () => {
+    const result = groupCharactersToWords({
+      characters: ['H', 'i', '!', ' ', 'O', 'k', '.'],
+      character_start_times_seconds: [0, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3],
+      character_end_times_seconds: [0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35],
+    })
+    expect(result).toEqual([
+      { word: 'Hi!', startSecond: 0, endSecond: 0.15 },
+      { word: 'Ok.', startSecond: 0.2, endSecond: 0.35 },
+    ])
+  })
+
+  it('handles single character input', () => {
+    const result = groupCharactersToWords({
+      characters: ['a'],
+      character_start_times_seconds: [0],
+      character_end_times_seconds: [0.1],
+    })
+    expect(result).toEqual([{ word: 'a', startSecond: 0, endSecond: 0.1 }])
+  })
+
+  it('returns empty array for empty input', () => {
+    const result = groupCharactersToWords({
+      characters: [],
+      character_start_times_seconds: [],
+      character_end_times_seconds: [],
+    })
+    expect(result).toEqual([])
+  })
+
+  it('handles leading/trailing whitespace', () => {
+    const result = groupCharactersToWords({
+      characters: [' ', 'a', ' '],
+      character_start_times_seconds: [0, 0.1, 0.2],
+      character_end_times_seconds: [0.1, 0.2, 0.3],
+    })
+    expect(result).toEqual([{ word: 'a', startSecond: 0.1, endSecond: 0.2 }])
+  })
+})
+
+describe('ElevenLabs parseElevenLabsStream', () => {
+  function createNdjsonStream(lines: object[]): ReadableStream<Uint8Array> {
+    const text = lines.map((l) => JSON.stringify(l)).join('\n')
+    const encoder = new TextEncoder()
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode(text))
+        controller.close()
+      },
+    })
+  }
+
+  it('parses audio chunks and alignment', async () => {
+    const lines = [
+      {
+        audio_base64: Buffer.from([1, 2, 3]).toString('base64'),
+        normalized_alignment: {
+          characters: ['H', 'i'],
+          character_start_times_seconds: [0, 0.1],
+          character_end_times_seconds: [0.1, 0.2],
+        },
+      },
+      { audio_base64: Buffer.from([4, 5, 6]).toString('base64') },
+    ]
+
+    const result = await parseElevenLabsStream(createNdjsonStream(lines))
+
+    expect(result.audioChunks.length).toBe(2)
+    expect(result.alignment).toEqual({
+      characters: ['H', 'i'],
+      character_start_times_seconds: [0, 0.1],
+      character_end_times_seconds: [0.1, 0.2],
+    })
+  })
+
+  it('handles stream with no alignment', async () => {
+    const lines = [
+      { audio_base64: Buffer.from([1, 2, 3]).toString('base64') },
+    ]
+
+    const result = await parseElevenLabsStream(createNdjsonStream(lines))
+
+    expect(result.audioChunks.length).toBe(1)
+    expect(result.alignment).toBeUndefined()
+  })
+
+  it('prefers normalized_alignment over alignment', async () => {
+    const lines = [
+      {
+        audio_base64: Buffer.from([1]).toString('base64'),
+        alignment: {
+          characters: ['4', '2'],
+          character_start_times_seconds: [0, 0.1],
+          character_end_times_seconds: [0.1, 0.2],
+        },
+        normalized_alignment: {
+          characters: ['f', 'o', 'r', 't', 'y', ' ', 't', 'w', 'o'],
+          character_start_times_seconds: [0, 0.02, 0.04, 0.06, 0.08, 0.1, 0.12, 0.14, 0.16],
+          character_end_times_seconds: [0.02, 0.04, 0.06, 0.08, 0.1, 0.12, 0.14, 0.16, 0.18],
+        },
+      },
+    ]
+
+    const result = await parseElevenLabsStream(createNdjsonStream(lines))
+
+    expect(result.alignment!.characters[0]).toBe('f') // normalized, not '4'
+  })
+})
+
+describe('Cartesia parseCartesiaSseStream', () => {
+  function createSseStream(events: string[]): ReadableStream<Uint8Array> {
+    const text = events.map((e) => `data: ${e}\n\n`).join('')
+    const encoder = new TextEncoder()
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode(text))
+        controller.close()
+      },
+    })
+  }
+
+  it('parses audio chunks and timestamps', async () => {
+    const events = [
+      JSON.stringify({ type: 'chunk', done: false, status_code: 206, data: 'AAAA', step_time: 10 }),
+      JSON.stringify({
+        type: 'timestamps', done: false, status_code: 206,
+        word_timestamps: { words: ['Hello', 'world'], start: [0, 0.5], end: [0.4, 0.9] },
+      }),
+      JSON.stringify({ type: 'chunk', done: false, status_code: 206, data: 'BBBB', step_time: 10 }),
+      JSON.stringify({ type: 'done', done: true, status_code: 206 }),
+    ]
+
+    const result = await parseCartesiaSseStream(createSseStream(events))
+
+    expect(result.audioChunks.length).toBe(2)
+    expect(result.timestamps).toEqual([
+      { word: 'Hello', startSecond: 0, endSecond: 0.4 },
+      { word: 'world', startSecond: 0.5, endSecond: 0.9 },
+    ])
+  })
+
+  it('handles stream with no timestamps', async () => {
+    const events = [
+      JSON.stringify({ type: 'chunk', done: false, status_code: 206, data: 'AAAA', step_time: 10 }),
+      JSON.stringify({ type: 'done', done: true, status_code: 206 }),
+    ]
+
+    const result = await parseCartesiaSseStream(createSseStream(events))
+
+    expect(result.audioChunks.length).toBe(1)
+    expect(result.timestamps).toEqual([])
+  })
+
+  it('throws on error events', async () => {
+    const events = [
+      JSON.stringify({ type: 'error', done: true, status_code: 400, message: 'Invalid model', title: 'Bad Request' }),
+    ]
+
+    await expect(parseCartesiaSseStream(createSseStream(events)))
+      .rejects.toThrow('Cartesia TTS SSE error 400: Invalid model')
+  })
+
+  it('handles multiple timestamp events', async () => {
+    const events = [
+      JSON.stringify({
+        type: 'timestamps', done: false, status_code: 206,
+        word_timestamps: { words: ['Hello'], start: [0], end: [0.4] },
+      }),
+      JSON.stringify({
+        type: 'timestamps', done: false, status_code: 206,
+        word_timestamps: { words: ['world'], start: [0.5], end: [0.9] },
+      }),
+      JSON.stringify({ type: 'done', done: true, status_code: 206 }),
+    ]
+
+    const result = await parseCartesiaSseStream(createSseStream(events))
+
+    expect(result.timestamps).toEqual([
+      { word: 'Hello', startSecond: 0, endSecond: 0.4 },
+      { word: 'world', startSecond: 0.5, endSecond: 0.9 },
+    ])
+  })
+})

package/src/cli/transcription-catalog.ts

@@ -0,0 +1,250 @@
+// Transcription (speech-to-text) model catalog — single source of truth.
+// Mirrors the speech catalog pattern: every model's provider, pricing,
+// features live here. Other modules derive their data from this catalog.
+//
+// Pricing sources:
+//   OpenAI:      https://platform.openai.com/docs/pricing (per minute of audio)
+//   ElevenLabs:  https://elevenlabs.io/pricing
+//   Deepgram:    https://deepgram.com/pricing
+//   Groq:        https://groq.com/pricing
+
+import type { ProviderOption } from './model-catalog.js'
+
+// ─── cost types ──────────────────────────────────────────────────────────────
+
+export type PerSecondCost = {
+  type: 'per-second'
+  /** USD per second of audio */
+  perSecond: number
+}
+
+export type TranscriptionModelCost = PerSecondCost
+
+// ─── feature types ───────────────────────────────────────────────────────────
+
+export type TranscriptionModelFeatures = {
+  /** Whether word-level timestamps are returned */
+  wordTimestamps: boolean
+  /** Whether speaker diarization is supported */
+  diarization: boolean
+  /** Whether language detection is automatic */
+  languageDetection: boolean
+  /** Whether a language hint can be provided */
+  languageHint: boolean
+  /** Supported input audio formats */
+  inputFormats: string[]
+  /** Max audio duration in seconds (0 = unknown/unlimited) */
+  maxDurationSec: number
+}
+
+// ─── entry type ──────────────────────────────────────────────────────────────
+
+export type TranscriptionModelEntry = {
+  id: string
+  name: string
+  description?: string
+  provider: string
+  strategy: 'transcription'
+  released: string
+  cost: TranscriptionModelCost
+  features: TranscriptionModelFeatures
+  providerOptions?: ProviderOption[]
+}
+
+// ─── shared fragments ────────────────────────────────────────────────────────
+
+const openaiBase = {
+  provider: 'openai',
+  strategy: 'transcription' as const,
+}
+
+const elevenlabsBase = {
+  provider: 'elevenlabs',
+  strategy: 'transcription' as const,
+}
+
+const deepgramBase = {
+  provider: 'deepgram',
+  strategy: 'transcription' as const,
+}
+
+const groqBase = {
+  provider: 'groq',
+  strategy: 'transcription' as const,
+}
+
+const cartesiaBase = {
+  provider: 'cartesia',
+  strategy: 'transcription' as const,
+}
+
+const commonInputFormats = ['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm', 'ogg', 'flac']
+
+// ─── catalog ─────────────────────────────────────────────────────────────────
+
+export const TRANSCRIPTION_CATALOG: TranscriptionModelEntry[] = [
+  // ── OpenAI ─────────────────────────────────────────────────────────────
+  {
+    id: 'whisper-1',
+    name: 'Whisper v1',
+    description: 'OpenAI Whisper large-v2 model. Reliable, supports 57 languages.',
+    ...openaiBase,
+    released: '2023-03',
+    cost: { type: 'per-second', perSecond: 0.0001 }, // $0.006/min
+    features: {
+      wordTimestamps: true,
+      diarization: false,
+      languageDetection: true,
+      languageHint: true,
+      inputFormats: commonInputFormats,
+      maxDurationSec: 0,
+    },
+  },
+  {
+    id: 'gpt-4o-transcribe',
+    name: 'GPT-4o Transcribe',
+    description: 'GPT-4o powered transcription. Better accuracy than Whisper on complex audio. No word timestamps (OpenAI API only supports response_format=json for this model, verbose_json is required for timestamps).',
+    ...openaiBase,
+    released: '2025-03',
+    cost: { type: 'per-second', perSecond: 0.0001 }, // $0.006/min
+    features: {
+      // OpenAI API limitation: gpt-4o-transcribe only supports response_format=json,
+      // not verbose_json. Word timestamps require verbose_json.
+      wordTimestamps: false,
+      diarization: false,
+      languageDetection: true,
+      languageHint: true,
+      inputFormats: commonInputFormats,
+      maxDurationSec: 0,
+    },
+  },
+  {
+    id: 'gpt-4o-mini-transcribe',
+    name: 'GPT-4o Mini Transcribe',
+    description: 'GPT-4o Mini powered transcription. Cheaper, still better than Whisper. No word timestamps (same OpenAI API limitation as gpt-4o-transcribe).',
+    ...openaiBase,
+    released: '2025-03',
+    cost: { type: 'per-second', perSecond: 0.00005 }, // $0.003/min
+    features: {
+      // Same OpenAI API limitation as gpt-4o-transcribe.
+      wordTimestamps: false,
+      diarization: false,
+      languageDetection: true,
+      languageHint: true,
+      inputFormats: commonInputFormats,
+      maxDurationSec: 0,
+    },
+  },
+
+  // ── ElevenLabs ─────────────────────────────────────────────────────────
+  {
+    id: 'scribe_v1',
+    name: 'ElevenLabs Scribe v1',
+    description: 'ElevenLabs speech-to-text with word-level timestamps and speaker diarization.',
+    ...elevenlabsBase,
+    released: '2024-12',
+    cost: { type: 'per-second', perSecond: 0.0001 },
+    features: {
+      wordTimestamps: true,
+      diarization: true,
+      languageDetection: true,
+      languageHint: true,
+      inputFormats: commonInputFormats,
+      maxDurationSec: 0,
+    },
+  },
+
+  // ── Deepgram ───────────────────────────────────────────────────────────
+  {
+    id: 'nova-3',
+    name: 'Deepgram Nova 3',
+    description: 'Deepgram Nova 3. Fast and accurate with word-level timestamps and diarization.',
+    ...deepgramBase,
+    released: '2025-01',
+    cost: { type: 'per-second', perSecond: 0.0000717 }, // $0.0043/min
+    features: {
+      wordTimestamps: true,
+      diarization: true,
+      languageDetection: true,
+      languageHint: true,
+      inputFormats: commonInputFormats,
+      maxDurationSec: 0,
+    },
+  },
+
+  // ── Groq ───────────────────────────────────────────────────────────────
+  {
+    id: 'whisper-large-v3',
+    name: 'Whisper Large v3 (Groq)',
+    description: 'Whisper large-v3 on Groq. Extremely fast inference with word-level timestamps.',
+    ...groqBase,
+    released: '2024-01',
+    cost: { type: 'per-second', perSecond: 0.00000185 }, // $0.000111/min
+    features: {
+      wordTimestamps: true,
+      diarization: false,
+      languageDetection: true,
+      languageHint: true,
+      inputFormats: commonInputFormats,
+      maxDurationSec: 7200,
+    },
+  },
+  {
+    id: 'whisper-large-v3-turbo',
+    name: 'Whisper Large v3 Turbo (Groq)',
+    description: 'Whisper large-v3-turbo on Groq. Faster variant with slightly less accuracy.',
+    ...groqBase,
+    released: '2024-06',
+    cost: { type: 'per-second', perSecond: 0.000000667 }, // $0.00004/min
+    features: {
+      wordTimestamps: true,
+      diarization: false,
+      languageDetection: true,
+      languageHint: true,
+      inputFormats: commonInputFormats,
+      maxDurationSec: 7200,
+    },
+  },
+  {
+    id: 'distil-whisper-large-v3-en',
+    name: 'Distil Whisper Large v3 EN (Groq)',
+    description: 'Distilled English-only Whisper on Groq. Cheapest option, English only.',
+    ...groqBase,
+    released: '2024-01',
+    cost: { type: 'per-second', perSecond: 0.000000333 }, // $0.00002/min
+    features: {
+      wordTimestamps: true,
+      diarization: false,
+      languageDetection: false,
+      languageHint: false,
+      inputFormats: commonInputFormats,
+      maxDurationSec: 7200,
+    },
+  },
+
+  // ── Cartesia ───────────────────────────────────────────────────────────
+  // Pricing: 1 credit per 2 seconds of audio on /stt batch endpoint.
+  // At Startup plan ($49/1.25M credits) ≈ $0.00002/sec.
+  {
+    id: 'ink-whisper',
+    name: 'Cartesia Ink Whisper',
+    description: 'Cartesia batch STT. Word-level timestamps, 99+ languages. Based on Whisper.',
+    ...cartesiaBase,
+    released: '2026-01',
+    cost: { type: 'per-second', perSecond: 0.00002 },
+    features: {
+      wordTimestamps: true,
+      diarization: false,
+      languageDetection: false,
+      languageHint: true,
+      inputFormats: ['mp3', 'mp4', 'm4a', 'wav', 'webm', 'ogg', 'flac'],
+      maxDurationSec: 0,
+    },
+  },
+]
+
+// ─── lookup helpers ──────────────────────────────────────────────────────────
+
+export function findTranscriptionModel(modelId: string): TranscriptionModelEntry | undefined {
+  return TRANSCRIPTION_CATALOG.find((m) => m.id === modelId)
+}

package/src/cli/transcription-generate.ts

@@ -0,0 +1,214 @@
+// Programmatic API for egaki audio transcription (speech-to-text).
+// Returns Error | Result (errore style) instead of process.exit/console.error.
+//
+// Two variants:
+//   - `transcribeAudio(opts)` — cached, writes JSON to public/generated/transcription/, returns WordTimestamp[]
+//   - `transcribeAudioUncached(opts)` — raw, returns TranscribeResult with text + segments
+//
+// Uses direct HTTP calls to each provider API (no AI SDK dependency).
+// Each provider implementation lives in transcription-providers.ts.
+//
+// Usage:
+//   import { transcribeAudio, transcribeAudioUncached } from 'egaki/generate'
+//   const cached = await transcribeAudio({ audio: fs.readFileSync('audio.mp3') })
+//   if (!(cached instanceof Error)) cached // WordTimestamp[]
+//   const raw = await transcribeAudioUncached({ audio: fs.readFileSync('audio.mp3') })
+//   if (!(raw instanceof Error)) raw.text // full transcript
+import { injectCredentialsToEnv } from './credentials.js'
+import {
+  getTranscriptionModelConfig,
+  getTranscriptionProvider,
+  DEFAULT_TRANSCRIPTION_MODEL,
+} from './transcription-models.js'
+
+// ─── autocomplete-friendly union types ───────────────────────────────────────
+
+/** Transcription model IDs from the catalog. Accepts arbitrary strings too. */
+export type TranscriptionModelId =
+  | 'whisper-1' | 'gpt-4o-transcribe' | 'gpt-4o-mini-transcribe'
+  | 'scribe_v1'
+  | 'nova-3'
+  | 'whisper-large-v3' | 'whisper-large-v3-turbo' | 'distil-whisper-large-v3-en'
+  | 'ink-whisper'
+  | (string & {})
+
+// ─── public types ────────────────────────────────────────────────────────────
+
+export interface TranscribeOptions {
+  /** Audio data as a Uint8Array or Buffer. */
+  audio: Uint8Array
+  /** Transcription model ID. Defaults to 'whisper-1' if omitted. */
+  model?: TranscriptionModelId
+  /** ISO 639-1 language hint (e.g. "en", "es", "fr"). */
+  language?: string
+  /** Original audio filename, used as the human-readable cache file prefix. */
+  filename?: string
+}
+
+export interface TranscriptionSegment {
+  text: string
+  startSecond: number
+  endSecond: number
+}
+
+export interface TranscribeResult {
+  text: string
+  segments: TranscriptionSegment[]
+  language: string | undefined
+  durationInSeconds: number | undefined
+  model: string
+  cost: number | null
+}
+
+// ─── word-level timestamp types ──────────────────────────────────────────────
+
+/** A single word with its start/end time in seconds. */
+export interface WordTimestamp {
+  word: string
+  startSecond: number
+  endSecond: number
+}
+
+/**
+ * Convert TranscriptionSegment[] to WordTimestamp[].
+ *
+ * When segments are word-level (one word per segment), maps directly.
+ * When segments are phrase/sentence-level, splits by whitespace and
+ * distributes time evenly across words as a fallback.
+ */
+export function segmentsToWordTimestamps(segments: TranscriptionSegment[]): WordTimestamp[] {
+  const result: WordTimestamp[] = []
+  for (const seg of segments) {
+    const trimmed = seg.text.trim()
+    // Skip empty/whitespace-only segments (ElevenLabs returns space segments)
+    if (!trimmed) continue
+    const words = trimmed.split(/\s+/).filter(Boolean)
+    if (words.length <= 1) {
+      result.push({ word: trimmed, startSecond: seg.startSecond, endSecond: seg.endSecond })
+      continue
+    }
+    // Phrase-level segment: distribute time evenly across words
+    const duration = seg.endSecond - seg.startSecond
+    const wordDuration = duration / words.length
+    for (let i = 0; i < words.length; i++) {
+      result.push({
+        word: words[i]!,
+        startSecond: seg.startSecond + i * wordDuration,
+        endSecond: seg.startSecond + (i + 1) * wordDuration,
+      })
+    }
+  }
+  return result
+}
+
+/**
+ * Convert WordTimestamp[] to @remotion/captions Caption[] format.
+ * First word has no leading space; subsequent words get a leading space
+ * (required by createTikTokStyleCaptions).
+ */
+export function wordTimestampsToCaptions(words: WordTimestamp[]): Array<{
+  text: string
+  startMs: number
+  endMs: number
+  timestampMs: number
+  confidence: number
+}> {
+  return words.map((w, i) => ({
+    text: i === 0 ? w.word : ` ${w.word}`,
+    startMs: w.startSecond * 1000,
+    endMs: w.endSecond * 1000,
+    timestampMs: ((w.startSecond + w.endSecond) / 2) * 1000,
+    confidence: 1,
+  }))
+}
+
+// ─── cost calculation ────────────────────────────────────────────────────────
+
+export function calculateTranscriptionCost(
+  cost: { type: 'per-second'; perSecond: number },
+  durationInSeconds: number | undefined,
+): number | null {
+  if (durationInSeconds == null) return null
+  return durationInSeconds * cost.perSecond
+}
+
+// ─── transcribeAudioUncached ─────────────────────────────────────────────────
+
+/**
+ * Transcribe audio to text. Auto-detects which provider to use
+ * based on model ID. Shares credentials with the CLI.
+ */
+export async function transcribeAudioUncached(opts: TranscribeOptions): Promise<Error | TranscribeResult> {
+  injectCredentialsToEnv()
+
+  const model = opts.model ?? DEFAULT_TRANSCRIPTION_MODEL
+  const config = getTranscriptionModelConfig(model)
+  if (config instanceof Error) return config
+
+  if (opts.language && !config.features.languageHint) {
+    return new Error(`Model ${model} does not support a language hint`)
+  }
+
+  const provider = getTranscriptionProvider(config.provider)
+  if (provider instanceof Error) return provider
+
+  let result
+  try {
+    result = await provider.transcribe({
+      audio: opts.audio,
+      modelId: model,
+      language: opts.language,
+    })
+  } catch (err) {
+    return err instanceof Error ? err : new Error(String(err))
+  }
+
+  const cost = calculateTranscriptionCost(config.cost, result.durationInSeconds)
+
+  return {
+    text: result.text,
+    segments: result.segments,
+    language: result.language,
+    durationInSeconds: result.durationInSeconds,
+    model,
+    cost,
+  }
+}
+
+// ─── cached transcribeAudio ─────────────────────────────────────────────────
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { cachedGenerate } from './cached-generate.js'
+
+export const transcribeAudio = cachedGenerate<TranscribeOptions, { wordTimestamps: WordTimestamp[]; text: string }, WordTimestamp[]>({
+  namespace: 'transcription',
+  prefixFrom: (p) => {
+    if (p.filename) {
+      const ext = path.extname(p.filename)
+      return path.basename(p.filename, ext)
+    }
+    return 'transcription'
+  },
+  // Exclude filename from cache key — it only affects the human-readable prefix,
+  // not the identity of the transcription result.
+  cacheKey: ({ filename, ...rest }) => rest as Record<string, unknown>,
+  modelFrom: (p) => p.model,
+  generate: async (params) => {
+    const result = await transcribeAudioUncached(params)
+    if (result instanceof Error) throw result
+    return {
+      wordTimestamps: segmentsToWordTimestamps(result.segments),
+      text: result.text,
+    }
+  },
+  serialize: (result) => ({
+    json: result.wordTimestamps,
+    extension: '.json',
+    // Use the transcript text as a more readable filename prefix
+    prefix: result.text || undefined,
+  }),
+  deserialize: ({ filePath }) => {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'))
+  },
+})