@xynogen/pix-9router 0.4.4 → 0.6.0

package/src/recorder.ts

@@ -0,0 +1,103 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { findExecutableSync } from "@xynogen/pix-runtime/which";
+
+export function parsePulseSources(output: string): string[] {
+	return output
+		.split("\n")
+		.map((line) => line.split("\t")[1]?.trim())
+		.filter((name): name is string => Boolean(name));
+}
+
+export function parseRmsDb(output: string): number | undefined {
+	const matches = [
+		...output.matchAll(/(?:RMS level dB:\s*|lavfi\.astats\.Overall\.RMS_level=)(-?\d+(?:\.\d+)?)/g),
+	];
+	const value = matches.at(-1)?.[1];
+	return value === undefined ? undefined : Number(value);
+}
+
+export function ffmpegRecordArgs(device: string, output: string): string[] {
+	return [
+		"-hide_banner",
+		"-loglevel",
+		"info",
+		"-f",
+		"pulse",
+		"-i",
+		device,
+		"-ac",
+		"1",
+		"-ar",
+		"16000",
+		"-af",
+		"astats=metadata=1:reset=1,ametadata=print:key=lavfi.astats.Overall.RMS_level",
+		"-y",
+		output,
+	];
+}
+
+function run(command: string, args: string[]): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (data) => (stdout += String(data)));
+		child.stderr.on("data", (data) => (stderr += String(data)));
+		child.once("error", reject);
+		child.once("exit", (code) =>
+			code === 0
+				? resolve(stdout)
+				: reject(new Error(stderr.trim() || `${command} exited ${code}`)),
+		);
+	});
+}
+
+export async function microphoneDevices(): Promise<string[]> {
+	const pactl = findExecutableSync("pactl");
+	if (!pactl) return ["default"];
+	const names = parsePulseSources(await run(pactl, ["list", "short", "sources"]));
+	return [...new Set(["default", ...names])];
+}
+
+export interface Recording {
+	path: string;
+	stop(): Promise<number | undefined>;
+}
+
+export function startRecording(device: string, onLevel: (db: number) => void): Recording {
+	const ffmpeg = findExecutableSync("ffmpeg");
+	if (!ffmpeg) throw new Error("Microphone recording needs ffmpeg on PATH.");
+	const path = join(tmpdir(), `pix-stt-${randomUUID()}.wav`);
+	const child = spawn(ffmpeg, ffmpegRecordArgs(device, path), {
+		stdio: ["pipe", "ignore", "pipe"],
+	});
+	let stderr = "";
+	let lastLevel: number | undefined;
+	child.stderr.on("data", (data) => {
+		const text = String(data);
+		stderr += text;
+		const level = parseRmsDb(text);
+		if (level !== undefined) {
+			lastLevel = level;
+			onLevel(level);
+		}
+	});
+	const exit = new Promise<void>((resolve, reject) => {
+		child.once("error", reject);
+		child.once("exit", (code) =>
+			code === 0 ? resolve() : reject(new Error(stderr.trim() || `ffmpeg exited ${code}`)),
+		);
+	});
+	return {
+		path,
+		async stop() {
+			child.stdin.write("q");
+			child.stdin.end();
+			await exit;
+			return lastLevel;
+		},
+	};
+}

package/src/stt-command.ts

@@ -0,0 +1,127 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
+import {
+	frameModal,
+	modalOverlayOptions,
+	modalWidth,
+	terminalModalHeight,
+} from "@xynogen/pix-pretty/modal-frame";
+import { routerDefaults, saveDefaults } from "./defaults.js";
+import { microphoneDevices, type Recording, startRecording } from "./recorder.js";
+import { transcribeAudioFile } from "./transcribe.js";
+
+function levelBar(db: number | undefined): string {
+	if (db === undefined) return "░".repeat(24);
+	const count = Math.max(0, Math.min(24, Math.round(((db + 60) / 60) * 24)));
+	return `${"█".repeat(count)}${"░".repeat(24 - count)}`;
+}
+
+async function record(
+	ctx: ExtensionCommandContext,
+	devices: string[],
+): Promise<string | undefined> {
+	return (
+		(await ctx.ui.custom<string | null>(
+			(tui, theme, _keybindings, done) => {
+				let deviceIndex = Math.max(0, devices.indexOf(routerDefaults.sttDevice));
+				let recording: Recording | undefined;
+				let level: number | undefined;
+				let error = "";
+				let stopping = false;
+
+				const stop = async () => {
+					if (!recording || stopping) return;
+					stopping = true;
+					try {
+						const current = recording;
+						await current.stop();
+						done(current.path);
+					} catch (cause) {
+						error = cause instanceof Error ? cause.message : String(cause);
+						recording = undefined;
+						stopping = false;
+						tui.requestRender();
+					}
+				};
+
+				return {
+					render(width: number) {
+						const device = devices[deviceIndex] ?? "default";
+						return frameModal({
+							width: modalWidth(width),
+							maxHeight: terminalModalHeight(tui.terminal?.rows),
+							title: "Microphone",
+							titleColor: (text) => theme.fg("accent", theme.bold(text)),
+							header: [""],
+							body: [
+								`${theme.fg("dim", "input")}  ${theme.fg("success", device)}`,
+								"",
+								`${theme.fg("dim", "level")}  ${theme.fg(level !== undefined && level > -12 ? "warning" : "success", levelBar(level))} ${level === undefined ? "" : `${level.toFixed(1)} dB`}`,
+								"",
+								theme.fg(error ? "error" : "text", error || (recording ? "Recording…" : "Ready")),
+							],
+							footer: [
+								"",
+								theme.fg(
+									"muted",
+									recording
+										? "enter stop and transcribe · esc cancel"
+										: "←→ input · enter record · esc close",
+								),
+							],
+							color: (text) => theme.fg("accent", text),
+							bg: (text) => theme.bg("customMessageBg", text),
+						}).lines;
+					},
+					invalidate: () => {},
+					handleInput(data: string) {
+						if (matchesKey(data, "escape")) {
+							if (recording) void recording.stop().finally(() => done(null));
+							else done(null);
+						} else if (matchesKey(data, "enter")) {
+							if (recording) void stop();
+							else {
+								const device = devices[deviceIndex] ?? "default";
+								try {
+									recording = startRecording(device, (db) => {
+										level = db;
+										tui.requestRender();
+									});
+									routerDefaults.sttDevice = device;
+									saveDefaults(routerDefaults);
+								} catch (cause) {
+									error = cause instanceof Error ? cause.message : String(cause);
+								}
+							}
+						} else if (!recording && (matchesKey(data, "left") || matchesKey(data, "right"))) {
+							const direction = matchesKey(data, "left") ? -1 : 1;
+							deviceIndex = (deviceIndex + direction + devices.length) % devices.length;
+						}
+						tui.requestRender();
+					},
+				};
+			},
+			{ overlay: true, overlayOptions: modalOverlayOptions() },
+		)) ?? undefined
+	);
+}
+
+export default function registerSttCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("stt", {
+		description: "Record microphone audio and put its transcript in the prompt",
+		handler: async (_args, ctx) => {
+			try {
+				const audio = await record(ctx, await microphoneDevices());
+				if (!audio) return;
+				ctx.ui.setStatus("9router-stt", "Transcribing microphone…");
+				const transcript = await transcribeAudioFile(audio);
+				ctx.ui.setEditorText(transcript);
+				ctx.ui.notify("The transcript is in the prompt editor.", "info");
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			} finally {
+				ctx.ui.setStatus("9router-stt", undefined);
+			}
+		},
+	});
+}

package/src/transcribe.ts

@@ -19,6 +19,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { ioTimeoutSignal } from "@xynogen/pix-runtime/io";
 import { Type } from "typebox";
 import { routerBaseUrl } from "./data.js";
+import { routerDefaults } from "./defaults.js";
 import { auth, curl } from "./http.js";
 import { makeRenderCall, makeRenderResult } from "./render.js";
 
@@ -62,7 +63,7 @@ export function mimeType(filePath: string): string {
 	return types[ext] ?? "application/octet-stream";
 }
 
-async function apiMultipart(
+export async function apiMultipart(
 	path: string,
 	filePath: string,
 	model: string,
@@ -295,6 +296,16 @@ export async function buildTranscriptionResult(
 	};
 }
 
+export async function transcribeAudioFile(
+	filePath: string,
+	model = routerDefaults.sttModel,
+	language?: string,
+	signal?: AbortSignal,
+): Promise<string> {
+	const raw = await apiMultipart("/audio/transcriptions", filePath, model, language, signal);
+	return parseTranscriptionResponse(raw);
+}
+
 function compactChars(chars: number | undefined): string {
 	const value = chars ?? 0;
 	if (value < 1_000) return String(value);
@@ -366,7 +377,7 @@ export default function registerTranscribe(pi: ExtensionAPI): void {
 		}),
 
 		async execute(_toolCallId, params, signal, onUpdate) {
-			const model = params.model ?? DEFAULT_MODEL;
+			const model = params.model ?? routerDefaults.sttModel;
 			const filePath = params.file;
 			const outputFile = params.output_file;
 			let apiMsg = "";

package/src/tts.ts

@@ -0,0 +1,210 @@
+/** Text-to-speech through the 9Router `/v1/audio/speech` endpoint. */
+
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { icon } from "@xynogen/pix-pretty/icon-catalog";
+import { humanSize } from "@xynogen/pix-pretty/utils";
+import { ioTimeoutSignal } from "@xynogen/pix-runtime/io";
+import { Type } from "typebox";
+import { routerBaseUrl } from "./data.js";
+import { routerDefaults } from "./defaults.js";
+import { auth } from "./http.js";
+import { makeRenderCall, makeRenderResult } from "./render.js";
+import { resolveOutputPath, validateOutputPath } from "./transcribe.js";
+
+const DEFAULT_FORMAT = "mp3";
+
+type SpeechFormat = "mp3" | "wav" | "opus" | "aac" | "flac";
+
+interface TtsDetails {
+	_type: "ttsResult";
+	outcome: "running" | "success" | "cancelled" | "error";
+	model: string;
+	format: SpeechFormat;
+	output_path: string;
+	bytes?: number;
+}
+
+export function buildSpeechRequest(
+	input: string,
+	model: string,
+	format: SpeechFormat,
+	signal?: AbortSignal,
+): { url: string; init: RequestInit } {
+	const key = auth();
+	return {
+		url: `${routerBaseUrl()}/audio/speech?response_format=${format}`,
+		init: {
+			method: "POST",
+			headers: {
+				...(key ? { Authorization: `Bearer ${key}` } : {}),
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({ model, input }),
+			signal: ioTimeoutSignal(signal),
+		},
+	};
+}
+
+export async function saveSpeech(outputFile: string, audio: Uint8Array): Promise<string> {
+	const path = resolveOutputPath(outputFile);
+	const validation = await validateOutputPath(path);
+	if (!validation.ok) throw new Error(`output_file rejected: ${validation.reason}`);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, audio);
+	return path;
+}
+
+export function playerCommand(path: string, available: ReadonlySet<string>): string[] | undefined {
+	if (available.has("pw-play")) return ["pw-play", path];
+	if (available.has("paplay")) return ["paplay", path];
+	if (available.has("ffplay"))
+		return ["ffplay", "-nodisp", "-autoexit", "-loglevel", "error", path];
+	if (available.has("mpv")) return ["mpv", "--no-video", "--really-quiet", path];
+	return undefined;
+}
+
+async function runPlayer(command: string[]): Promise<boolean> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command[0] ?? "", command.slice(1), { stdio: "ignore" });
+		child.once("error", (error: NodeJS.ErrnoException) => {
+			if (error.code === "ENOENT") resolve(false);
+			else reject(error);
+		});
+		child.once("exit", (code) => {
+			if (code === 0) resolve(true);
+			else reject(new Error(`audio player exited with code ${code ?? "unknown"}`));
+		});
+	});
+}
+
+async function playSpeech(path: string): Promise<void> {
+	for (const name of ["pw-play", "paplay", "ffplay", "mpv"]) {
+		const command = playerCommand(path, new Set([name]));
+		if (command && (await runPlayer(command))) return;
+	}
+	throw new Error("no supported audio player found (pw-play, paplay, ffplay, or mpv)");
+}
+
+export default function registerTts(pi: ExtensionAPI): void {
+	const renderResult = makeRenderResult<TtsDetails>({
+		tool: "tts",
+		target: (details) => basename(details.output_path),
+		meta: (details) => `${humanSize(details.bytes ?? 0)} · ${details.model}`,
+		status: (details) => (details.outcome === "error" ? "error" : "success"),
+	});
+
+	pi.registerTool({
+		name: "tts",
+		label: "Text to speech",
+		renderShell: "self",
+		description:
+			"Convert text to speech through 9Router and save the audio file. Uses NINEROUTER_URL/NINEROUTER_KEY, with legacy ROUTER_API_BASE/ROUTER_API_KEY aliases.",
+		promptSnippet:
+			"tts(input, model?, output_file?, response_format?, play?) — Generate speech with saved /9router defaults.",
+		promptGuidelines: [
+			"tts: Use a model or voice ID from the 9Router TTS catalog. The tool saves and plays audio by default; set play=false for file-only output. Sensitive paths and symlinks are rejected.",
+		],
+		renderCall: makeRenderCall("tts", (args) => String(args.model ?? "")),
+		renderResult,
+		parameters: Type.Object({
+			input: Type.String({ description: "Text to speak" }),
+			model: Type.Optional(
+				Type.String({ description: "9Router TTS model or voice ID. Defaults to /9router." }),
+			),
+			output_file: Type.Optional(
+				Type.String({
+					description: "Audio output path. Defaults to an OS temporary file.",
+				}),
+			),
+			response_format: Type.Optional(
+				Type.Union(
+					[
+						Type.Literal("mp3"),
+						Type.Literal("wav"),
+						Type.Literal("opus"),
+						Type.Literal("aac"),
+						Type.Literal("flac"),
+					],
+					{ description: "Audio format (default: mp3)", default: DEFAULT_FORMAT },
+				),
+			),
+			play: Type.Optional(
+				Type.Boolean({ description: "Play the saved audio before returning (default: true)" }),
+			),
+		}),
+
+		async execute(_id, params, signal, onUpdate) {
+			const format = params.response_format ?? DEFAULT_FORMAT;
+			const model = params.model?.trim() || routerDefaults.ttsModel;
+			const outputFile =
+				params.output_file?.trim() || join(tmpdir(), `pix-tts-${randomUUID()}.${format}`);
+			const outputPath = resolveOutputPath(outputFile);
+			const details: TtsDetails = {
+				_type: "ttsResult",
+				outcome: "running",
+				model,
+				format,
+				output_path: outputPath,
+			};
+			onUpdate?.({
+				content: [{ type: "text", text: `Generating speech with ${model}...` }],
+				details,
+			});
+
+			try {
+				const request = buildSpeechRequest(params.input, model, format, signal);
+				const response = await fetch(request.url, request.init);
+				if (!response.ok) {
+					const message = await response.text().catch(() => "");
+					throw new Error(`API ${response.status}: ${message.slice(0, 500)}`);
+				}
+				const audio = new Uint8Array(await response.arrayBuffer());
+				const saved = await saveSpeech(outputFile, audio);
+				const play = params.play ?? routerDefaults.ttsPlay;
+				if (play) {
+					onUpdate?.({
+						content: [
+							{
+								type: "text",
+								text: `${icon("audio.play")} ${basename(saved)} · ${humanSize(audio.byteLength)}`,
+							},
+						],
+						details,
+					});
+					await playSpeech(saved);
+				}
+				return {
+					content: [
+						{
+							type: "text",
+							text: play
+								? `${icon("audio.stop")} ${basename(saved)} · ${humanSize(audio.byteLength)}`
+								: `${icon("audio.file")} ${saved} · ${humanSize(audio.byteLength)}`,
+						},
+					],
+					details: {
+						...details,
+						outcome: "success" as const,
+						output_path: saved,
+						bytes: audio.byteLength,
+					},
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `TTS failed: ${message}` }],
+					details: {
+						...details,
+						outcome: signal?.aborted ? ("cancelled" as const) : ("error" as const),
+					},
+					isError: true,
+				};
+			}
+		},
+	});
+}