opencode-voice-plugin 0.0.0-stage → 0.1.1

package/src/capture.ts

@@ -0,0 +1,253 @@
+/**
+ * ÚNICO módulo com lógica por plataforma.
+ *
+ * Aqui vivem: montagem dos argumentos de entrada do ffmpeg, listagem de dispositivos
+ * e a heurística de microfone padrão. Também expõe `ProcessControl`, que injeta no
+ * `ffmpeg.ts` tudo que é específico do sistema (caminhos conhecidos, como matar a
+ * árvore de processos, etc.), mantendo o resto do código livre de `if (platform)`.
+ */
+
+import { spawn } from "node:child_process"
+import { existsSync, statSync } from "node:fs"
+import { findOnPath, runCommand } from "./ffmpeg.js"
+
+export const PLATFORM: NodeJS.Platform = process.platform
+
+/** Um arquivo abaixo disso é tratado como launcher/shim, não como o ffmpeg real. */
+const SHIM_MAX_BYTES = 1_000_000
+
+const WINDOWS_FFMPEG_PATHS = [
+  "C:\\ProgramData\\chocolatey\\lib\\ffmpeg\\tools\\ffmpeg\\bin\\ffmpeg.exe",
+  "C:\\ProgramData\\chocolatey\\bin\\ffmpeg.exe",
+  "C:\\ffmpeg\\bin\\ffmpeg.exe",
+]
+const DARWIN_FFMPEG_PATHS = ["/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/usr/bin/ffmpeg"]
+const LINUX_FFMPEG_PATHS = ["/usr/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/snap/bin/ffmpeg"]
+
+function pathExtensions(): readonly string[] {
+  return PLATFORM === "win32" ? [".exe", ".cmd", ".bat", ""] : [""]
+}
+
+function isShim(file: string): boolean {
+  if (PLATFORM !== "win32") return false
+  try {
+    const stats = statSync(file)
+    return stats.isFile() && stats.size < SHIM_MAX_BYTES
+  } catch {
+    return false
+  }
+}
+
+export interface ProcessControl {
+  readonly knownPaths: readonly string[]
+  readonly pathExtensions: readonly string[]
+  readonly spawnDetached: boolean
+  isShim(file: string): boolean
+  killTree(pid: number): Promise<void>
+}
+
+export function captureControl(): ProcessControl {
+  return {
+    knownPaths: PLATFORM === "win32" ? WINDOWS_FFMPEG_PATHS : PLATFORM === "darwin" ? DARWIN_FFMPEG_PATHS : LINUX_FFMPEG_PATHS,
+    pathExtensions: pathExtensions(),
+    spawnDetached: PLATFORM !== "win32",
+    isShim,
+    async killTree(pid: number) {
+      if (!pid) return
+      if (PLATFORM === "win32") {
+        await new Promise<void>((resolve) => {
+          const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { windowsHide: true })
+          killer.on("close", () => resolve())
+          killer.on("error", () => resolve())
+        })
+        return
+      }
+      try {
+        process.kill(-pid, "SIGKILL")
+      } catch {
+        try {
+          process.kill(pid, "SIGKILL")
+        } catch {
+          // já morreu
+        }
+      }
+    },
+  }
+}
+
+const CONTROL: ProcessControl = captureControl()
+
+export function installHint(): string {
+  if (PLATFORM === "win32") {
+    return "Install ffmpeg with `choco install ffmpeg` (or download it from ffmpeg.org and add it to PATH)."
+  }
+  if (PLATFORM === "darwin") {
+    return "Install ffmpeg with `brew install ffmpeg`."
+  }
+  return "Install ffmpeg with `sudo apt install ffmpeg pulseaudio-utils` (Debian/Ubuntu) or the equivalent for your distro."
+}
+
+export interface CaptureBackend {
+  /** argumentos de entrada do ffmpeg para o dispositivo (nome ou id) */
+  inputArgs(device?: string): string[]
+  /** lista de dispositivos legíveis (para log e para o caso de múltiplos microfones) */
+  listDevices(ffmpeg: string): Promise<string[]>
+  /** dispositivo usado quando o usuário não configura `device` */
+  defaultDevice(ffmpeg: string): Promise<string | undefined>
+}
+
+// ---------------------------------------------------------------------------
+// Parsing (puro, testável)
+// ---------------------------------------------------------------------------
+
+/** `"Microphone (C922)" (audio)` → `Microphone (C922)`; ignora dispositivos de vídeo. */
+export function parseDshowDevices(text: string): string[] {
+  const devices: string[] = []
+  const pattern = /"([^"]+)"\s*\((?:audio|áudio)\)/g
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(text)) !== null) {
+    if (match[1]) devices.push(match[1].trim())
+  }
+  return devices
+}
+
+/** `pactl list short sources`: nome na 2ª coluna; descarta monitores de saída. */
+export function parsePactlSources(text: string): string[] {
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.split("\t"))
+    .filter((columns) => columns.length >= 2 && columns[1] !== undefined)
+    .map((columns) => (columns[1] ?? "").trim())
+    .filter((name) => name.length > 0 && !name.endsWith(".monitor"))
+}
+
+/** `arecord -l`: `card 1: PCH [...], device 0: ...` → `hw:1,0`. */
+export function parseArecordDevices(text: string): string[] {
+  const devices: string[] = []
+  const pattern = /card\s+(\d+):[\s\S]*?device\s+(\d+):/g
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(text)) !== null) {
+    devices.push(`hw:${match[1]},${match[2]}`)
+  }
+  return devices
+}
+
+/** `ffmpeg -f avfoundation -list_devices`: lista os índices do bloco de áudio. */
+export function parseAvfoundationDevices(text: string): string[] {
+  const marker = "AVFoundation audio devices:"
+  const index = text.indexOf(marker)
+  if (index < 0) return []
+  const section = text.slice(index)
+  const devices: string[] = []
+  const pattern = /\[(\d+)\]\s+(.+)/g
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(section)) !== null) {
+    if (match[1]) devices.push(match[1].trim())
+  }
+  return devices
+}
+
+// ---------------------------------------------------------------------------
+// Heurística de dispositivo padrão
+// ---------------------------------------------------------------------------
+
+const VIRTUAL = [/cable output/i, /stereo mix/i, /what u hear/i, /\.monitor\b/i, /loopback/i, /virtual/i]
+const PREFERRED = [/microphone/i, /microfone/i, /headset/i, /mic\b/i, /^default$/i, /@default_source@/i]
+
+/**
+ * Muitas máquinas têm cabos virtuais (VB-Audio, MSI Sound Tune, monitores do Pulse)
+ * que abrem mas gravam silêncio. Preferimos nomes de microfone de verdade e evitamos
+ * os virtuais; sem candidato ideal, usamos o primeiro não virtual.
+ */
+export function pickDefaultDevice(devices: readonly string[]): string | undefined {
+  const list = devices.map((device) => device.trim()).filter(Boolean)
+  if (list.length === 0) return undefined
+  const clean = list.filter((name) => !VIRTUAL.some((pattern) => pattern.test(name)))
+  const pool = clean.length > 0 ? clean : list
+  return pool.find((name) => PREFERRED.some((pattern) => pattern.test(name))) ?? pool[0]
+}
+
+// ---------------------------------------------------------------------------
+// Backends por plataforma
+// ---------------------------------------------------------------------------
+
+function windowsInputArgs(device?: string): string[] {
+  if (!device) {
+    throw new Error("On Windows you must pick a DirectShow microphone before recording.")
+  }
+  return ["-f", "dshow", "-i", `audio=${device}`]
+}
+
+async function windowsListDevices(ffmpeg: string): Promise<string[]> {
+  // O ffmpeg sai com código != 0 aqui de propósito; a lista vem no stderr.
+  const { stderr } = await runCommand(
+    ffmpeg,
+    ["-hide_banner", "-f", "dshow", "-list_devices", "true", "-i", "dummy"],
+    CONTROL,
+  )
+  return parseDshowDevices(stderr)
+}
+
+const windowsBackend: CaptureBackend = {
+  inputArgs: windowsInputArgs,
+  listDevices: windowsListDevices,
+  defaultDevice: async (ffmpeg) => pickDefaultDevice(await windowsListDevices(ffmpeg)),
+}
+
+let pactlCache: boolean | undefined
+
+function hasPactl(): boolean {
+  if (pactlCache === undefined) {
+    pactlCache = findOnPath("pactl", pathExtensions()) !== undefined
+  }
+  return pactlCache
+}
+
+function linuxInputArgs(device?: string): string[] {
+  const driver = hasPactl() ? "pulse" : "alsa"
+  return ["-f", driver, "-i", device ?? "default"]
+}
+
+async function linuxListDevices(_ffmpeg: string): Promise<string[]> {
+  if (hasPactl()) {
+    const { stdout } = await runCommand("pactl", ["list", "short", "sources"], CONTROL)
+    const sources = parsePactlSources(stdout)
+    if (sources.length > 0) return sources
+  }
+  const { stdout } = await runCommand("arecord", ["-l"], CONTROL)
+  return parseArecordDevices(stdout)
+}
+
+const linuxBackend: CaptureBackend = {
+  inputArgs: linuxInputArgs,
+  listDevices: linuxListDevices,
+  defaultDevice: async (ffmpeg) => pickDefaultDevice(await linuxListDevices(ffmpeg)),
+}
+
+function macInputArgs(device?: string): string[] {
+  return ["-f", "avfoundation", "-i", `:${device ?? "0"}`]
+}
+
+async function macListDevices(ffmpeg: string): Promise<string[]> {
+  const { stderr } = await runCommand(
+    ffmpeg,
+    ["-hide_banner", "-f", "avfoundation", "-list_devices", "true", "-i", ""],
+    CONTROL,
+  )
+  return parseAvfoundationDevices(stderr)
+}
+
+const macBackend: CaptureBackend = {
+  inputArgs: macInputArgs,
+  listDevices: macListDevices,
+  defaultDevice: async (ffmpeg) => pickDefaultDevice(await macListDevices(ffmpeg)),
+}
+
+const fallbackBackend: CaptureBackend = linuxBackend
+
+export function getBackend(): CaptureBackend {
+  if (PLATFORM === "win32") return windowsBackend
+  if (PLATFORM === "darwin") return macBackend
+  if (existsSync("/proc") || PLATFORM === "linux") return linuxBackend
+  return fallbackBackend
+}

package/src/ffmpeg.ts

@@ -0,0 +1,157 @@
+/**
+ * Resolução do binário do ffmpeg, execução de processos e parada limpa.
+ * Este arquivo é intencionalmente livre de lógica por plataforma: tudo que muda
+ * entre sistemas vem injetado via `ProcessControl` (definido em `capture.ts`).
+ */
+
+import { spawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import { delimiter, join } from "node:path"
+import type { ProcessControl } from "./capture.js"
+
+export interface CommandResult {
+  code: number | null
+  stdout: string
+  stderr: string
+}
+
+/** Procura um executável no PATH. Usa o separador de PATH do próprio Node, sem branch de plataforma. */
+export function findOnPath(name: string, extensions: readonly string[]): string | undefined {
+  const entries = (process.env.PATH ?? "").split(delimiter)
+  for (const entry of entries) {
+    if (!entry) continue
+    for (const extension of extensions) {
+      const candidate = join(entry, name + extension)
+      if (existsSync(candidate)) return candidate
+    }
+  }
+  return undefined
+}
+
+/** Executa um comando e captura stdout/stderr. Nunca rejeita: o resultado carrega o erro. */
+export function runCommand(
+  command: string,
+  args: readonly string[],
+  control: ProcessControl,
+  timeoutMs = 15_000,
+): Promise<CommandResult> {
+  return new Promise((resolve) => {
+    let stdout = ""
+    let stderr = ""
+    const child = spawn(command, [...args], { windowsHide: true })
+    const timer = setTimeout(() => {
+      void control.killTree(child.pid ?? 0)
+    }, timeoutMs)
+
+    const finish = (code: number | null) => {
+      clearTimeout(timer)
+      resolve({ code, stdout, stderr })
+    }
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString()
+    })
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString()
+    })
+    child.on("close", (code) => finish(code))
+    child.on("error", (error) => {
+      stderr += (stderr ? "\n" : "") + error.message
+      finish(null)
+    })
+  })
+}
+
+const ffmpegCache = new Map<string, string>()
+
+/**
+ * Ordem de resolução: opção explícita → PATH → caminhos conhecidos da plataforma.
+ * Se o caminho resolvido for um launcher (ex.: shim do Chocolatey no Windows),
+ * desce para o binário real, para que `q` no stdin chegue ao processo certo.
+ */
+export function resolveFfmpeg(explicit: string | null | undefined, control: ProcessControl): Promise<string> {
+  const key = explicit ?? ""
+  const cached = ffmpegCache.get(key)
+  if (cached && existsSync(cached)) return Promise.resolve(cached)
+
+  const candidates: string[] = []
+  if (explicit) candidates.push(explicit)
+  const onPath = findOnPath("ffmpeg", control.pathExtensions)
+  if (onPath) candidates.push(onPath)
+  candidates.push(...control.knownPaths)
+
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue
+    const resolved = control.isShim(candidate)
+      ? (control.knownPaths.find((path) => existsSync(path) && !control.isShim(path)) ?? candidate)
+      : candidate
+    ffmpegCache.set(key, resolved)
+    return Promise.resolve(resolved)
+  }
+
+  return Promise.reject(new Error("ffmpeg not found"))
+}
+
+export interface RecordingResult {
+  code: number | null
+  stderr: string
+}
+
+export interface Recording {
+  readonly file: string
+  /** Escreve `q` no stdin para o ffmpeg fechar o WAV; mata a árvore após 2 s se preciso. */
+  stop(): Promise<RecordingResult>
+}
+
+export function startRecording(options: {
+  ffmpeg: string
+  args: readonly string[]
+  file: string
+  control: ProcessControl
+}): Recording {
+  const { ffmpeg, args, file, control } = options
+  const child = spawn(ffmpeg, [...args], {
+    stdio: ["pipe", "ignore", "pipe"],
+    windowsHide: true,
+    detached: control.spawnDetached,
+  })
+
+  let stderr = ""
+  child.stderr?.on("data", (chunk: Buffer) => {
+    if (stderr.length < 8_000) stderr += chunk.toString()
+  })
+  // O stdin pode fechar sozinho se o ffmpeg morrer durante a gravação.
+  child.stdin?.on("error", () => {})
+
+  const exited = new Promise<RecordingResult>((resolve) => {
+    child.on("close", (code) => resolve({ code, stderr }))
+    child.on("error", (error) => {
+      stderr += (stderr ? "\n" : "") + error.message
+      resolve({ code: null, stderr })
+    })
+  })
+
+  let stopping: Promise<RecordingResult> | undefined
+
+  return {
+    file,
+    stop() {
+      if (stopping) return stopping
+      stopping = (async () => {
+        try {
+          child.stdin?.write("q\n")
+          child.stdin?.end()
+        } catch {
+          // stdin já estava fechado
+        }
+        const timer = setTimeout(() => {
+          void control.killTree(child.pid ?? 0)
+        }, 2_000)
+        const result = await exited
+        clearTimeout(timer)
+        return result
+      })()
+      return stopping
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import { Plugin } from "@opencode/plugin"
+
+/**
+ * Entrypoint de servidor exigido pelo layout de descoberta de plugins
+ * (`index.ts` + `tui` no mesmo diretório). Toda a funcionalidade vive no `tui.tsx`;
+ * este plugin é intencionalmente vazio.
+ */
+export default Plugin.define({
+  id: "voice.server",
+  setup() {},
+})

package/src/settings.ts

@@ -0,0 +1,162 @@
+/**
+ * Configuração do plugin: options do cli.json + variáveis de ambiente + defaults.
+ *
+ * Resolução da chave da API, nesta ordem:
+ *   1. `process.env[apiKeyEnv]`
+ *   2. store de credenciais do próprio OpenCode (`auth.json`), se `apiKeyFromAuth`
+ *
+ * A chave nunca é logada, copiada nem gravada em nenhum lugar.
+ */
+
+import { readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/**
+ * Glifos do ícone. Os defaults são caracteres do BMP com largura 1, que existem
+ * nas fontes de console (Consolas, Cascadia, DejaVu) e são medidos corretamente —
+ * emojis fora do BMP (ex.: 🎤) aparecem como "?" em alguns terminais e desalinham
+ * a área clicável. Se sua fonte suportar emoji, sobrescreva via `icons`.
+ */
+export interface VoiceIcons {
+  idle: string
+  recording: string
+  transcribing: string
+}
+
+export const DEFAULT_ICONS: VoiceIcons = {
+  idle: "○",
+  recording: "●",
+  transcribing: "…",
+}
+
+export interface VoiceSettings {
+  /** Nome da variável de ambiente que guarda a chave do OpenRouter (prioridade). */
+  apiKeyEnv: string
+  /** Se a env var não existir, usa a chave já guardada pelo OpenCode. */
+  apiKeyFromAuth: boolean
+  /** Integração do OpenCode de onde ler a chave (ex.: "openrouter"). */
+  authIntegration: string
+  /** Modelo de STT (ex.: "openai/whisper-large-v3"). */
+  model: string
+  /** Código ISO-639-1 ou "auto" (omite o campo no request). */
+  language: string
+  /** Base URL do provedor compatível com /audio/transcriptions. */
+  baseUrl: string
+  /** Dispositivo de áudio explícito; null = autodetectar. */
+  device: string | null
+  /** Caminho explícito do binário ffmpeg; null = resolver automaticamente. */
+  ffmpegPath: string | null
+  /** Binding do comando de ditado (ex.: "ctrl+y" ou "<leader>v"). */
+  keybind: string
+  /** Envia direto, sem abrir o dialog de revisão. */
+  autoSubmit: boolean
+  /** Permite ditar na tela inicial, criando a sessão automaticamente. */
+  allowFromHome: boolean
+  /** Corte automático da gravação, em segundos. */
+  maxSeconds: number
+  /** Mantém o WAV temporário depois de transcrever (debug). */
+  keepAudio: boolean
+  /** Glifos do ícone por estado. */
+  icons: VoiceIcons
+}
+
+export const DEFAULTS: VoiceSettings = {
+  apiKeyEnv: "OPENROUTER_API_KEY",
+  apiKeyFromAuth: true,
+  authIntegration: "openrouter",
+  model: "openai/whisper-large-v3",
+  language: "auto",
+  baseUrl: "https://openrouter.ai/api/v1",
+  device: null,
+  ffmpegPath: null,
+  keybind: "ctrl+y",
+  autoSubmit: false,
+  allowFromHome: true,
+  maxSeconds: 55,
+  keepAudio: false,
+  icons: DEFAULT_ICONS,
+}
+
+/**
+ * O provedor de STT estoura em ~60 s por requisição, então uma gravação mais longa
+ * que isso provavelmente falha. Mantemos o teto em 120 s apenas como rede de segurança.
+ */
+export const MAX_SECONDS_CEILING = 120
+export const PROVIDER_SAFE_SECONDS = 60
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined
+}
+
+export function resolveSettings(options: Readonly<Record<string, unknown>> | undefined): VoiceSettings {
+  const raw = options ?? {}
+  const settings: VoiceSettings = { ...DEFAULTS }
+
+  settings.apiKeyEnv = nonEmptyString(raw.apiKeyEnv) ?? settings.apiKeyEnv
+  settings.apiKeyFromAuth = raw.apiKeyFromAuth !== false
+  settings.authIntegration = nonEmptyString(raw.authIntegration) ?? settings.authIntegration
+  settings.model = nonEmptyString(raw.model) ?? settings.model
+  settings.language = nonEmptyString(raw.language) ?? settings.language
+  settings.baseUrl = nonEmptyString(raw.baseUrl) ?? settings.baseUrl
+  settings.device = nonEmptyString(raw.device) ?? null
+  settings.ffmpegPath = nonEmptyString(raw.ffmpegPath) ?? null
+  settings.keybind = nonEmptyString(raw.keybind) ?? settings.keybind
+  settings.autoSubmit = raw.autoSubmit === true
+  settings.allowFromHome = raw.allowFromHome !== false
+  settings.keepAudio = raw.keepAudio === true
+
+  const rawIcons = raw.icons as Partial<Record<keyof VoiceIcons, unknown>> | undefined
+  if (rawIcons && typeof rawIcons === "object") {
+    settings.icons = {
+      idle: nonEmptyString(rawIcons.idle) ?? DEFAULT_ICONS.idle,
+      recording: nonEmptyString(rawIcons.recording) ?? DEFAULT_ICONS.recording,
+      transcribing: nonEmptyString(rawIcons.transcribing) ?? DEFAULT_ICONS.transcribing,
+    }
+  }
+
+  if (typeof raw.maxSeconds === "number" && Number.isFinite(raw.maxSeconds) && raw.maxSeconds > 0) {
+    settings.maxSeconds = Math.min(Math.floor(raw.maxSeconds), MAX_SECONDS_CEILING)
+  }
+
+  return settings
+}
+
+/** Diretório de dados do OpenCode. Layout fixo, inclusive no Windows. */
+function openCodeDataDir(): string {
+  const xdg = nonEmptyString(process.env.XDG_DATA_HOME)
+  return xdg ? join(xdg, "opencode") : join(homedir(), ".local", "share", "opencode")
+}
+
+/**
+ * Lê a chave da API que o próprio OpenCode guardou (ex.: via `/connect`).
+ * Somente leitura, sem log; qualquer falha ou formato inesperado retorna undefined.
+ */
+export function readStoredApiKey(integration: string): string | undefined {
+  try {
+    const raw = readFileSync(join(openCodeDataDir(), "auth.json"), "utf8")
+    const parsed = JSON.parse(raw) as Record<string, { type?: unknown; key?: unknown } | undefined>
+    const entry = parsed?.[integration]
+    return entry ? nonEmptyString(entry.key) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export interface ApiKeyResolution {
+  key?: string
+  source: "env" | "auth-store" | "none"
+}
+
+/** Env var tem prioridade; senão, o store do OpenCode. */
+export function resolveApiKey(settings: VoiceSettings): ApiKeyResolution {
+  const fromEnv = nonEmptyString(process.env[settings.apiKeyEnv])
+  if (fromEnv) return { key: fromEnv, source: "env" }
+
+  if (settings.apiKeyFromAuth) {
+    const stored = readStoredApiKey(settings.authIntegration)
+    if (stored) return { key: stored, source: "auth-store" }
+  }
+
+  return { source: "none" }
+}

package/src/transcribe.ts

@@ -0,0 +1,111 @@
+/**
+ * Transcrição via OpenRouter (`POST /api/v1/audio/transcriptions`).
+ *
+ * O endpoint espera JSON com o áudio em base64 (não multipart). Mantemos a
+ * interface `TranscriptionProvider` para que outro provedor possa ser adicionado
+ * depois sem tocar no resto do plugin.
+ */
+
+import { readFile } from "node:fs/promises"
+
+export interface TranscribeInput {
+  /** Caminho do WAV a transcrever. */
+  file: string
+  apiKey: string
+  model: string
+  /** ISO-639-1; "auto" ou vazio omite o campo e deixa o provedor detectar. */
+  language?: string
+  /** Base do provedor; default é o OpenRouter. */
+  baseUrl?: string
+  timeoutMs?: number
+  /** Injetável para testes. */
+  fetchImpl?: typeof fetch
+}
+
+export interface TranscribeOutput {
+  text: string
+  cost?: number
+  seconds?: number
+}
+
+export class TranscribeError extends Error {
+  readonly status?: number
+  readonly body?: string
+
+  constructor(message: string, status?: number, body?: string) {
+    super(message)
+    this.name = "TranscribeError"
+    this.status = status
+    this.body = body
+  }
+}
+
+function truncate(value: string, max = 500): string {
+  return value.length > max ? `${value.slice(0, max)}…` : value
+}
+
+function toMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export async function transcribe(input: TranscribeInput): Promise<TranscribeOutput> {
+  const base = (input.baseUrl ?? "https://openrouter.ai/api/v1").replace(/\/+$/, "")
+  const doFetch = input.fetchImpl ?? fetch
+
+  const audio = await readFile(input.file)
+  const body: Record<string, unknown> = {
+    model: input.model,
+    input_audio: { data: audio.toString("base64"), format: "wav" },
+  }
+  if (input.language && input.language !== "auto") body.language = input.language
+
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), input.timeoutMs ?? 90_000)
+
+  try {
+    const response = await doFetch(`${base}/audio/transcriptions`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${input.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    })
+
+    const raw = await response.text()
+    if (!response.ok) {
+      throw new TranscribeError(`The provider returned ${response.status}.`, response.status, truncate(raw))
+    }
+
+    let parsed: { text?: unknown; usage?: { cost?: unknown; seconds?: unknown } }
+    try {
+      parsed = JSON.parse(raw) as typeof parsed
+    } catch {
+      throw new TranscribeError("Invalid response from the provider.", response.status, truncate(raw))
+    }
+
+    const text = typeof parsed.text === "string" ? parsed.text.trim() : ""
+    const cost = typeof parsed.usage?.cost === "number" ? parsed.usage.cost : undefined
+    const seconds = typeof parsed.usage?.seconds === "number" ? parsed.usage.seconds : undefined
+    return { text, cost, seconds }
+  } catch (error) {
+    if (error instanceof TranscribeError) throw error
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new TranscribeError("Timed out talking to the provider.")
+    }
+    throw new TranscribeError(toMessage(error))
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export interface TranscriptionProvider {
+  readonly id: string
+  transcribe(input: TranscribeInput): Promise<TranscribeOutput>
+}
+
+export const openRouterProvider: TranscriptionProvider = {
+  id: "openrouter",
+  transcribe,
+}