egaki 0.5.0 → 0.7.0

package/src/cli/speech-catalog.ts

@@ -0,0 +1,253 @@
+// Speech model catalog — single source of truth for all TTS models.
+// Mirrors the image/video catalog pattern: every model's provider, pricing,
+// features, and default voices live here. Other modules derive their data
+// from this catalog.
+//
+// Pricing sources:
+//   OpenAI:      https://platform.openai.com/docs/pricing (per 1M characters)
+//   ElevenLabs:  https://elevenlabs.io/pricing (per 1K characters, varies by plan)
+//   Cartesia:    https://cartesia.ai/pricing (plan-based, ~1 credit per character)
+
+import type { ProviderOption } from './model-catalog.js'
+
+// ─── cost types ──────────────────────────────────────────────────────────────
+
+export type PerCharacterCost = {
+  type: 'per-character'
+  /** USD per 1 million characters */
+  perMillionChars: number
+}
+
+export type SpeechModelCost = PerCharacterCost
+
+// ─── feature types ───────────────────────────────────────────────────────────
+
+export type SpeechModelFeatures = {
+  /** Supported output audio formats */
+  outputFormats: string[]
+  /** Whether the model supports voice instructions / style prompts */
+  instructions: boolean
+  /** Whether speed control is supported */
+  speed: boolean
+  /** Whether language selection is supported */
+  language: boolean
+  /** Max input characters per request (0 = unknown/unlimited) */
+  maxChars: number
+  /** Built-in voice names (not exhaustive for providers with voice libraries) */
+  defaultVoices: string[]
+}
+
+// ─── entry type ──────────────────────────────────────────────────────────────
+
+export type SpeechModelEntry = {
+  id: string
+  name: string
+  description?: string
+  provider: string
+  strategy: 'speech'
+  released: string
+  cost: SpeechModelCost
+  features: SpeechModelFeatures
+  providerOptions?: ProviderOption[]
+}
+
+// ─── shared fragments ────────────────────────────────────────────────────────
+
+const openaiSpeechBase = {
+  provider: 'openai',
+  strategy: 'speech' as const,
+}
+
+const elevenlabsSpeechBase = {
+  provider: 'elevenlabs',
+  strategy: 'speech' as const,
+}
+
+const cartesiaSpeechBase = {
+  provider: 'cartesia',
+  strategy: 'speech' as const,
+}
+
+// ─── catalog ─────────────────────────────────────────────────────────────────
+
+export const SPEECH_CATALOG: SpeechModelEntry[] = [
+  // ── OpenAI ─────────────────────────────────────────────────────────────
+  {
+    id: 'tts-1',
+    name: 'TTS-1 (Standard)',
+    description: 'OpenAI standard text-to-speech. Low latency, good for real-time use.',
+    ...openaiSpeechBase,
+    released: '2023-11',
+    cost: { type: 'per-character', perMillionChars: 15 },
+    features: {
+      outputFormats: ['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm'],
+      instructions: false,
+      speed: true,
+      language: false,
+      maxChars: 4096,
+      defaultVoices: ['alloy', 'ash', 'coral', 'echo', 'fable', 'onyx', 'nova', 'sage', 'shimmer'],
+    },
+  },
+  {
+    id: 'tts-1-hd',
+    name: 'TTS-1 HD',
+    description: 'OpenAI high-definition text-to-speech. Higher fidelity audio.',
+    ...openaiSpeechBase,
+    released: '2023-11',
+    cost: { type: 'per-character', perMillionChars: 30 },
+    features: {
+      outputFormats: ['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm'],
+      instructions: false,
+      speed: true,
+      language: false,
+      maxChars: 4096,
+      defaultVoices: ['alloy', 'ash', 'coral', 'echo', 'fable', 'onyx', 'nova', 'sage', 'shimmer'],
+    },
+  },
+  {
+    id: 'gpt-4o-mini-tts',
+    name: 'GPT-4o Mini TTS',
+    description:
+      'OpenAI GPT-4o Mini with text-to-speech. Supports style instructions ' +
+      'for expressive speech control.',
+    ...openaiSpeechBase,
+    released: '2025-03',
+    cost: { type: 'per-character', perMillionChars: 12 },
+    features: {
+      outputFormats: ['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm'],
+      instructions: true,
+      speed: true,
+      language: false,
+      maxChars: 2000,
+      defaultVoices: [
+        'alloy', 'ash', 'ballad', 'cedar', 'coral', 'echo',
+        'fable', 'marin', 'nova', 'onyx', 'sage', 'shimmer', 'verse',
+      ],
+    },
+  },
+
+  // ── ElevenLabs ─────────────────────────────────────────────────────────
+  {
+    id: 'eleven_v3',
+    name: 'ElevenLabs v3',
+    description: 'Latest ElevenLabs model with best quality and expressiveness.',
+    ...elevenlabsSpeechBase,
+    released: '2025-06',
+    cost: { type: 'per-character', perMillionChars: 100 },
+    features: {
+      outputFormats: ['mp3_44100_128', 'mp3_22050_32', 'pcm_16000', 'pcm_22050', 'pcm_24000', 'pcm_44100', 'ulaw_8000'],
+      instructions: false,
+      speed: false,
+      language: true,
+      maxChars: 0,
+      defaultVoices: [],
+    },
+  },
+  {
+    id: 'eleven_multilingual_v2',
+    name: 'ElevenLabs Multilingual v2',
+    description: 'ElevenLabs multilingual model. Supports 29 languages.',
+    ...elevenlabsSpeechBase,
+    released: '2024-01',
+    cost: { type: 'per-character', perMillionChars: 100 },
+    features: {
+      outputFormats: ['mp3_44100_128', 'mp3_22050_32', 'pcm_16000', 'pcm_22050', 'pcm_24000', 'pcm_44100', 'ulaw_8000'],
+      instructions: false,
+      speed: false,
+      language: true,
+      maxChars: 0,
+      defaultVoices: [],
+    },
+  },
+  {
+    id: 'eleven_flash_v2_5',
+    name: 'ElevenLabs Flash v2.5',
+    description: 'ElevenLabs low-latency model optimized for speed.',
+    ...elevenlabsSpeechBase,
+    released: '2024-08',
+    cost: { type: 'per-character', perMillionChars: 50 },
+    features: {
+      outputFormats: ['mp3_44100_128', 'mp3_22050_32', 'pcm_16000', 'pcm_22050', 'pcm_24000', 'pcm_44100', 'ulaw_8000'],
+      instructions: false,
+      speed: false,
+      language: true,
+      maxChars: 0,
+      defaultVoices: [],
+    },
+  },
+  {
+    id: 'eleven_turbo_v2_5',
+    name: 'ElevenLabs Turbo v2.5',
+    description: 'ElevenLabs turbo model. Balanced quality and speed.',
+    ...elevenlabsSpeechBase,
+    released: '2024-06',
+    cost: { type: 'per-character', perMillionChars: 50 },
+    features: {
+      outputFormats: ['mp3_44100_128', 'mp3_22050_32', 'pcm_16000', 'pcm_22050', 'pcm_24000', 'pcm_44100', 'ulaw_8000'],
+      instructions: false,
+      speed: false,
+      language: true,
+      maxChars: 0,
+      defaultVoices: [],
+    },
+  },
+
+
+  // ── Cartesia ───────────────────────────────────────────────────────────
+  // Pricing is plan-based (~1 credit per character). The per-million rate
+  // below is estimated from the Startup plan ($49/1.25M credits ≈ $39/M).
+  // See https://cartesia.ai/pricing for current plans.
+  {
+    id: 'sonic-3.5',
+    name: 'Cartesia Sonic 3.5',
+    description:
+      'Fastest, most natural Cartesia TTS. #1 for naturalness, sub-90ms latency, ' +
+      '42 languages. Recommended for production.',
+    ...cartesiaSpeechBase,
+    released: '2026-05',
+    cost: { type: 'per-character', perMillionChars: 39 },
+    features: {
+      outputFormats: ['mp3', 'wav', 'raw'],
+      instructions: false,
+      speed: true,
+      language: true,
+      maxChars: 0,
+      defaultVoices: [
+        'f786b574-daa5-4673-aa0c-cbe3e8534c02', // Katie (en-US Female)
+        'db6b0ed5-d5d3-463d-ae85-518a07d3c2b4', // Skylar (en-US Female)
+        'a5136bf9-224c-4d76-b823-52bd5efcffcc', // Jameson (en-US Male)
+        '62ae83ad-4f6a-430b-af41-a9bede9286ca', // Gemma (en-GB Female)
+        'ef191366-f52f-447a-a398-ed8c0f2943a1', // Archie (en-GB Male)
+      ],
+    },
+  },
+  {
+    id: 'sonic-3',
+    name: 'Cartesia Sonic 3',
+    description:
+      'Previous generation Cartesia TTS. Still high quality with pronunciation ' +
+      'dictionaries support.',
+    ...cartesiaSpeechBase,
+    released: '2025-01',
+    cost: { type: 'per-character', perMillionChars: 39 },
+    features: {
+      outputFormats: ['mp3', 'wav', 'raw'],
+      instructions: false,
+      speed: true,
+      language: true,
+      maxChars: 0,
+      defaultVoices: [
+        'f786b574-daa5-4673-aa0c-cbe3e8534c02', // Katie (en-US Female)
+        'db6b0ed5-d5d3-463d-ae85-518a07d3c2b4', // Skylar (en-US Female)
+        'a5136bf9-224c-4d76-b823-52bd5efcffcc', // Jameson (en-US Male)
+      ],
+    },
+  },
+
+]
+
+// ─── lookup helpers ──────────────────────────────────────────────────────────
+
+export function findSpeechModel(modelId: string): SpeechModelEntry | undefined {
+  return SPEECH_CATALOG.find((m) => m.id === modelId)
+}

package/src/cli/speech-generate.ts

@@ -0,0 +1,275 @@
+// Programmatic API for egaki speech generation.
+// Returns Error | Result (errore style) instead of process.exit/console.error.
+//
+// Two variants:
+//   - `generateSpeech(opts)` — cached, writes to public/generated/audio/, returns { src }
+//   - `generateSpeechUncached(opts)` — raw, returns bytes in GenerateSpeechResult
+//
+// Uses our own SpeechProvider interface instead of the Vercel AI SDK's
+// experimental_generateSpeech. This lets providers return word-level timestamps
+// alongside audio (ElevenLabs /with-timestamps, Cartesia /tts/sse).
+//
+// Usage:
+//   import { generateSpeech, generateSpeechUncached } from 'egaki/generate'
+//   const cached = await generateSpeech({ text: 'Hello world' })
+//   if (!(cached instanceof Error)) cached.src // '/generated/audio/hello-world-a1b2c3d4.mp3'
+//   const raw = await generateSpeechUncached({ text: 'Hello world' })
+//   if (!(raw instanceof Error)) raw.audio.uint8Array // raw bytes
+//   if (raw.timestamps) raw.timestamps[0] // { word: 'Hello', startSecond: 0, endSecond: 0.4 }
+import { injectCredentialsToEnv } from './credentials.js'
+import {
+  getSpeechModelConfig,
+  getSpeechProvider,
+  DEFAULT_SPEECH_MODEL,
+} from './speech-models.js'
+import type { GeneratedFile } from './generate.js'
+import type { WordTimestamp } from './transcription-generate.js'
+
+export type { WordTimestamp }
+
+// ─── SpeechProvider interface ────────────────────────────────────────────────
+// Each provider implements this to generate audio + optional word timestamps.
+
+export interface SpeechProviderResult {
+  audio: Uint8Array
+  mediaType: string
+  /** Word-level timestamps, if the provider supports them. */
+  timestamps?: WordTimestamp[]
+}
+
+export interface SpeechProviderOptions {
+  text: string
+  modelId: string
+  voice?: string
+  outputFormat?: string
+  instructions?: string
+  speed?: number
+  language?: string
+  abortSignal?: AbortSignal
+}
+
+export interface SpeechProvider {
+  generate(options: SpeechProviderOptions): Promise<SpeechProviderResult>
+}
+
+// ─── autocomplete-friendly union types ───────────────────────────────────────
+
+/** Speech model IDs from the catalog. Accepts arbitrary strings too. */
+export type SpeechModelId =
+  | 'tts-1' | 'tts-1-hd' | 'gpt-4o-mini-tts'
+  | 'eleven_v3' | 'eleven_multilingual_v2' | 'eleven_flash_v2_5' | 'eleven_turbo_v2_5'
+  | 'sonic-3.5' | 'sonic-3'
+  | (string & {})
+
+/** Built-in voice presets across providers. Accepts arbitrary strings too. */
+export type SpeechVoice =
+  | 'alloy' | 'ash' | 'coral' | 'echo' | 'fable' | 'onyx' | 'nova' | 'sage' | 'shimmer' | 'ballad' | 'cedar' | 'marin' | 'verse'
+  | (string & {})
+
+/** Audio output formats. */
+export type AudioOutputFormat = 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm' | 'raw' | (string & {})
+
+// ─── public types ────────────────────────────────────────────────────────────
+
+export interface GenerateSpeechOptions {
+  /** The text to convert to speech. */
+  text: string
+  /** Speech model ID. Defaults to DEFAULT_SPEECH_MODEL ('tts-1') if omitted. */
+  model?: SpeechModelId
+  /** Voice ID or name (provider-specific). */
+  voice?: SpeechVoice
+  /** Output audio format: mp3, wav, pcm, opus, aac, flac, etc. */
+  outputFormat?: AudioOutputFormat
+  /** Style instructions for models that support it (e.g. gpt-4o-mini-tts). */
+  instructions?: string
+  /**
+   * Playback speed multiplier. `1.0` is normal speed; values below slow
+   * down, values above speed up.
+   *
+   * Accepted ranges vary by provider:
+   *
+   * | Provider    | Range       | Notes                                                        |
+   * |-------------|-------------|--------------------------------------------------------------|
+   * | OpenAI      | 0.25 – 4.0  | Works with `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`.          |
+   * | ElevenLabs  | 0.25 – 4.0  | Passed as `voice_settings.speed`. Extreme values degrade     |
+   * |             |             | quality. Flash/turbo models may ignore it.                   |
+   * | Cartesia    | 0.6 – 1.5   | Passed as `generation_config.speed`. Sonic models treat it   |
+   * |             |             | as guidance, not an exact multiplier.                        |
+   *
+   * @default 1.0
+   */
+  speed?: number
+  /** ISO 639-1 language code (e.g. "en", "es", "fr"). */
+  language?: string
+  /** Abort signal for cancelling the request. */
+  abortSignal?: AbortSignal
+}
+
+export interface GenerateSpeechResult {
+  audio: GeneratedFile
+  model: string
+  cost: number | null
+  /** Word-level timestamps, if the provider supports them (ElevenLabs, Cartesia). */
+  timestamps?: WordTimestamp[]
+}
+
+// ─── cost calculation ────────────────────────────────────────────────────────
+
+export function calculateSpeechCost(
+  cost: { type: 'per-character'; perMillionChars: number },
+  textLength: number,
+): number {
+  return (textLength / 1_000_000) * cost.perMillionChars
+}
+
+// ─── media type inference ────────────────────────────────────────────────────
+
+function inferAudioMediaType(format?: string): string {
+  switch (format) {
+    case 'mp3':
+      return 'audio/mpeg'
+    case 'wav':
+      return 'audio/wav'
+    case 'pcm':
+    case 'raw':
+      return 'audio/pcm'
+    case 'opus':
+      return 'audio/opus'
+    case 'aac':
+      return 'audio/aac'
+    case 'flac':
+      return 'audio/flac'
+    default:
+      return 'audio/mpeg'
+  }
+}
+
+function inferMediaTypeFromBytes(audio: Uint8Array, requestedFormat?: string): string {
+  // Check magic bytes first
+  if (audio.length >= 3 && audio[0] === 0x49 && audio[1] === 0x44 && audio[2] === 0x33) {
+    return 'audio/mpeg' // ID3 header (MP3)
+  }
+  if (audio.length >= 2 && audio[0] === 0xff && (audio[1]! & 0xe0) === 0xe0) {
+    return 'audio/mpeg' // MP3 sync word
+  }
+  if (audio.length >= 4 && audio[0] === 0x52 && audio[1] === 0x49 && audio[2] === 0x46 && audio[3] === 0x46) {
+    return 'audio/wav' // RIFF header
+  }
+  if (audio.length >= 4 && audio[0] === 0x4f && audio[1] === 0x67 && audio[2] === 0x67 && audio[3] === 0x53) {
+    return 'audio/ogg' // OggS header (could be opus)
+  }
+  if (audio.length >= 4 && audio[0] === 0x66 && audio[1] === 0x4c && audio[2] === 0x61 && audio[3] === 0x43) {
+    return 'audio/flac' // fLaC header
+  }
+  // Fall back to requested format
+  return inferAudioMediaType(requestedFormat)
+}
+
+// ─── generateSpeech ──────────────────────────────────────────────────────────
+
+/**
+ * Generate speech audio from text. Auto-detects which provider to use
+ * based on model ID. Shares credentials and subscription with the CLI.
+ * Returns word-level timestamps when the provider supports them.
+ */
+export async function generateSpeechUncached(opts: GenerateSpeechOptions): Promise<Error | GenerateSpeechResult> {
+  injectCredentialsToEnv()
+
+  const model = opts.model ?? DEFAULT_SPEECH_MODEL
+  const config = getSpeechModelConfig(model)
+  if (config instanceof Error) return config
+
+  const provider = getSpeechProvider(config.provider)
+  if (provider instanceof Error) return provider
+
+  let result: SpeechProviderResult
+  try {
+    result = await provider.generate({
+      text: opts.text,
+      modelId: model,
+      voice: opts.voice,
+      outputFormat: opts.outputFormat,
+      instructions: opts.instructions,
+      speed: opts.speed,
+      language: opts.language,
+      abortSignal: opts.abortSignal,
+    })
+  } catch (err) {
+    return err instanceof Error ? err : new Error(String(err))
+  }
+
+  const mediaType = result.mediaType || inferMediaTypeFromBytes(result.audio, opts.outputFormat)
+  const cost = calculateSpeechCost(config.cost, opts.text.length)
+
+  return {
+    audio: { uint8Array: result.audio, mediaType },
+    model,
+    cost,
+    timestamps: result.timestamps,
+  }
+}
+
+// ─── cached generateSpeech ──────────────────────────────────────────────────
+// Writes audio to public/generated/audio/ and a sidecar .timestamps.json
+// next to it when the provider returns word timestamps. On cache hit,
+// the sidecar is read back to populate the result.
+//
+// Uses cachedGenerate with postWrite to write the timestamps sidecar after
+// the audio file, and deserialize to read it back on cache hit.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { cachedGenerate } from './cached-generate.js'
+import { extensionFromMediaType } from './cache-utils.js'
+
+/** Compute the sidecar timestamps path for an audio file.
+ *  Stored in a `timestamps/` subdirectory to avoid cache key collision:
+ *  findCachedFile() matches any filename containing the hash, so a sidecar
+ *  like `foo-hash.mp3.timestamps.json` in the same directory would be
+ *  mistakenly returned as the "cached audio" file. */
+function timestampsPathFor(filePath: string): string {
+  return path.join(path.dirname(filePath), 'timestamps', path.basename(filePath) + '.json')
+}
+
+export interface CachedSpeechResult {
+  src: string
+  timestamps?: WordTimestamp[]
+}
+
+/** Internal result carrying both audio bytes and optional timestamps. */
+interface SpeechGenerateOutput {
+  audio: GeneratedFile
+  timestamps?: WordTimestamp[]
+}
+
+export const generateSpeech = cachedGenerate<GenerateSpeechOptions & { seed?: number }, SpeechGenerateOutput, CachedSpeechResult>({
+  namespace: 'audio',
+  prefixFrom: (p) => p.text,
+  modelFrom: (p) => p.model,
+  generate: async (params) => {
+    const result = await generateSpeechUncached(params)
+    if (result instanceof Error) throw result
+    return { audio: result.audio, timestamps: result.timestamps }
+  },
+  serialize: (output) => ({
+    bytes: output.audio.uint8Array,
+    extension: extensionFromMediaType(output.audio.mediaType),
+  }),
+  postWrite: (filePath, output) => {
+    if (output.timestamps?.length) {
+      const tsPath = timestampsPathFor(filePath)
+      fs.mkdirSync(path.dirname(tsPath), { recursive: true })
+      fs.writeFileSync(tsPath, JSON.stringify(output.timestamps, null, 2))
+    }
+  },
+  deserialize: ({ urlPath, filePath }) => {
+    const tsPath = timestampsPathFor(filePath)
+    let timestamps: WordTimestamp[] | undefined
+    try {
+      if (fs.existsSync(tsPath)) {
+        timestamps = JSON.parse(fs.readFileSync(tsPath, 'utf-8'))
+      }
+    } catch { /* non-fatal: timestamps are optional */ }
+    return { src: urlPath, timestamps }
+  },
+})

package/src/cli/speech-models.ts

@@ -0,0 +1,146 @@
+// Speech model registry for egaki.
+// Maps speech model IDs to their provider and SpeechProvider factory.
+//
+// Provider resolution priority (same as image/video):
+//   1. Direct provider key → direct provider implementation
+//   2. Egaki API key → route through egaki gateway (future)
+//   3. No key → error with subscription recommendation
+import pc from 'picocolors'
+import type { SpeechProvider } from './speech-generate.js'
+import {
+  PROVIDERS,
+  injectCredentialsToEnv,
+} from './credentials.js'
+import { ValidationError } from './models.js'
+import {
+  SPEECH_CATALOG,
+  findSpeechModel,
+  type SpeechModelEntry,
+} from './speech-catalog.js'
+
+export { type SpeechModelEntry }
+
+export const DEFAULT_SPEECH_MODEL = 'tts-1'
+
+// ─── provider factory map ────────────────────────────────────────────────────
+
+type SpeechProviderFactory = () => Promise<SpeechProvider>
+
+const SPEECH_PROVIDER_FACTORIES: Record<string, SpeechProviderFactory> = {
+  openai: async () => {
+    const { createOpenAISpeechProvider } = await import('./openai-speech-provider.js')
+    return createOpenAISpeechProvider()
+  },
+  elevenlabs: async () => {
+    const { createElevenLabsSpeechProvider } = await import('./elevenlabs-speech-provider.js')
+    return createElevenLabsSpeechProvider()
+  },
+  cartesia: async () => {
+    const { createCartesiaSpeechProvider } = await import('./cartesia-provider.js')
+    return createCartesiaSpeechProvider()
+  },
+}
+
+// ─── key checking ────────────────────────────────────────────────────────────
+
+function hasDirectProviderKey(providerName: string): boolean {
+  const info = PROVIDERS[providerName]
+  if (!info) return false
+  return Boolean(process.env[info.envVar])
+}
+
+function hasEgakiKey(): boolean {
+  const info = PROVIDERS['egaki']
+  if (!info) return false
+  return Boolean(process.env[info.envVar])
+}
+
+// ─── config lookup ───────────────────────────────────────────────────────────
+
+export function getSpeechModelConfig(modelId: string): Error | SpeechModelEntry {
+  const entry = findSpeechModel(modelId)
+  if (!entry) {
+    return new ValidationError(`Unknown speech model: ${modelId}`)
+  }
+  return entry
+}
+
+// ─── auth source detection ───────────────────────────────────────────────────
+
+type AuthSource =
+  | { type: 'api-key'; label: string }
+  | { type: 'egaki-gateway' }
+
+function resolveAuthSource(providerName: string): AuthSource {
+  const info = PROVIDERS[providerName]
+  if (info && process.env[info.envVar]) {
+    return { type: 'api-key', label: info.envVar }
+  }
+  if (hasEgakiKey()) {
+    return { type: 'egaki-gateway' }
+  }
+  return { type: 'api-key', label: 'unknown' }
+}
+
+function logAuthSource(source: AuthSource): void {
+  switch (source.type) {
+    case 'api-key':
+      console.error(pc.dim(`Auth: ${source.label}`))
+      break
+    case 'egaki-gateway':
+      console.error(pc.dim('Auth: Egaki subscription (gateway)'))
+      break
+  }
+}
+
+// ─── ensure key ──────────────────────────────────────────────────────────────
+
+export function ensureSpeechProviderKey(providerName: string): Error | undefined {
+  if (hasDirectProviderKey(providerName)) return undefined
+
+  // Speech models don't go through the gateway yet (AI Gateway doesn't
+  // support speech routing). Direct provider key is required.
+  const info = PROVIDERS[providerName]
+  const label = info?.label || providerName
+  return new ValidationError(
+    `Missing API key for ${label}. ` +
+    `Run: egaki login --provider ${providerName} --key <key>. ` +
+    (info ? info.hint : ''),
+  )
+}
+
+// ─── provider cache ──────────────────────────────────────────────────────────
+
+/** Global cache of provider instances, keyed by provider name. */
+const providerCache: Map<string, Promise<SpeechProvider>> =
+  (globalThis as any).__egakiSpeechProviderCache ??= new Map()
+
+// ─── public factory ──────────────────────────────────────────────────────────
+
+export function getSpeechProvider(providerName: string): Error | SpeechProvider {
+  injectCredentialsToEnv()
+
+  const keyError = ensureSpeechProviderKey(providerName)
+  if (keyError) return keyError
+
+  const authSource = resolveAuthSource(providerName)
+  logAuthSource(authSource)
+
+  const factory = SPEECH_PROVIDER_FACTORIES[providerName]
+  if (!factory) {
+    return new Error(`Speech generation is not supported for provider: ${providerName}`)
+  }
+
+  // Return a lazy provider: the factory is async but we want getSpeechProvider
+  // to be sync for ergonomic use in generateSpeechUncached. The provider promise
+  // is cached globally per provider name so the factory runs once across all calls.
+  return {
+    async generate(options) {
+      const cached = providerCache.get(providerName)
+      if (cached) return (await cached).generate(options)
+      const promise = factory()
+      providerCache.set(providerName, promise)
+      return (await promise).generate(options)
+    },
+  }
+}