@maheidem/pi-audio-transcribe 0.2.0

package/pipeline.ts

@@ -0,0 +1,252 @@
+/**
+ * Transcription pipeline — deliberately free of any pi import.
+ *
+ * Keeping pi out of this module means the whole flow (pre-flight, ASR,
+ * cross-check, validation, sidecar) is unit-testable without a running pi,
+ * which is what makes the fixture-server tests possible. index.ts is the
+ * thin adapter that binds this to pi's tool/command/input surfaces.
+ */
+
+import { basename, relative } from "node:path";
+import { readdir, stat } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+
+import { resolveConfig, type TranscribeConfig } from "./config.ts";
+import {
+	isAudioPath,
+	listSttModels,
+	mimeFor,
+	pickSttModel,
+	transcribe,
+	normalizeLanguage,
+	type AsrResponse,
+	type SttModel,
+} from "./omlx.ts";
+import { expandPath } from "./paths.ts";
+import { exists, probeAudio, sha256File, sidecarPathFor, writeJsonAtomic, SIDECAR_SCHEMA, type SidecarDocument } from "./sidecar.ts";
+import { countWords, extractMeasurements, similarity, validateSpeech, type CrossCheckResult, type ValidationReport } from "./validate.ts";
+
+export type Exec = (cmd: string, args: string[], opts?: { signal?: AbortSignal }) => Promise<{ stdout: string; code: number; stderr?: string }>;
+
+/** Everything the pipeline needs from its host; pi supplies this via index.ts. */
+export interface PipelineCtx {
+	cwd: string;
+	exec: Exec;
+	signal?: AbortSignal;
+	onProgress?: (msg: string) => void;
+	/** Wrap the write so it serialises against pi's built-in edit/write. */
+	withQueue?: <T>(path: string, fn: () => Promise<T>) => Promise<T>;
+}
+
+export interface FileResult {
+	input: string;
+	audioPath: string;
+	sidecarPath: string | null;
+	skipped: boolean;
+	skipReason?: string;
+	error?: string;
+	verdict?: ValidationReport["verdict"];
+	confidence?: number;
+	language?: string | null;
+	durationSeconds?: number | null;
+	words?: number;
+	text?: string;
+	recommendations?: string[];
+	crossCheckSimilarity?: number | null;
+	measurements?: Array<{ raw: string; value: number; unit: string }>;
+}
+
+export interface Setup {
+	cfg: TranscribeConfig;
+	model: string | null;
+	modelInfo: SttModel | null;
+	note: string;
+}
+
+/** Resolve the STT model: a pinned config id wins, else auto-discover. */
+export async function resolveSttModel(cfg: TranscribeConfig, signal?: AbortSignal): Promise<Setup> {
+	if (cfg.model) return { cfg, model: cfg.model, modelInfo: null, note: `pinned via config: ${cfg.model}` };
+	const models = await listSttModels(cfg.baseUrl, cfg.apiKey, 15_000, signal);
+	const picked = pickSttModel(models);
+	if (!picked) return { cfg, model: null, modelInfo: null, note: "no audio_stt model exposed by the server" };
+	const est = picked.estimatedSize ? (picked.estimatedSize / 1e9).toFixed(1) : "?";
+	return {
+		cfg,
+		model: picked.id,
+		modelInfo: picked,
+		note: picked.loaded ? `${picked.id} (already resident)` : `${picked.id} (cold load, ~${est} GB)`,
+	};
+}
+
+/** Transcribe one file and persist its sidecar. Per-file failures return a result; they do not throw. */
+export async function transcribeOne(audioPath: string, setup: Setup, ctx: PipelineCtx): Promise<FileResult> {
+	const cfg = setup.cfg;
+	const abs = expandPath(audioPath, ctx.cwd);
+	const sidecarPath = sidecarPathFor(abs);
+	const base: FileResult = { input: audioPath, audioPath: abs, sidecarPath: null, skipped: false };
+	const progress = (m: string) => ctx.onProgress?.(m);
+
+	// Pre-flight. The server answers HTTP 500 for bad input, so every cheap
+	// rejection happens here where the message can be actionable.
+	const st = await stat(abs).catch(() => null);
+	if (!st) return { ...base, skipped: true, skipReason: "file not found" };
+	if (st.isDirectory()) return { ...base, skipped: true, skipReason: "is a directory" };
+	if (!isAudioPath(abs)) return { ...base, skipped: true, skipReason: `unrecognized audio extension ".${(basename(abs).split(".").pop() ?? "")}"` };
+	if (!st.size) return { ...base, skipped: true, skipReason: "file is empty (0 bytes)" };
+	if (cfg.maxBytes > 0 && st.size > cfg.maxBytes) return { ...base, skipped: true, skipReason: `${st.size} bytes exceeds maxBytes ${cfg.maxBytes}` };
+	if (!setup.model) return { ...base, skipped: true, skipReason: "no STT model available on the server" };
+	if (ctx.signal?.aborted) return { ...base, skipped: true, skipReason: "cancelled" };
+	if (!cfg.force && (await exists(sidecarPath))) return { ...base, skipped: true, skipReason: "sidecar exists (pass force to overwrite)", sidecarPath };
+
+	const requestedLanguage = normalizeLanguage(cfg.language);
+	progress(`transcribing ${basename(abs)} via ${setup.model}`);
+
+	// ffprobe = ground truth for duration; unavailable is tolerated.
+	const probe = await probeAudio(abs, ctx.exec, ctx.signal);
+
+	let primary: AsrResponse;
+	try {
+		primary = await transcribe({ baseUrl: cfg.baseUrl, model: setup.model, filePath: abs, apiKey: cfg.apiKey, language: requestedLanguage, timeoutMs: cfg.timeoutMs, signal: ctx.signal });
+	} catch (err) {
+		return { ...base, error: err instanceof Error ? err.message : String(err) };
+	}
+
+	// Cross-check pass: re-run with the language the server itself reported.
+	// On real speech this reproduces the primary byte-for-byte, so any
+	// divergence is a genuine instability signal.
+	let cross: CrossCheckResult = { performed: false, skippedReason: "disabled" };
+	const autoLang = normalizeLanguage(primary.language);
+	if (cfg.crossCheck && primary.text.trim() && !ctx.signal?.aborted) {
+		const hint = requestedLanguage ?? autoLang;
+		progress(`cross-check pass (${hint ?? "auto"})`);
+		try {
+			const second = await transcribe({ baseUrl: cfg.baseUrl, model: setup.model, filePath: abs, apiKey: cfg.apiKey, language: hint, timeoutMs: cfg.timeoutMs, signal: ctx.signal });
+			const sim = similarity(primary.text, second.text);
+			cross = { performed: true, languageUsed: hint, similarity: sim, textChanged: sim < 1, altText: sim < 1 ? second.text : undefined, latencySeconds: second.duration };
+		} catch (err) {
+			cross = { performed: false, skippedReason: err instanceof Error ? err.message : String(err) };
+		}
+	}
+
+	const report = validateSpeech({ response: primary, requestedLanguage, probe, crossCheck: cross });
+	const measurements = extractMeasurements(primary.text);
+
+	const doc: SidecarDocument = {
+		schema: SIDECAR_SCHEMA,
+		createdAt: new Date().toISOString(),
+		audio: {
+			path: abs,
+			name: basename(abs),
+			bytes: st.size,
+			sha256: await sha256File(abs),
+			mime: mimeFor(abs),
+			durationSeconds: probe.durationSeconds ?? null,
+			sampleRateHz: probe.sampleRateHz ?? null,
+			channels: probe.channels ?? null,
+			codec: probe.codec ?? null,
+		},
+		transcript: {
+			text: primary.text,
+			words: countWords(primary.text),
+			characters: primary.text.length,
+			language: report.language.normalized,
+		},
+		validation: {
+			verdict: report.verdict,
+			confidence: report.confidence,
+			checks: report.checks,
+			recommendations: report.recommendations,
+			language: report.language,
+			timings: report.timings,
+			crossCheck: report.crossCheck,
+			...(measurements.length ? { measurements } : {}),
+		},
+		provider: {
+			name: "oMLX",
+			baseUrl: cfg.baseUrl,
+			model: setup.model,
+			engine: setup.modelInfo?.engineType ?? null,
+			languageHintSent: requestedLanguage,
+			crossChecked: cross.performed,
+			note: "response.duration is inference latency, not audio length; audio duration comes from ffprobe/segments[].end",
+		},
+	};
+
+	const write = async () => writeJsonAtomic(sidecarPath, doc);
+	try {
+		if (ctx.withQueue) await ctx.withQueue(sidecarPath, write);
+		else await write();
+	} catch (err) {
+		return { ...base, error: `transcribed but failed to write sidecar: ${err instanceof Error ? err.message : String(err)}`, text: primary.text, verdict: report.verdict, confidence: report.confidence };
+	}
+
+	return {
+		input: audioPath,
+		audioPath: abs,
+		sidecarPath,
+		skipped: false,
+		verdict: report.verdict,
+		confidence: report.confidence,
+		language: report.language.normalized,
+		durationSeconds: probe.durationSeconds ?? report.timings.audioSeconds,
+		words: doc.transcript.words,
+		text: primary.text,
+		recommendations: report.recommendations,
+		crossCheckSimilarity: cross.similarity ?? null,
+		measurements,
+	};
+}
+
+/** Expand files/directories into a flat, de-duplicated audio path list. */
+export async function expandInputs(inputs: string[], cwd: string, recursive: boolean): Promise<string[]> {
+	const out: string[] = [];
+	for (const raw of inputs) {
+		const abs = expandPath(raw, cwd);
+		const st = await stat(abs).catch(() => null);
+		if (!st) continue;
+		const found = st.isDirectory() ? await walk(abs, recursive) : isAudioPath(abs) ? [abs] : [];
+		for (const f of found) if (!out.includes(f)) out.push(f);
+	}
+	return out;
+}
+
+async function walk(dir: string, recursive: boolean): Promise<string[]> {
+	const found: string[] = [];
+	let entries: Dirent[];
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return found;
+	}
+	for (const e of entries) {
+		const full = `${dir.replace(/\/+$/, "")}/${e.name}`;
+		if (e.isDirectory()) {
+			if (recursive && ![".git", "node_modules", ".Trash"].includes(e.name)) found.push(...(await walk(full, recursive)));
+		} else if (isAudioPath(full)) found.push(full);
+	}
+	return found;
+}
+
+/** Human-readable multi-file summary. */
+export function formatSummary(results: FileResult[], setup: Setup, cwd: string): string {
+	const done = results.filter((r) => !r.skipped && !r.error);
+	const skipped = results.filter((r) => r.skipped);
+	const failed = results.filter((r) => r.error);
+	const rel = (p: string): string => {
+		if (!p) return "";
+		const r = relative(cwd, p);
+		return r && !r.startsWith("..") ? r : p;
+	};
+	const lines = [`oMLX STT · model ${setup.model ?? "unavailable"} · ${done.length} transcribed, ${skipped.length} skipped, ${failed.length} failed`];
+	for (const r of done) {
+		const dur = r.durationSeconds ? `${r.durationSeconds.toFixed(1)}s` : "?";
+		const sim = r.crossCheckSimilarity != null ? ` · xcheck ${(r.crossCheckSimilarity * 100).toFixed(0)}%` : "";
+		lines.push(`  ${String(r.verdict ?? "?").toUpperCase()} (${((r.confidence ?? 0) * 100).toFixed(0)}%) ${r.language ?? "?"} ${dur}${sim} — ${rel(r.audioPath)}`);
+		lines.push(`    → ${rel(r.sidecarPath ?? "")}`);
+	}
+	for (const r of failed) lines.push(`  FAILED ${rel(r.audioPath)}: ${r.error}`);
+	for (const r of skipped) lines.push(`  skipped ${rel(r.audioPath)}: ${r.skipReason}`);
+	const recs = [...new Set(done.flatMap((r) => r.recommendations ?? []))];
+	if (recs.length) lines.push(`  advice: ${recs.join(" | ")}`);
+	return lines.join("\n");
+}

package/settings.ts

@@ -0,0 +1,130 @@
+import {
+	CONFIG_PATH,
+	environmentOverrideKeys,
+	loadStoredConfig,
+	normalizeBaseUrl,
+	resetConfig,
+	resolveConfig,
+	saveConfig,
+	type TranscribeConfig,
+} from "./config.ts";
+
+export type AudioSettingKey =
+	| "autoDetect"
+	| "crossCheck"
+	| "force"
+	| "language"
+	| "model"
+	| "baseUrl"
+	| "timeoutMs"
+	| "maxBytes";
+
+function booleanValue(raw: string): boolean | null {
+	const normalized = raw.trim().toLowerCase();
+	if (["true", "on", "yes", "1"].includes(normalized)) return true;
+	if (["false", "off", "no", "0"].includes(normalized)) return false;
+	return null;
+}
+
+export function formatBytes(bytes: number): string {
+	if (bytes === 0) return "unlimited";
+	if (bytes >= 1024 ** 3) return `${Number((bytes / 1024 ** 3).toFixed(1))} GB`;
+	if (bytes >= 1024 ** 2) return `${Number((bytes / 1024 ** 2).toFixed(1))} MB`;
+	if (bytes >= 1024) return `${Number((bytes / 1024).toFixed(1))} KB`;
+	return `${bytes} B`;
+}
+
+export function parseBytes(raw: string): number | null {
+	const normalized = raw.trim().toLowerCase();
+	if (["0", "none", "unlimited", "off"].includes(normalized)) return 0;
+	const match = /^(\d+(?:\.\d+)?)\s*(b|kb|kib|mb|mib|gb|gib)?$/.exec(normalized);
+	if (!match) return null;
+	const amount = Number(match[1]);
+	const unit = match[2] ?? "b";
+	const power = unit.startsWith("k") ? 1 : unit.startsWith("m") ? 2 : unit.startsWith("g") ? 3 : 0;
+	const bytes = Math.round(amount * 1024 ** power);
+	return Number.isSafeInteger(bytes) ? bytes : null;
+}
+
+export function formatTimeout(milliseconds: number): string {
+	if (milliseconds % 60_000 === 0) return `${milliseconds / 60_000}m`;
+	if (milliseconds % 1_000 === 0) return `${milliseconds / 1_000}s`;
+	return `${milliseconds}ms`;
+}
+
+export function parseTimeout(raw: string): number | null {
+	const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m)?\s*$/i.exec(raw);
+	if (!match) return null;
+	const amount = Number(match[1]);
+	const unit = (match[2] ?? "s").toLowerCase();
+	const milliseconds = Math.round(amount * (unit === "m" ? 60_000 : unit === "s" ? 1_000 : 1));
+	return Number.isSafeInteger(milliseconds) ? milliseconds : null;
+}
+
+/** Canonical persistent actions shared by the panel and future script syntax. */
+export class AudioSettingsController {
+	private storedValue: TranscribeConfig;
+
+	constructor() {
+		this.storedValue = loadStoredConfig();
+	}
+
+	stored(): TranscribeConfig {
+		return { ...this.storedValue };
+	}
+
+	effective(): TranscribeConfig {
+		return resolveConfig();
+	}
+
+	overrides(): string[] {
+		return environmentOverrideKeys();
+	}
+
+	apply(key: AudioSettingKey, raw: string): string | null {
+		const next = { ...this.storedValue };
+		if (key === "autoDetect" || key === "crossCheck" || key === "force") {
+			const value = booleanValue(raw);
+			if (value === null) return `${key} accepts on or off`;
+			next[key] = value;
+		} else if (key === "language") {
+			const value = raw.trim();
+			if (!value || value.toLowerCase() === "auto") next.language = null;
+			else if (!/^[A-Za-z]{2,16}(?:-[A-Za-z0-9]{2,16})*$/.test(value)) return "Language must be auto or an ISO-style tag such as pt or en-US";
+			else next.language = value;
+		} else if (key === "model") {
+			const value = raw.trim();
+			if (value.length > 200) return "Model id must be 200 characters or fewer";
+			next.model = !value || value.toLowerCase() === "auto" ? null : value;
+		} else if (key === "baseUrl") {
+			const value = normalizeBaseUrl(raw);
+			try {
+				const parsed = new URL(value);
+				if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname) throw new Error("invalid");
+			} catch {
+				return "Server must be an HTTP(S) host or URL";
+			}
+			next.baseUrl = value;
+		} else if (key === "timeoutMs") {
+			const value = parseTimeout(raw);
+			if (value === null || value < 1_000 || value > 30 * 60_000) return "Timeout must be between 1s and 30m";
+			next.timeoutMs = value;
+		} else if (key === "maxBytes") {
+			const value = parseBytes(raw);
+			if (value === null || value > 100 * 1024 ** 3) return "Max file size must be unlimited or at most 100 GB";
+			next.maxBytes = value;
+		}
+
+		this.storedValue = saveConfig(next);
+		return null;
+	}
+
+	reset(): TranscribeConfig {
+		this.storedValue = resetConfig();
+		return this.stored();
+	}
+
+	configPath(): string {
+		return CONFIG_PATH;
+	}
+}

package/sidecar.ts

@@ -0,0 +1,123 @@
+/**
+ * Sidecar persistence + audio probing.
+ *
+ * The sidecar is a JSON document written next to the audio file:
+ *   Medidas da gaveta.m4a -> Medidas da gaveta.transcript.json
+ *
+ * Writes are atomic (temp file + rename) so a cancelled or crashed run can
+ * never leave a half-written transcript that looks authoritative.
+ */
+
+import { createHash } from "node:crypto";
+import { open, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+import type { ProbeInfo } from "./validate.ts";
+
+export const SIDECAR_SCHEMA = "pi-audio-transcript/v1";
+
+export interface SidecarDocument {
+	schema: typeof SIDECAR_SCHEMA;
+	createdAt: string;
+	audio: {
+		path: string;
+		name: string;
+		bytes: number;
+		sha256: string;
+		mime: string;
+		durationSeconds: number | null;
+		sampleRateHz: number | null;
+		channels: number | null;
+		codec: string | null;
+	};
+	transcript: {
+		text: string;
+		words: number;
+		characters: number;
+		language: string | null;
+	};
+	validation: Record<string, unknown>;
+	provider: Record<string, unknown>;
+	raw?: Record<string, unknown>;
+	[key: string]: unknown;
+}
+
+/** `foo.m4a` -> `foo.transcript.json` (dotfiles and extension-less names handled). */
+export function sidecarPathFor(audioPath: string): string {
+	const ext = extname(audioPath);
+	if (!ext || audioPath.startsWith(".") || ext.length > 6) return `${audioPath}.transcript.json`;
+	return `${audioPath.slice(0, audioPath.length - ext.length)}.transcript.json`;
+}
+
+export async function sha256File(path: string): Promise<string> {
+	const hash = createHash("sha256");
+	const fh = await open(path, "r");
+	try {
+		const buf = Buffer.alloc(1024 * 1024);
+		for (;;) {
+			const { bytesRead } = await fh.read(buf, 0, buf.length, null);
+			if (!bytesRead) break;
+			hash.update(buf.subarray(0, bytesRead));
+		}
+	} finally {
+		await fh.close();
+	}
+	return hash.digest("hex");
+}
+
+/** Atomic write: same-directory temp file, fsync-ish, then rename over target. */
+export async function writeJsonAtomic(path: string, doc: unknown): Promise<void> {
+	const tmp = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
+	const fh = await open(tmp, "w");
+	try {
+		await fh.writeFile(`${JSON.stringify(doc, null, 2)}\n`, "utf8");
+		await fh.sync?.();
+	} catch (err) {
+		await fh.close().catch(() => {});
+		await unlink(tmp).catch(() => {});
+		throw err;
+	}
+	await fh.close();
+	await rename(tmp, path);
+}
+
+export function exists(path: string): Promise<boolean> {
+	return stat(path).then(() => true, () => false);
+}
+
+/**
+ * Read real duration / sample rate / codec with ffprobe.
+ * Returns available:false (never throws) when ffprobe is missing, so the
+ * extension still works on machines without ffmpeg.
+ */
+export async function probeAudio(
+	path: string,
+	exec: (cmd: string, args: string[], opts?: { signal?: AbortSignal }) => Promise<{ stdout: string; code: number; stderr?: string }>,
+	signal?: AbortSignal,
+): Promise<ProbeInfo> {
+	const args = ["-v", "error", "-show_entries", "format=duration,size:stream=codec_name,sample_rate,channels", "-of", "json", path];
+	let res: { stdout: string; code: number; stderr?: string };
+	try {
+		res = await exec("ffprobe", args, { signal });
+	} catch (err) {
+		return { available: false, error: `ffprobe could not run: ${err instanceof Error ? err.message : String(err)}` };
+	}
+	if (res.code !== 0 || !res.stdout?.trim()) {
+		return { available: false, error: `ffprobe exit ${res.code}${res.stderr?.trim() ? `: ${res.stderr.trim().slice(0, 160)}` : ""}` };
+	}
+	try {
+		const j = JSON.parse(res.stdout) as {
+			format?: { duration?: string; size?: string };
+			streams?: Array<{ codec_type?: string; codec_name?: string; sample_rate?: string; channels?: number }>;
+		};
+		const audio = (j.streams ?? []).find((s) => s.codec_type === "audio") ?? (j.streams ?? [])[0];
+		return {
+			available: true,
+			durationSeconds: j.format?.duration != null ? Number(j.format.duration) : null,
+			sampleRateHz: audio?.sample_rate != null ? Number(audio.sample_rate) : null,
+			channels: audio?.channels ?? null,
+			codec: audio?.codec_name ?? null,
+		};
+	} catch (err) {
+		return { available: false, error: `ffprobe output was unparseable: ${err instanceof Error ? err.message : String(err)}` };
+	}
+}

package/ui/audio-panel.ts

@@ -0,0 +1,104 @@
+import { homedir } from "node:os";
+import { sep } from "node:path";
+import type { TranscribeConfig } from "../config.ts";
+import { AudioSettingsController, formatBytes, formatTimeout } from "../settings.ts";
+import type { PanelSnapshot, PanelValueStyle } from "./settings-panel.ts";
+
+function compactHomePath(path: string): string {
+	const home = homedir().replace(/[\\/]+$/, "");
+	return path.startsWith(`${home}${sep}`) ? `~${path.slice(home.length)}` : path;
+}
+
+function compactOverrides(overrides: string[]): string {
+	return overrides.length <= 3
+		? overrides.join(", ")
+		: `${overrides.slice(0, 3).join(", ")} +${overrides.length - 3}`;
+}
+
+function apiKeySource(
+	stored: TranscribeConfig,
+	effective: TranscribeConfig,
+	overrides: string[],
+): string {
+	if (!effective.apiKey) return "not configured";
+	if (overrides.includes("API key")) return stored.apiKey ? "env (file also set)" : "environment";
+	return "config file";
+}
+
+function displayValue(
+	stored: string,
+	effective: string,
+	style: PanelValueStyle = "text",
+): { value: string; valueStyle: PanelValueStyle } {
+	return stored === effective
+		? { value: effective, valueStyle: style }
+		: { value: `${effective} (env; file: ${stored})`, valueStyle: "warning" };
+}
+
+export function buildAudioPanelSnapshot(controller: AudioSettingsController): PanelSnapshot {
+	const stored = controller.stored();
+	const effective = controller.effective();
+	const overrides = controller.overrides();
+	const language = displayValue(stored.language ?? "auto", effective.language ?? "auto", effective.language ? "text" : "muted");
+	const model = displayValue(stored.model ?? "auto", effective.model ?? "auto", effective.model ? "text" : "muted");
+	const server = displayValue(stored.baseUrl, effective.baseUrl, "accent");
+	const timeout = displayValue(formatTimeout(stored.timeoutMs), formatTimeout(effective.timeoutMs));
+	const maxSize = displayValue(formatBytes(stored.maxBytes), formatBytes(effective.maxBytes));
+
+	return {
+		title: "Audio Transcribe",
+		summaryLines: [
+			`oMLX speech-to-text · model: ${effective.model ?? "auto"}`,
+		],
+		sections: [
+			{
+				title: "Behavior",
+				rows: [
+					{ key: "autoDetect", label: "Input path hook", value: effective.autoDetect ? "enabled" : "disabled", rawValue: String(stored.autoDetect), valueStyle: effective.autoDetect ? "success" : "muted", kind: "toggle" },
+					{ key: "crossCheck", label: "Validation pass", value: effective.crossCheck ? "enabled" : "disabled", rawValue: String(stored.crossCheck), valueStyle: effective.crossCheck ? "success" : "warning", kind: "toggle" },
+					{ key: "force", label: "Overwrite sidecars", value: effective.force ? "enabled" : "disabled", rawValue: String(stored.force), valueStyle: effective.force ? "warning" : "muted", kind: "toggle" },
+				],
+			},
+			{
+				title: "Recognition",
+				rows: [
+					{ key: "language", label: "Language hint", ...language, rawValue: stored.language ?? "auto", inputHint: "ISO tag such as pt, or auto · Esc cancels", kind: "input" },
+					{ key: "model", label: "Model", ...model, rawValue: stored.model ?? "auto", inputHint: "Model id, or auto · Esc cancels", kind: "input" },
+					{ key: "baseUrl", label: "oMLX server", ...server, rawValue: stored.baseUrl, inputHint: "HTTP(S) host or URL · /v1 is added automatically", kind: "input" },
+				],
+			},
+			{
+				title: "Limits",
+				rows: [
+					{ key: "timeoutMs", label: "Request timeout", ...timeout, rawValue: formatTimeout(stored.timeoutMs), inputHint: "1s to 30m", kind: "input" },
+					{ key: "maxBytes", label: "Max file size", ...maxSize, rawValue: formatBytes(stored.maxBytes), inputHint: "Bytes, KB, MB, GB, or unlimited", kind: "input" },
+				],
+			},
+			{
+				title: "Actions",
+				rows: [
+					{ key: "transcribe", label: "Transcribe a path", value: "open…", kind: "action" },
+					{ key: "status", label: "Server diagnostics", value: "run…", kind: "action" },
+					{ key: "reset", label: "Reset settings", value: "confirm…", valueStyle: "warning", kind: "action" },
+				],
+			},
+		],
+		detailLines: [
+			...(overrides.length
+				? [`Env overrides: ${compactOverrides(overrides)} · file settings still save`]
+				: ["Atomic config · corrupt files are preserved for recovery"]),
+			`Config: ${compactHomePath(controller.configPath())} · API key: ${apiKeySource(stored, effective, overrides)}`,
+		],
+		idleMessage: "Changes save immediately",
+		shortcuts: [
+			{ key: "t", label: "transcribe", action: "transcribe" },
+			{ key: "h", label: "health", action: "status" },
+			{ key: "r", label: "reset", action: "reset" },
+		],
+	};
+}
+
+/** Compare only user-visible config fields; API key remains intentionally hidden. */
+export function panelConfigSummary(config: TranscribeConfig): string {
+	return `${config.autoDetect ? "hook on" : "hook off"}, ${config.crossCheck ? "cross-check on" : "cross-check off"}, ${config.language ?? "auto language"}`;
+}