@maheidem/pi-audio-transcribe 0.2.0

package/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 maheidem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project builds against and vendors patterns from works under the MIT
+License, copyright their respective authors:
+
+- @earendil-works/pi-coding-agent (pi coding agent), including the official
+  `subagent` and `plan-mode` extension examples and RPC documentation.
+- @earendil-works/pi-tui.
+- The local `/loop` extension (same workspace), from which
+  `ui/settings-panel.ts` is vendored.

package/README.md

@@ -0,0 +1,132 @@
+# audio-transcribe
+
+Speech-to-text for [pi](https://github.com/earendil-works/pi) using an **oMLX** server running a Qwen3-ASR model. Give pi an audio file; it transcribes, validates the speech, and persists a JSON transcript sidecar beside the original.
+
+Built and verified against **oMLX 0.6.4** on `http://192.168.31.152:8123` with `Qwen3-ASR-1.7B-8bit`.
+
+## What you get
+
+| Surface | Trigger |
+|---|---|
+| `transcribe_audio` tool | The model calls it when you reference an audio file |
+| `/transcribe` command | You invoke it directly |
+| `input` hook | Audio paths pasted into chat are auto-transcribed before the model sees them |
+
+Per file: **pre-flight → ffprobe → ASR → cross-check pass → validation → atomic JSON sidecar** (`audio.m4a` → `audio.transcript.json`).
+
+## Usage
+
+```
+/transcribe                                             # interactive controls
+/transcribe "/Users/me/Downloads/Medidas da gaveta.m4a"
+/transcribe ./recordings --recursive --lang pt --force
+/transcribe --status                                    # scriptable diagnostics
+```
+
+The bare command opens a responsive control panel in TUI mode. It manages the
+input hook, validation pass, overwrite policy, language/model hints, server,
+timeout, file-size limit, diagnostics, and reset. It can also launch a direct
+transcription. Outside TUI mode the bare command emits status. Existing nested
+forms remain the stable scripting interface.
+
+Flags: `--lang <iso>`, `--model <id>`, `--no-crosscheck`, `--force`, `--recursive`.
+
+Pasting a path into chat also just works, including the backslash-escaped form pi inserts on interactive paste:
+
+```
+> what did I say in /Users/me/Downloads/Medidas\ da\ gaveta.m4a ?
+```
+
+## Configuration
+
+`~/.pi/agent/audio-transcribe.json` (defaults shown):
+
+```json
+{
+  "baseUrl": "http://192.168.31.152:8123/v1",
+  "language": null,
+  "model": null,
+  "timeoutMs": 300000,
+  "crossCheck": true,
+  "autoDetect": true,
+  "maxBytes": 0,
+  "force": false
+}
+```
+
+The file is created on first load, written atomically with owner-only permissions,
+and a corrupt copy is preserved before defaults recover. The panel intentionally
+hides API-key contents; add optional `"apiKey": "..."` by hand or use an
+environment variable.
+
+Precedence: defaults < config file < env (`OMLX_BASE_URL`, `OMLX_API_KEY`, `AUDIO_TRANSCRIBE_{MODEL,LANGUAGE,TIMEOUT_MS,CROSSCHECK,AUTODETECT,MAX_BYTES}`). `language: "auto"` or `null` means *send no hint* and let the server detect. Active environment overrides are called out in the panel instead of silently masking the saved file value.
+
+## Validation
+
+Every transcript gets a deterministic verdict — `ok` / `review` / `no_speech` / `failed` — written into the sidecar with the individual checks.
+
+**Structural:** speech present, repetition/hallucination loops (single-word stutter and multi-word), UTF-8/garble, duration coverage, words-per-second plausibility, language label vs content heuristics.
+
+**Cross-check:** a second ASR pass using the language the server itself reported, compared by word-bigram similarity. Stable audio reproduces byte-for-byte, so divergence is a real instability signal rather than noise.
+
+Measured on a real 102.9 s Portuguese recording: **verdict `ok`, confidence 1.0, cross-check 100 %, ~4.4 s** total (two passes).
+
+## Sidecar format (`pi-audio-transcript/v1`)
+
+```json
+{
+  "schema": "pi-audio-transcript/v1",
+  "audio": { "path": "...", "bytes": 1679661, "sha256": "...", "mime": "audio/mp4",
+             "durationSeconds": 102.867729, "sampleRateHz": 48000, "channels": 1, "codec": "aac" },
+  "transcript": { "text": "Vou gravar aqui as medidas...", "words": 56, "characters": 337, "language": "pt" },
+  "validation": { "verdict": "ok", "confidence": 1, "checks": [...], "recommendations": [...],
+                  "crossCheck": { "performed": true, "similarity": 1 }, "measurements": [...] },
+  "provider": { "name": "oMLX", "baseUrl": "...", "model": "Qwen3-ASR-1.7B-8bit", "engine": "audio_stt" }
+}
+```
+
+`sha256` lets a downstream consumer tell a stale sidecar from a fresh one if the audio changes. Writes are atomic (temp + rename), so an interrupted run never leaves a half-written transcript that looks authoritative.
+
+`validation.measurements` is **additive derived data** — spelled-out numbers like *"vinte seis centímetros"* are also exposed as `{ "value": 26, "unit": "cm" }`. The `transcript.text` is never rewritten, so nothing you dictated is silently altered.
+
+## Verified server behaviour (this is what shapes the design)
+
+These were measured against the live box, not assumed:
+
+- **`duration` in the response is inference latency, not audio length.** A 102.87 s clip reported `duration: 1.72` — a 60× error. Real duration comes from ffprobe, falling back to `segments[].end` (which was accurate to 3 decimal places). The sidecar labels this explicitly.
+- **Unsupported input returns HTTP 500** `unsupported file format`, not a 4xx. Files are therefore pre-flight-checked client-side so the message is actionable and no upload is wasted.
+- **`word_timestamps=true` and `response_format` are accepted but ignored.** This extension makes no claim about word-level timing.
+- **`language` casing is inconsistent** — `"Portuguese"` on auto-detect vs `"portuguese"` when hinted. Always normalized.
+- **Silence is honest**: `text: ""`, `language: null`, `segments[].language: "None"` → surfaced as `no_speech`, not an error.
+- **Formats confirmed working:** wav, mp3, m4a, aac, opus (WhatsApp voice notes).
+
+## Known limitations
+
+- **Auto-detect was wrong on *synthetic* audio.** A TTS-generated Portuguese clip came back labelled `English` with a mangled transcript. On **real** recorded speech auto-detect was correct and stable, so the default stays auto-detect; the language check plus cross-check are the safety net, and a mismatch emits a `language=pt` recommendation rather than silently overriding you.
+- **Heuristic language detection is shallow** — tuned for pt/en/es plus CJK and Cyrillic scripts. Portuguese and Spanish share markers, so `es`/`pt` can be confused on short clips.
+- **No diarization and no word timestamps** — the server does not provide them.
+- **`extractMeasurements` reads literal phrasing.** *"vinte seis centímetros ponto dois milímetros"* becomes `26 cm` + `2 mm`, not necessarily the `26.2 cm` you may have meant. Treat measurements as hints, not resolved values.
+- **Passing mentions of audio paths get transcribed.** The `input` hook stats every candidate and skips missing/directory/non-audio, but a real path mentioned in passing *will* be transcribed. Set `autoDetect: false` if that is unwanted.
+- Existing sidecars are skipped unless `force` is set, so re-transcribing after a config change needs `--force`.
+
+## Install
+
+Published to npm as `@maheidem/pi-audio-transcribe`:
+
+```bash
+pi install npm:@maheidem/pi-audio-transcribe@0.2.0
+```
+
+or install from a local path / add the path to `packages` in `~/.pi/agent/settings.json`, then `/reload`.
+
+Requires `ffprobe` (ffmpeg) on PATH for ground-truth duration; without it the extension still works and falls back to `segments[].end`.
+
+## Development
+
+```bash
+npm install
+npm test          # 68 offline contracts in isolated HOME directories
+npm run typecheck
+```
+
+Architecture: `pipeline.ts` holds all transcription logic and deliberately imports **no pi**, which is what makes the whole flow testable against a fixture server that reproduces the real oMLX quirks. `settings.ts` owns canonical persistent actions, `ui/audio-panel.ts` derives the view, and `index.ts` remains the thin Pi adapter (tool / command / input hook). `omlx.ts` is the HTTP client, `validate.ts` the pure validation functions, `paths.ts` path parsing, and `sidecar.ts` atomic persistence + ffprobe.

package/config.ts

@@ -0,0 +1,174 @@
+/**
+ * Persistent configuration for audio-transcribe.
+ *
+ * Precedence (lowest first): defaults < JSON file < environment. The panel
+ * edits only the JSON layer and reports active environment overrides.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { JsonStore } from "./lib/json-store.ts";
+
+export const CONFIG_PATH = join(homedir(), ".pi", "agent", "audio-transcribe.json");
+
+export interface TranscribeConfig {
+	/** Base URL of the oMLX server, including the /v1 suffix. */
+	baseUrl: string;
+	/** Optional bearer token sent as Authorization header. */
+	apiKey?: string;
+	/** Default language hint; null means server auto-detection. */
+	language: string | null;
+	/** Requested model id; null means discover an audio_stt engine. */
+	model: string | null;
+	/** Request timeout in milliseconds. */
+	timeoutMs: number;
+	/** Run a second ASR pass and compare it. */
+	crossCheck: boolean;
+	/** Auto-transcribe audio paths found in user input. */
+	autoDetect: boolean;
+	/** Skip files larger than this many bytes (0 = no limit). */
+	maxBytes: number;
+	/** Overwrite an existing sidecar instead of skipping it. */
+	force: boolean;
+}
+
+export const DEFAULT_CONFIG: TranscribeConfig = {
+	baseUrl: "http://192.168.31.152:8123/v1",
+	language: null,
+	model: null,
+	timeoutMs: 300_000,
+	crossCheck: true,
+	autoDetect: true,
+	maxBytes: 0,
+	force: false,
+};
+
+function record(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
+function coerceBoolean(value: unknown, fallback: boolean): boolean {
+	if (typeof value === "boolean") return value;
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (["1", "true", "yes", "on"].includes(normalized)) return true;
+		if (["0", "false", "no", "off"].includes(normalized)) return false;
+	}
+	return fallback;
+}
+
+function coerceNumber(value: unknown, fallback: number): number {
+	const parsed = typeof value === "string" ? Number(value) : value;
+	return typeof parsed === "number" && Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+/** Normalize a base URL to end with `/v1` and no trailing slash. */
+export function normalizeBaseUrl(input: string): string {
+	let url = input.trim().replace(/\/+$/, "");
+	if (!url) return DEFAULT_CONFIG.baseUrl;
+	if (!/^https?:\/\//i.test(url)) url = `http://${url}`;
+	if (!/\/v1$/.test(url)) url = `${url}/v1`;
+	return url;
+}
+
+export function normalizeStoredConfig(
+	value: unknown,
+	defaults: TranscribeConfig = DEFAULT_CONFIG,
+): TranscribeConfig {
+	const input = record(value);
+	const language = input.language === null
+		? null
+		: typeof input.language === "string"
+			? (input.language.trim() && input.language.trim().toLowerCase() !== "auto" ? input.language.trim() : null)
+			: defaults.language;
+	const model = input.model === null
+		? null
+		: typeof input.model === "string"
+			? (input.model.trim() || null)
+			: defaults.model;
+	const apiKey = typeof input.apiKey === "string" && input.apiKey.trim()
+		? input.apiKey.trim()
+		: defaults.apiKey;
+
+	return {
+		baseUrl: typeof input.baseUrl === "string" ? normalizeBaseUrl(input.baseUrl) : defaults.baseUrl,
+		apiKey,
+		language,
+		model,
+		timeoutMs: coerceNumber(input.timeoutMs, defaults.timeoutMs),
+		crossCheck: coerceBoolean(input.crossCheck, defaults.crossCheck),
+		autoDetect: coerceBoolean(input.autoDetect, defaults.autoDetect),
+		maxBytes: coerceNumber(input.maxBytes, defaults.maxBytes),
+		force: coerceBoolean(input.force, defaults.force),
+	};
+}
+
+function storeFor(path: string): JsonStore<TranscribeConfig> {
+	return new JsonStore<TranscribeConfig>({
+		path,
+		defaults: DEFAULT_CONFIG,
+		normalize: normalizeStoredConfig,
+	});
+}
+
+/** Read the persistent JSON layer, writing discoverable defaults if absent. */
+export function loadStoredConfig(path: string = CONFIG_PATH): TranscribeConfig {
+	return storeFor(path).load();
+}
+
+export function saveConfig(config: TranscribeConfig, path: string = CONFIG_PATH): TranscribeConfig {
+	return storeFor(path).save(config);
+}
+
+export function resetConfig(path: string = CONFIG_PATH): TranscribeConfig {
+	return storeFor(path).reset();
+}
+
+function fromEnv(env: NodeJS.ProcessEnv): Partial<TranscribeConfig> {
+	const output: Partial<TranscribeConfig> = {};
+	const base = env.OMLX_BASE_URL ?? env.AUDIO_TRANSCRIBE_BASE_URL;
+	if (base) output.baseUrl = normalizeBaseUrl(base);
+	const key = env.OMLX_API_KEY ?? env.AUDIO_TRANSCRIBE_API_KEY;
+	if (key) output.apiKey = key;
+	if (env.AUDIO_TRANSCRIBE_MODEL !== undefined) output.model = env.AUDIO_TRANSCRIBE_MODEL.trim() || null;
+	if (env.AUDIO_TRANSCRIBE_LANGUAGE !== undefined) {
+		const value = env.AUDIO_TRANSCRIBE_LANGUAGE.trim();
+		output.language = !value || value.toLowerCase() === "auto" ? null : value;
+	}
+	if (env.AUDIO_TRANSCRIBE_TIMEOUT_MS !== undefined) {
+		output.timeoutMs = coerceNumber(env.AUDIO_TRANSCRIBE_TIMEOUT_MS, DEFAULT_CONFIG.timeoutMs);
+	}
+	if (env.AUDIO_TRANSCRIBE_CROSSCHECK !== undefined) {
+		output.crossCheck = coerceBoolean(env.AUDIO_TRANSCRIBE_CROSSCHECK, DEFAULT_CONFIG.crossCheck);
+	}
+	if (env.AUDIO_TRANSCRIBE_AUTODETECT !== undefined) {
+		output.autoDetect = coerceBoolean(env.AUDIO_TRANSCRIBE_AUTODETECT, DEFAULT_CONFIG.autoDetect);
+	}
+	if (env.AUDIO_TRANSCRIBE_MAX_BYTES !== undefined) {
+		output.maxBytes = coerceNumber(env.AUDIO_TRANSCRIBE_MAX_BYTES, DEFAULT_CONFIG.maxBytes);
+	}
+	return output;
+}
+
+export function environmentOverrideKeys(env: NodeJS.ProcessEnv = process.env): string[] {
+	const keys: string[] = [];
+	if (env.OMLX_BASE_URL !== undefined || env.AUDIO_TRANSCRIBE_BASE_URL !== undefined) keys.push("server");
+	if (env.OMLX_API_KEY !== undefined || env.AUDIO_TRANSCRIBE_API_KEY !== undefined) keys.push("API key");
+	if (env.AUDIO_TRANSCRIBE_MODEL !== undefined) keys.push("model");
+	if (env.AUDIO_TRANSCRIBE_LANGUAGE !== undefined) keys.push("language");
+	if (env.AUDIO_TRANSCRIBE_TIMEOUT_MS !== undefined) keys.push("timeout");
+	if (env.AUDIO_TRANSCRIBE_CROSSCHECK !== undefined) keys.push("cross-check");
+	if (env.AUDIO_TRANSCRIBE_AUTODETECT !== undefined) keys.push("input hook");
+	if (env.AUDIO_TRANSCRIBE_MAX_BYTES !== undefined) keys.push("max file size");
+	return keys;
+}
+
+/** Resolve defaults < persistent file < environment. */
+export function resolveConfig(
+	env: NodeJS.ProcessEnv = process.env,
+	configPath: string = CONFIG_PATH,
+): TranscribeConfig {
+	return { ...loadStoredConfig(configPath), ...fromEnv(env) };
+}

package/index.ts

@@ -0,0 +1,322 @@
+/**
+ * audio-transcribe — oMLX speech-to-text for pi.
+ *
+ * Give pi an audio file, get a validated transcript persisted beside it.
+ *
+ *   tool    transcribe_audio  — audio paths or directories
+ *   command /transcribe       — direct invocation; /transcribe --status for health
+ *   hook    input             — auto-transcribes audio paths pasted into chat
+ *
+ * All the work lives in pipeline.ts (pi-free, unit-tested); this module only
+ * binds it to pi's tool / command / input surfaces.
+ *
+ * Server facts this is built against (oMLX 0.6.4, verified live on
+ * 192.168.31.152:8123 with Qwen3-ASR-1.7B-8bit):
+ *   - `duration` in the response is INFERENCE LATENCY, not audio length
+ *     (a 102.87 s clip reported 1.72). Real duration = ffprobe / segments[].end.
+ *   - unsupported input returns HTTP 500, so file type is pre-checked here.
+ *   - `word_timestamps` and `response_format` are accepted but ignored.
+ *   - `language` casing varies ("Portuguese" auto vs "portuguese" hinted).
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { resolveConfig, type TranscribeConfig } from "./config.ts";
+import { isAudioPath, listSttModels, serverHealth, type SttModel } from "./omlx.ts";
+import { extractAudioPaths, expandPath, tokenizeArgs } from "./paths.ts";
+import { expandInputs, formatSummary, resolveSttModel, transcribeOne, type FileResult, type PipelineCtx, type Setup } from "./pipeline.ts";
+import { AudioSettingsController, type AudioSettingKey } from "./settings.ts";
+import { buildAudioPanelSnapshot } from "./ui/audio-panel.ts";
+import { SettingsPanel, type PanelResult } from "./ui/settings-panel.ts";
+
+const TAG = "[audio-transcribe]";
+
+/**
+ * Mode-aware output. `ctx.ui.notify` is a no-op in print/JSON mode
+ * (ctx.hasUI === false), so headless runs would silently lose every message.
+ */
+function say(ctx: ExtensionContext, msg: string, level: "info" | "warning" | "error" = "info"): void {
+	if (ctx.hasUI) ctx.ui.notify(msg, level);
+	// eslint-disable-next-line no-console
+	else console.log(msg);
+}
+
+/** Adapt pi's ctx + exec into the pi-free pipeline context. */
+function hostCtx(ctx: ExtensionContext, exec: (c: string, a: string[], o?: { signal?: AbortSignal }) => Promise<{ stdout: string; code: number }>, onProgress?: (m: string) => void): PipelineCtx {
+	return {
+		cwd: ctx.cwd,
+		exec,
+		signal: ctx.signal,
+		onProgress,
+		withQueue: (p, fn) => withFileMutationQueue(p, fn),
+	};
+}
+
+/** Merge per-call overrides onto the resolved config, ignoring undefined. */
+function mergedConfig(overrides: Partial<TranscribeConfig>): TranscribeConfig {
+	const out: TranscribeConfig = { ...resolveConfig() };
+	if (overrides.language !== undefined) out.language = overrides.language;
+	if (overrides.model !== undefined) out.model = overrides.model;
+	if (overrides.crossCheck !== undefined) out.crossCheck = overrides.crossCheck;
+	if (overrides.force !== undefined) out.force = overrides.force;
+	if (overrides.baseUrl !== undefined) out.baseUrl = overrides.baseUrl;
+	if (overrides.apiKey !== undefined) out.apiKey = overrides.apiKey;
+	if (overrides.timeoutMs !== undefined) out.timeoutMs = overrides.timeoutMs;
+	if (overrides.autoDetect !== undefined) out.autoDetect = overrides.autoDetect;
+	if (overrides.maxBytes !== undefined) out.maxBytes = overrides.maxBytes;
+	return out;
+}
+
+export default function (pi: ExtensionAPI) {
+	// Cache model discovery briefly so a batch does not re-query the server.
+	let cached: Setup | null = null;
+	let cachedAt = 0;
+	async function getSetup(force = false): Promise<Setup> {
+		if (cached && !force && Date.now() - cachedAt < 60_000) return cached;
+		cached = await resolveSttModel(resolveConfig());
+		cachedAt = Date.now();
+		return cached;
+	}
+
+	async function reportStatus(ctx: ExtensionContext): Promise<void> {
+		const cfg = resolveConfig();
+		const health = await serverHealth(cfg.baseUrl, cfg.apiKey, 8_000, ctx.signal);
+		const setup = await getSetup(true);
+		const models = health.reachable
+			? await listSttModels(cfg.baseUrl, cfg.apiKey, 8_000, ctx.signal).catch(() => [] as SttModel[])
+			: [];
+		say(
+			ctx,
+			[
+				`${TAG} status`,
+				`  server:      ${cfg.baseUrl}`,
+				`  status:      ${health.reachable ? `ok (oMLX ${health.version})` : `UNREACHABLE — ${health.error}`}`,
+				`  model:       ${setup.model ?? "none discovered"}`,
+				`  resident:    ${setup.modelInfo?.loaded ? "yes" : "no (cold load on first use)"}`,
+				`  language:    ${cfg.language ?? "auto-detect (default)"}`,
+				`  cross-check: ${cfg.crossCheck ? "on" : "off"}`,
+				`  input hook:  ${cfg.autoDetect ? "on" : "off"}`,
+				`  stt models:  ${models.length ? models.map((model) => `${model.id}${model.loaded ? " *" : ""}`).join(", ") : "none"}`,
+			].join("\n"),
+			health.reachable ? "info" : "error",
+		);
+	}
+
+	async function runTranscription(raw: string, ctx: ExtensionCommandContext): Promise<void> {
+		const overrides: Partial<TranscribeConfig> = {};
+		const paths: string[] = [];
+		let recursive = false;
+		const tokens = tokenizeArgs(raw);
+		for (let index = 0; index < tokens.length; index++) {
+			const token = tokens[index]!;
+			if (token === "--no-crosscheck") overrides.crossCheck = false;
+			else if (token === "--force") overrides.force = true;
+			else if (token === "--recursive") recursive = true;
+			else if (token.startsWith("--lang=")) overrides.language = token.slice(7);
+			else if (token.startsWith("--model=")) overrides.model = token.slice(8);
+			else if (token === "--lang") overrides.language = tokens[++index] ?? null;
+			else if (token === "--model") overrides.model = tokens[++index] ?? null;
+			else paths.push(expandPath(token, ctx.cwd));
+		}
+
+		const effective = mergedConfig(overrides);
+		let setup = await getSetup(Boolean(overrides.model));
+		setup = { ...setup, cfg: effective };
+		const files = await expandInputs(paths, ctx.cwd, recursive);
+		if (!files.length) {
+			say(ctx, `${TAG} no audio files matched: ${paths.join(", ") || "(no path given)"}`, "error");
+			return;
+		}
+
+		say(ctx, `${TAG} transcribing ${files.length} file(s) via ${setup.model ?? "…"}`, "info");
+		const host = hostCtx(ctx, (command, args, options) => pi.exec(command, args, options), (message) => say(ctx, `${TAG} ${message}`, "info"));
+		const results: FileResult[] = [];
+		for (const file of files) {
+			if (ctx.signal?.aborted) {
+				results.push({ input: file, audioPath: file, sidecarPath: null, skipped: true, skipReason: "cancelled" });
+				continue;
+			}
+			results.push(await transcribeOne(file, setup, host));
+		}
+		const done = results.filter((result) => !result.skipped && !result.error);
+		say(ctx, `${TAG}\n${formatSummary(results, setup, ctx.cwd)}`, "info");
+		for (const result of done) say(ctx, `\n--- ${result.audioPath.split("/").pop()} ---\n${result.text}`, "info");
+	}
+
+	async function openPanel(ctx: ExtensionCommandContext): Promise<void> {
+		if (ctx.mode !== "tui") {
+			await reportStatus(ctx);
+			return;
+		}
+
+		const controller = new AudioSettingsController();
+		let initialKey = "autoDetect";
+		for (;;) {
+			const result = await ctx.ui.custom<PanelResult>(
+				(tui, theme, keybindings, done) => new SettingsPanel({
+					theme,
+					keybindings,
+					initialKey,
+					snapshot: () => buildAudioPanelSnapshot(controller),
+					apply: (key, rawValue) => {
+						const error = controller.apply(key as AudioSettingKey, rawValue);
+						if (!error) cached = null;
+						return error;
+					},
+					activate: (key) => ["transcribe", "status", "reset"].includes(key)
+						? { kind: "close", action: key }
+						: { kind: "error", message: `Unknown audio action: ${key}` },
+					requestRender: () => tui.requestRender(),
+					done,
+				}),
+				{
+					overlay: true,
+					overlayOptions: {
+						anchor: "center",
+						width: 78,
+						minWidth: 44,
+						maxHeight: "90%",
+						margin: 1,
+					},
+				},
+			);
+
+			if (!result?.action) return;
+			if (result.action === "status") {
+				await reportStatus(ctx);
+				initialKey = "status";
+				continue;
+			}
+			if (result.action === "transcribe") {
+				const path = await ctx.ui.input("Audio file or directory", "");
+				if (path?.trim()) await runTranscription(JSON.stringify(path.trim()), ctx);
+				return;
+			}
+			if (result.action === "reset") {
+				const confirmed = await ctx.ui.confirm("Reset Audio Transcribe?", "Restore every file-backed setting to its shipped default?");
+				if (confirmed) {
+					controller.reset();
+					cached = null;
+					say(ctx, `${TAG} settings reset to defaults.`);
+				}
+				initialKey = "reset";
+			}
+		}
+	}
+
+	pi.registerTool({
+		name: "transcribe_audio",
+		label: "Transcribe audio",
+		description:
+			"Transcribe audio files with the oMLX STT server (Qwen3-ASR), validate the speech, and persist a JSON sidecar beside each file as <name>.transcript.json. Accepts audio file paths, or directories whose audio files are transcribed. Use this whenever the user references an audio file, recording, or voice note and wants its spoken content — the read tool cannot open audio.",
+		promptSnippet: "Transcribe audio via oMLX STT with validation + JSON transcript sidecar beside the file",
+		promptGuidelines: [
+			"Use transcribe_audio for any audio file the user references instead of the read tool; it returns the transcript text and writes <name>.transcript.json next to the audio.",
+			"transcribe_audio defaults to server-side language auto-detection; pass language only when the user names one, or when a 'review' verdict recommends pinning it.",
+			"If transcribe_audio returns verdict 'review' or 'failed', report the reason and recommendations to the user instead of presenting the transcript as fact.",
+			"transcribe_audio skips files whose sidecar already exists unless force is true; re-read the existing .transcript.json before assuming a file was transcribed fresh.",
+		],
+		parameters: Type.Object({
+			paths: Type.Array(Type.String(), { description: "Audio file paths, or directories containing audio" }),
+			language: Type.Optional(Type.String({ description: "ISO language hint such as 'pt' or 'en'. Omit for server auto-detect (the default)." })),
+			model: Type.Optional(Type.String({ description: "Override the STT model id. Omit to auto-discover the server's audio_stt engine." })),
+			crossCheck: Type.Optional(Type.Boolean({ description: "Re-transcribe and compare to measure stability. Defaults to config (true)." })),
+			force: Type.Optional(Type.Boolean({ description: "Overwrite existing sidecars. Default false." })),
+			recursive: Type.Optional(Type.Boolean({ description: "Recurse into directories. Default false." })),
+		}),
+
+		async execute(_id, params, signal, onUpdate, ctx) {
+			const cfg = mergedConfig({
+				...(params.language !== undefined ? { language: params.language } : {}),
+				...(params.model !== undefined ? { model: params.model } : {}),
+				...(params.crossCheck !== undefined ? { crossCheck: params.crossCheck } : {}),
+				...(params.force !== undefined ? { force: params.force } : {}),
+			});
+			let setup = await getSetup(Boolean(params.model));
+			setup = { ...setup, cfg };
+
+			const files = await expandInputs(params.paths, ctx.cwd, params.recursive ?? false);
+			if (!files.length) {
+				const h = await serverHealth(cfg.baseUrl, cfg.apiKey, 8_000, signal);
+				throw new Error(
+					`No audio files matched ${JSON.stringify(params.paths)}. ` +
+						(h.reachable ? `Server reachable (oMLX ${h.version}); STT model: ${setup.model ?? "none exposed"}.` : `Server unreachable: ${h.error}`),
+				);
+			}
+
+			const host = hostCtx(ctx, (c, a, o) => pi.exec(c, a, o), (m) => onUpdate?.({ content: [{ type: "text", text: m }], details: {} }));
+			const results: FileResult[] = [];
+			for (let i = 0; i < files.length; i++) {
+				if (signal?.aborted) {
+					results.push({ input: files[i]!, audioPath: files[i]!, sidecarPath: null, skipped: true, skipReason: "cancelled" });
+					continue;
+				}
+				onUpdate?.({ content: [{ type: "text", text: `${i + 1}/${files.length} ${files[i]!.split("/").pop()}` }], details: { index: i, total: files.length } });
+				results.push(await transcribeOne(files[i]!, setup, host));
+			}
+
+			const summary = formatSummary(results, setup, ctx.cwd);
+			const done = results.filter((r) => !r.skipped && !r.error);
+			const body = done.length
+				? `${summary}\n\n--- TRANSCRIPTS ---\n${done.map((r) => `## ${(r.audioPath.split("/").pop() ?? r.audioPath)} [${r.verdict}, ${((r.confidence ?? 0) * 100).toFixed(0)}%, ${r.language ?? "?"}]\n${r.text}`).join("\n\n")}`
+				: summary;
+			return {
+				content: [{ type: "text", text: body }],
+				details: { model: setup.model, results: results.map(({ text, ...rest }) => rest) },
+			};
+		},
+	});
+
+	pi.registerCommand("transcribe", {
+		description: "Open audio-transcription controls or transcribe with /transcribe <path|dir> [flags]",
+		getArgumentCompletions: (prefix: string) => {
+			const options = ["--status", "--lang ", "--model ", "--no-crosscheck", "--force", "--recursive "]
+				.filter((option) => option.startsWith(prefix));
+			return options.length ? options.map((value) => ({ value, label: value })) : null;
+		},
+		async handler(args, ctx) {
+			const raw = (args ?? "").trim();
+			if (!raw) {
+				await openPanel(ctx);
+				return;
+			}
+			if (raw === "--status") {
+				await reportStatus(ctx);
+				return;
+			}
+			await runTranscription(raw, ctx);
+		},
+	});
+
+	// Auto-transcribe audio paths pasted into chat and hand the transcript to
+	// the model inline, so audio never reaches the model as an opaque path.
+	pi.on("input", async (event, ctx) => {
+		if (!resolveConfig().autoDetect) return { action: "continue" as const };
+		if (event.source === "extension") return { action: "continue" as const }; // avoid self-triggering
+		const found = extractAudioPaths(event.text ?? "");
+		if (!found.length) return { action: "continue" as const };
+
+		const setup = await getSetup();
+		if (!setup.model) return { action: "continue" as const };
+
+		const blocks: string[] = [];
+		for (const p of found) {
+			const abs = expandPath(p, ctx.cwd);
+			const st = await (await import("node:fs/promises")).stat(abs).catch(() => null);
+			if (!st || st.isDirectory() || !isAudioPath(abs)) continue; // ignore passing mentions of absent files
+			say(ctx, `${TAG} auto-transcribing ${abs.split("/").pop()}`, "info");
+			const r = await transcribeOne(abs, setup, hostCtx(ctx, (c, a, o) => pi.exec(c, a, o)));
+			if (r.error) blocks.push(`[audio-transcribe] ${abs}: FAILED — ${r.error}`);
+			else if (r.skipped) blocks.push(`[audio-transcribe] ${abs}: skipped — ${r.skipReason}`);
+			else {
+				const head = `[audio-transcribe] ${abs}\nverdict=${r.verdict} confidence=${((r.confidence ?? 0) * 100).toFixed(0)}% language=${r.language ?? "?"} duration=${r.durationSeconds?.toFixed(1) ?? "?"}s sidecar=${r.sidecarPath}`;
+				blocks.push(`${head}\ntranscript:\n${r.text}`);
+				if (r.recommendations?.length) blocks.push(`advice: ${r.recommendations.join(" | ")}`);
+			}
+		}
+		if (!blocks.length) return { action: "continue" as const };
+		return { action: "transform" as const, text: `${event.text}\n\n${blocks.join("\n\n")}` };
+	});
+}