@juicesharp/rpiv-voice 1.4.2

package/command/voice-command.ts

@@ -0,0 +1,251 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { createMic, type DecibriLike } from "../audio/mic-source.js";
+import {
+	assertModelIntact,
+	ensureModelDownloaded,
+	getModelPaths,
+	isModelDownloaded,
+	ModelInstallError,
+	removeModelInstall,
+} from "../audio/model-download.js";
+import { createSttEngine, type SttEngine } from "../audio/stt-engine.js";
+import { isHallucinationFilterEnabled, loadVoiceConfig } from "../config/voice-config.js";
+import { getActiveLocale, t } from "../state/i18n-bridge.js";
+import type { VoiceResult } from "../state/state-reducer.js";
+import { VoiceSession } from "../state/voice-session.js";
+import type { SplashPhase } from "../view/components/splash-view.js";
+import { STATUS_BAR_PULSE_FRAME_INTERVAL_MS } from "../view/components/status-bar-view.js";
+import { startDictationPipeline } from "./pipeline-runner.js";
+import { runWithSplash } from "./splash-runner.js";
+
+export const VOICE_COMMAND_NAME = "voice";
+
+// Locales the bundled Whisper base multilingual model recognizes well. Mapped
+// from i18n locale codes; entries not in this set fall back to Whisper's
+// auto-detect (the multilingual model handles ~99 languages, but this keeps
+// us aligned to locales we actively translate to and have tested).
+const WHISPER_SUPPORTED_LANGUAGES: ReadonlySet<string> = new Set([
+	"de",
+	"en",
+	"es",
+	"fr",
+	"it",
+	"ja",
+	"pt",
+	"ru",
+	"uk",
+	"zh",
+]);
+
+// IETF locale tags have an optional region subtag after the first hyphen
+// (e.g. "pt-BR" → "pt"). Whisper's language hint expects just the base.
+const LOCALE_REGION_SEPARATOR = "-";
+const LOCALE_BASE_INDEX = 0;
+
+function baseLanguage(locale: string): string {
+	return locale.split(LOCALE_REGION_SEPARATOR)[LOCALE_BASE_INDEX] ?? locale;
+}
+
+function isWhisperSupported(language: string): boolean {
+	return WHISPER_SUPPORTED_LANGUAGES.has(language);
+}
+
+function whisperLanguageForLocale(locale: string | undefined): string | undefined {
+	if (!locale) return undefined;
+	const base = baseLanguage(locale);
+	return isWhisperSupported(base) ? base : undefined;
+}
+
+const SPLASH_INITIAL_ENGINE: SplashPhase = { kind: "loading_engine" };
+function splashInitialDownload(): SplashPhase {
+	return { kind: "downloading", message: t("splash.preparing", "Preparing model…") };
+}
+
+type PreflightStage = "download" | "extract" | "verify" | "stale_install" | "engine" | "mic";
+
+class PreflightError extends Error {
+	constructor(
+		public readonly stage: PreflightStage,
+		cause: unknown,
+	) {
+		super(`preflight failed at ${stage}`, { cause: cause as Error });
+	}
+}
+
+interface Preflight {
+	sttEngine: SttEngine;
+	mic: DecibriLike;
+}
+
+export function registerVoiceCommand(pi: ExtensionAPI): void {
+	pi.registerCommand(VOICE_COMMAND_NAME, {
+		description: t("command.description", "Dictate text with your voice — local STT, no cloud"),
+		handler: (_args: string, ctx: ExtensionCommandContext) => handleVoiceCommand(ctx),
+	});
+}
+
+async function handleVoiceCommand(ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(t("error.requires_interactive", "/voice requires interactive mode"), "error");
+		return;
+	}
+
+	const preflight = await runPreflight(ctx);
+	if (!preflight) return;
+
+	const result = await runDictationSession(ctx, preflight.sttEngine, preflight.mic);
+	if (result.intent === "commit" && result.transcript) {
+		ctx.ui.pasteToEditor(result.transcript);
+	}
+}
+
+async function runPreflight(ctx: ExtensionCommandContext): Promise<Preflight | null> {
+	try {
+		return await runWithSplash<Preflight>(
+			ctx,
+			{ initialPhase: isModelDownloaded() ? SPLASH_INITIAL_ENGINE : splashInitialDownload() },
+			async (controller) => {
+				if (!isModelDownloaded()) {
+					try {
+						await ensureModelDownloaded((p) => {
+							const message = p.message ?? "";
+							if (p.phase === "downloading")
+								controller.setPhase({
+									kind: "downloading",
+									message,
+									percent: p.percent,
+									bytesReceived: p.bytesReceived,
+									totalBytes: p.totalBytes,
+								});
+							else if (p.phase === "extracting") controller.setPhase({ kind: "extracting", message });
+							else if (p.phase === "verifying") controller.setPhase({ kind: "verifying", message });
+						});
+					} catch (e) {
+						const stage = e instanceof ModelInstallError ? e.stage : "download";
+						throw new PreflightError(stage, e);
+					}
+				}
+
+				controller.setPhase({ kind: "loading_engine" });
+				let sttEngine: SttEngine;
+				try {
+					// The sentinel proves a *prior* run finished cleanly — it does not
+					// guarantee the .onnx files are still present and valid. Re-verify
+					// here so a tampered/partially-deleted install gets caught with a
+					// clear message + auto-recovery instead of an opaque native crash
+					// deep inside sherpa-onnx.
+					try {
+						assertModelIntact();
+					} catch (e) {
+						removeModelInstall();
+						throw new PreflightError("stale_install", e);
+					}
+					const paths = getModelPaths();
+					// Pre-set Whisper's language hint from the active i18n locale when we
+					// have a confident mapping; otherwise fall back to Whisper's built-in
+					// per-utterance auto-detect. Pre-setting trades a small amount of
+					// flexibility for noticeably better accuracy in the user's primary
+					// language and avoids the first-utterance detection latency.
+					sttEngine = await createSttEngine({
+						encoderPath: paths.encoderPath,
+						decoderPath: paths.decoderPath,
+						tokensPath: paths.tokensPath,
+						language: whisperLanguageForLocale(getActiveLocale()),
+					});
+				} catch (e) {
+					// Preserve the inner stage tag (e.g. "stale_install") instead of
+					// flattening every failure in this block to "engine" — the user-
+					// facing copy in preflightUserMessage diverges per stage.
+					if (e instanceof PreflightError) throw e;
+					throw new PreflightError("engine", e);
+				}
+
+				controller.setPhase({ kind: "initializing_mic" });
+				let mic: DecibriLike;
+				try {
+					mic = await createMic();
+				} catch (e) {
+					sttEngine.release();
+					throw new PreflightError("mic", e);
+				}
+
+				return { sttEngine, mic };
+			},
+		);
+	} catch (e) {
+		if (e instanceof PreflightError) {
+			ctx.ui.notify(preflightUserMessage(e.stage), "error");
+		} else {
+			ctx.ui.notify(t("error.engine_load_failed", "Failed to load STT model."), "error");
+		}
+		return null;
+	}
+}
+
+function preflightUserMessage(stage: PreflightStage): string {
+	switch (stage) {
+		case "download":
+			return t("error.model_download_failed", "Failed to download STT model. Check your internet connection.");
+		case "extract":
+			return t("error.model_extract_failed", "Downloaded STT model archive is corrupt. Please retry.");
+		case "verify":
+			return t("error.model_verify_failed", "STT model files are incomplete after download. Please retry.");
+		case "stale_install":
+			return t(
+				"error.model_stale_install",
+				"STT model files were removed or corrupted. They will be redownloaded on next launch.",
+			);
+		case "engine":
+			return t("error.engine_load_failed", "Failed to load STT model.");
+		case "mic":
+			return t(
+				"error.mic_unavailable",
+				"Microphone unavailable. Check that an input device is connected and that Pi has microphone permission.",
+			);
+	}
+}
+
+async function runDictationSession(
+	ctx: ExtensionCommandContext,
+	sttEngine: SttEngine,
+	mic: DecibriLike,
+): Promise<VoiceResult> {
+	const controller = new AbortController();
+	const persistedConfig = loadVoiceConfig();
+
+	let pipelineHandle:
+		| {
+				setPaused: (v: boolean) => void;
+				setHallucinationFilterEnabled: (v: boolean) => void;
+				stop: () => void;
+		  }
+		| undefined;
+	let pulseTick: ReturnType<typeof setInterval> | undefined;
+
+	const result = await ctx.ui.custom<VoiceResult>((tui, theme, _kb, done) => {
+		const session = new VoiceSession({
+			tui,
+			theme,
+			persistedConfig,
+			deps: {
+				pasteToEditor: (text) => ctx.ui.pasteToEditor(text),
+				notify: (message, level) => ctx.ui.notify(message, level),
+				abort: () => controller.abort(),
+				stopMic: () => pipelineHandle?.stop(),
+				setPipelinePaused: (paused) => pipelineHandle?.setPaused(paused),
+				setHallucinationFilterEnabled: (enabled) => pipelineHandle?.setHallucinationFilterEnabled(enabled),
+			},
+			done,
+		});
+		pipelineHandle = startDictationPipeline(mic, sttEngine, session, controller.signal, {
+			hallucinationFilterEnabled: isHallucinationFilterEnabled(persistedConfig),
+		});
+		pulseTick = setInterval(() => session.tickPulse(), STATUS_BAR_PULSE_FRAME_INTERVAL_MS);
+		return session.component;
+	});
+
+	if (pulseTick) clearInterval(pulseTick);
+	if (!controller.signal.aborted) controller.abort();
+	sttEngine.release();
+	return result;
+}

package/config/voice-config.ts

@@ -0,0 +1,80 @@
+/**
+ * voice-config — best-effort persistence of optional rpiv-voice settings
+ * (custom model path, named mic device) at `~/.config/rpiv-voice/voice.json`.
+ *
+ * Both load and save are crash-resistant: malformed JSON or filesystem errors
+ * resolve to "no config". The file is created with 0600 perms because it may
+ * one day hold device IDs that the user doesn't want world-readable.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// ── Filesystem layout ────────────────────────────────────────────────────────
+const CONFIG_DIR_NAME = "rpiv-voice";
+const CONFIG_FILE_NAME = "voice.json";
+const CONFIG_DIR = join(homedir(), ".config", CONFIG_DIR_NAME);
+const CONFIG_PATH = join(CONFIG_DIR, CONFIG_FILE_NAME);
+
+// ── Permissions & formatting ─────────────────────────────────────────────────
+const CONFIG_FILE_MODE = 0o600;
+const JSON_INDENT = 2;
+
+// ── Module-level singleton key (cleared by test/setup beforeEach) ────────────
+const VOICE_STATE_KEY = Symbol.for("rpiv-voice");
+
+export interface VoiceConfig {
+	readonly hallucinationFilterEnabled?: boolean;
+	readonly equalizerEnabled?: boolean;
+}
+
+/**
+ * The hallucination filter defaults to ENABLED. We only persist the off-state
+ * to keep voice.json minimal, which means "field absent" must be read as
+ * "enabled". Centralizing this rule here keeps the three readers in sync —
+ * persisted config, pipeline runtime options, and the in-flight settings
+ * draft all decode the absence the same way.
+ */
+export function isHallucinationFilterEnabled(config: { hallucinationFilterEnabled?: boolean }): boolean {
+	return config.hallucinationFilterEnabled !== false;
+}
+
+/**
+ * The equalizer defaults to DISABLED. Mirror of the hallucination-filter
+ * decoding rule but with the inverted polarity: only the on-state is
+ * persisted, "field absent" reads as "disabled".
+ */
+export function isEqualizerEnabled(config: { equalizerEnabled?: boolean }): boolean {
+	return config.equalizerEnabled === true;
+}
+
+export function loadVoiceConfig(): VoiceConfig {
+	if (!existsSync(CONFIG_PATH)) return {};
+	try {
+		const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) as unknown;
+		if (parsed === null || typeof parsed !== "object") return {};
+		return parsed as VoiceConfig;
+	} catch {
+		return {};
+	}
+}
+
+export function saveVoiceConfig(config: VoiceConfig): void {
+	try {
+		mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+		writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, JSON_INDENT)}\n`, "utf-8");
+	} catch {
+		// best-effort
+	}
+	try {
+		chmodSync(CONFIG_PATH, CONFIG_FILE_MODE);
+	} catch {
+		// best-effort — perms are advisory; the user's umask still wins.
+	}
+}
+
+export function __resetState(): void {
+	const g = globalThis as unknown as { [k: symbol]: unknown };
+	delete g[VOICE_STATE_KEY];
+}

package/docs/cover.svg

@@ -0,0 +1,173 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 800" role="img" aria-label="rpiv-voice — Local voice dictation overlay for Pi" preserveAspectRatio="xMidYMid meet">
+  <title>rpiv-voice — Local voice dictation overlay for Pi</title>
+  <defs>
+    <style>
+      .mono { font-family: 'JetBrains Mono', 'Fira Code', 'SFMono-Regular', ui-monospace, Menlo, Consolas, monospace; }
+      .ink { fill: #F4EFE6; }
+      .muted { fill: #8C8678; }
+      .dim { fill: #4F4A41; }
+      .fade { fill: #6A645A; }
+      .accent { fill: #FF7A3D; }
+      .mint { fill: #6FD0B8; }
+      .rec { fill: #E5594E; }
+    </style>
+    <filter id="grain" x="0" y="0" width="100%" height="100%">
+      <feTurbulence type="fractalNoise" baseFrequency="1.4" numOctaves="2" seed="31"/>
+      <feColorMatrix values="0 0 0 0 0.96  0 0 0 0 0.94  0 0 0 0 0.88  0 0 0 0.04 0"/>
+    </filter>
+    <radialGradient id="vignette" cx="50%" cy="50%" r="70%">
+      <stop offset="55%" stop-color="#070605" stop-opacity="0"/>
+      <stop offset="100%" stop-color="#000" stop-opacity="0.7"/>
+    </radialGradient>
+    <linearGradient id="titleGrad" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#1C1813"/>
+      <stop offset="100%" stop-color="#14110D"/>
+    </linearGradient>
+    <filter id="winShadow" x="-10%" y="-10%" width="120%" height="130%">
+      <feDropShadow dx="0" dy="14" stdDeviation="22" flood-color="#000" flood-opacity="0.6"/>
+    </filter>
+    <clipPath id="wclip"><rect x="64" y="56" width="1152" height="688" rx="12"/></clipPath>
+    <linearGradient id="eqFade" x1="0" x2="1" y1="0" y2="0">
+      <stop offset="0%" stop-color="#6FD0B8" stop-opacity="0.05"/>
+      <stop offset="50%" stop-color="#6FD0B8" stop-opacity="0.95"/>
+      <stop offset="100%" stop-color="#6FD0B8" stop-opacity="0.05"/>
+    </linearGradient>
+    <radialGradient id="recPulse" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#E5594E" stop-opacity="0.45"/>
+      <stop offset="100%" stop-color="#E5594E" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+
+  <rect width="1280" height="800" fill="#070605"/>
+  <rect width="1280" height="800" filter="url(#grain)" opacity="0.45"/>
+  <rect width="1280" height="800" fill="url(#vignette)"/>
+
+  <rect x="64" y="56" width="1152" height="688" rx="12" fill="#0E0D0B" filter="url(#winShadow)"/>
+
+  <g clip-path="url(#wclip)">
+    <rect x="64" y="56" width="1152" height="44" fill="url(#titleGrad)"/>
+    <line x1="64" y1="100" x2="1216" y2="100" stroke="#2A2620"/>
+    <line x1="64" y1="57" x2="1216" y2="57" stroke="#3A352D" stroke-opacity="0.6"/>
+    <circle cx="92"  cy="78" r="7" fill="#FF5F57"/>
+    <circle cx="120" cy="78" r="7" fill="#FFBD2E"/>
+    <circle cx="148" cy="78" r="7" fill="#28C840"/>
+    <text class="mono muted" x="640" y="84" font-size="14" letter-spacing="1.4" text-anchor="middle">~/rpiv-mono &#8212; pi &#8212; rpiv-voice</text>
+
+    <!-- Section label -->
+    <text class="mono dim" x="120" y="156" font-size="12" letter-spacing="2.4">/VOICE &#8212; LIVE TRANSCRIPT</text>
+
+    <!-- Live transcript: committed lines + dim rolling partial -->
+    <text class="mono ink" x="120" y="218" font-size="32">Refactor the splash runner so download progress shows</text>
+    <text class="mono ink" x="120" y="262" font-size="32">percent and bytes on a single line, then keep the same</text>
+    <text class="mono ink" x="120" y="306" font-size="32">format for extracting and verifying.</text>
+    <text class="mono fade" x="120" y="350" font-size="32">Add a unit test that asserts the whisper hallucination&#8230;</text>
+
+    <!-- Mint divider (matches rpiv-voice overlay) -->
+    <line x1="120" y1="392" x2="1160" y2="392" stroke="#6FD0B8" stroke-opacity="0.65" stroke-width="1.25"/>
+
+    <!-- Equalizer strip — live VAD waveform feel -->
+    <g transform="translate(120 416)" fill="url(#eqFade)">
+      <rect x="0"    y="36" rx="3" width="10" height="6"/>
+      <rect x="16"   y="32" rx="3" width="10" height="14"/>
+      <rect x="32"   y="20" rx="3" width="10" height="38"/>
+      <rect x="48"   y="26" rx="3" width="10" height="26"/>
+      <rect x="64"   y="14" rx="3" width="10" height="50"/>
+      <rect x="80"   y="22" rx="3" width="10" height="34"/>
+      <rect x="96"   y="8"  rx="3" width="10" height="62"/>
+      <rect x="112"  y="18" rx="3" width="10" height="42"/>
+      <rect x="128"  y="4"  rx="3" width="10" height="70"/>
+      <rect x="144"  y="14" rx="3" width="10" height="50"/>
+      <rect x="160"  y="22" rx="3" width="10" height="34"/>
+      <rect x="176"  y="10" rx="3" width="10" height="58"/>
+      <rect x="192"  y="20" rx="3" width="10" height="38"/>
+      <rect x="208"  y="6"  rx="3" width="10" height="66"/>
+      <rect x="224"  y="16" rx="3" width="10" height="46"/>
+      <rect x="240"  y="0"  rx="3" width="10" height="78"/>
+      <rect x="256"  y="12" rx="3" width="10" height="54"/>
+      <rect x="272"  y="22" rx="3" width="10" height="34"/>
+      <rect x="288"  y="8"  rx="3" width="10" height="62"/>
+      <rect x="304"  y="18" rx="3" width="10" height="42"/>
+      <rect x="320"  y="2"  rx="3" width="10" height="74"/>
+      <rect x="336"  y="14" rx="3" width="10" height="50"/>
+      <rect x="352"  y="24" rx="3" width="10" height="30"/>
+      <rect x="368"  y="10" rx="3" width="10" height="58"/>
+      <rect x="384"  y="20" rx="3" width="10" height="38"/>
+      <rect x="400"  y="6"  rx="3" width="10" height="66"/>
+      <rect x="416"  y="16" rx="3" width="10" height="46"/>
+      <rect x="432"  y="22" rx="3" width="10" height="34"/>
+      <rect x="448"  y="12" rx="3" width="10" height="54"/>
+      <rect x="464"  y="26" rx="3" width="10" height="26"/>
+      <rect x="480"  y="18" rx="3" width="10" height="42"/>
+      <rect x="496"  y="10" rx="3" width="10" height="58"/>
+      <rect x="512"  y="22" rx="3" width="10" height="34"/>
+      <rect x="528"  y="14" rx="3" width="10" height="50"/>
+      <rect x="544"  y="28" rx="3" width="10" height="22"/>
+      <rect x="560"  y="20" rx="3" width="10" height="38"/>
+      <rect x="576"  y="12" rx="3" width="10" height="54"/>
+      <rect x="592"  y="24" rx="3" width="10" height="30"/>
+      <rect x="608"  y="18" rx="3" width="10" height="42"/>
+      <rect x="624"  y="30" rx="3" width="10" height="18"/>
+      <rect x="640"  y="22" rx="3" width="10" height="34"/>
+      <rect x="656"  y="14" rx="3" width="10" height="50"/>
+      <rect x="672"  y="26" rx="3" width="10" height="26"/>
+      <rect x="688"  y="34" rx="3" width="10" height="10"/>
+      <rect x="704"  y="20" rx="3" width="10" height="38"/>
+      <rect x="720"  y="32" rx="3" width="10" height="14"/>
+      <rect x="736"  y="24" rx="3" width="10" height="30"/>
+      <rect x="752"  y="36" rx="3" width="10" height="6"/>
+      <rect x="768"  y="28" rx="3" width="10" height="22"/>
+      <rect x="784"  y="38" rx="3" width="10" height="4"/>
+      <rect x="800"  y="34" rx="3" width="10" height="10"/>
+      <rect x="816"  y="38" rx="3" width="10" height="4"/>
+      <rect x="832"  y="36" rx="3" width="10" height="6"/>
+      <rect x="848"  y="38" rx="3" width="10" height="4"/>
+      <rect x="864"  y="38" rx="3" width="10" height="4"/>
+      <rect x="880"  y="38" rx="3" width="10" height="4"/>
+      <rect x="896"  y="38" rx="3" width="10" height="4"/>
+      <rect x="912"  y="38" rx="3" width="10" height="4"/>
+      <rect x="928"  y="38" rx="3" width="10" height="4"/>
+      <rect x="944"  y="38" rx="3" width="10" height="4"/>
+      <rect x="960"  y="38" rx="3" width="10" height="4"/>
+      <rect x="976"  y="38" rx="3" width="10" height="4"/>
+      <rect x="992"  y="38" rx="3" width="10" height="4"/>
+      <rect x="1008" y="38" rx="3" width="10" height="4"/>
+      <rect x="1024" y="38" rx="3" width="10" height="4"/>
+    </g>
+
+    <!-- Status bar row: red glyph, timer, footer hints -->
+    <circle cx="138" cy="568" r="20" fill="url(#recPulse)"/>
+    <text class="rec mono" x="118" y="576" font-size="26">&#9679;</text>
+    <text class="mono" font-size="20" y="574">
+      <tspan x="158" class="muted" font-weight="700">0:14</tspan>
+      <tspan dx="14" class="dim">&#183;</tspan>
+      <tspan dx="14" class="ink" font-weight="700">Enter</tspan>
+      <tspan dx="8"  class="muted">to paste</tspan>
+      <tspan dx="14" class="dim">&#183;</tspan>
+      <tspan dx="14" class="ink" font-weight="700">Space</tspan>
+      <tspan dx="8"  class="muted">to pause</tspan>
+      <tspan dx="14" class="dim">&#183;</tspan>
+      <tspan dx="14" class="ink" font-weight="700">Tab</tspan>
+      <tspan dx="8"  class="muted">for settings</tspan>
+      <tspan dx="14" class="dim">&#183;</tspan>
+      <tspan dx="14" class="ink" font-weight="700">Esc</tspan>
+      <tspan dx="8"  class="muted">to cancel</tspan>
+    </text>
+
+    <text class="mono muted" x="120" y="640" font-size="13" letter-spacing="2.4">100% ON-DEVICE &#183; WHISPER MULTILINGUAL &#183; ~99 LANGUAGES &#183; NO CLOUD &#183; NO API KEYS</text>
+
+    <!-- Footer chrome -->
+    <rect x="64" y="708" width="1152" height="36" fill="url(#titleGrad)"/>
+    <line x1="64" y1="708" x2="1216" y2="708" stroke="#2A2620"/>
+    <text class="mono" font-size="14" y="731" letter-spacing="1">
+      <tspan x="92" class="accent" font-weight="700">&#9612; rpiv-voice</tspan>
+      <tspan dx="14" class="dim">&#9474;</tspan>
+      <tspan dx="14" class="mint">on-device STT</tspan>
+      <tspan dx="14" class="dim">&#9474;</tspan>
+      <tspan dx="14" class="muted">whisper-base int8</tspan>
+      <tspan dx="14" class="dim">&#9474;</tspan>
+      <tspan dx="14" class="muted">npm:@juicesharp/rpiv-voice</tspan>
+    </text>
+  </g>
+
+  <rect x="64" y="56" width="1152" height="688" rx="12" fill="none" stroke="#3A352D" stroke-width="1"/>
+</svg>

package/docs/equalizer.svg

@@ -0,0 +1,86 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1028 80" role="img" aria-label="rpiv-voice live audio equalizer" preserveAspectRatio="xMidYMid meet">
+  <title>rpiv-voice live audio equalizer</title>
+  <defs>
+    <linearGradient id="eqFade" x1="0" x2="1" y1="0" y2="0">
+      <stop offset="0%" stop-color="#6FD0B8" stop-opacity="0.05"/>
+      <stop offset="50%" stop-color="#6FD0B8" stop-opacity="0.95"/>
+      <stop offset="100%" stop-color="#6FD0B8" stop-opacity="0.05"/>
+    </linearGradient>
+  </defs>
+  <g fill="url(#eqFade)">
+    <rect x="0" y="39" width="6" height="2" rx="3"/>
+    <rect x="14" y="39" width="6" height="2" rx="3"/>
+    <rect x="28" y="39" width="6" height="2" rx="3"/>
+    <rect x="42" y="39" width="6" height="2" rx="3"/>
+    <rect x="56" y="39" width="6" height="2" rx="3"/>
+    <rect x="70" y="37" width="6" height="6" rx="3"/>
+    <rect x="84" y="36" width="6" height="8" rx="3"/>
+    <rect x="98" y="33" width="6" height="14" rx="3"/>
+    <rect x="112" y="29" width="6" height="22" rx="3"/>
+    <rect x="126" y="30" width="6" height="20" rx="3"/>
+    <rect x="140" y="27" width="6" height="26" rx="3"/>
+    <rect x="154" y="28" width="6" height="24" rx="3"/>
+    <rect x="168" y="18" width="6" height="44" rx="3"/>
+    <rect x="182" y="19" width="6" height="42" rx="3"/>
+    <rect x="196" y="20" width="6" height="40" rx="3"/>
+    <rect x="210" y="17" width="6" height="46" rx="3"/>
+    <rect x="224" y="12" width="6" height="56" rx="3"/>
+    <rect x="238" y="8" width="6" height="64" rx="3"/>
+    <rect x="252" y="16" width="6" height="48" rx="3"/>
+    <rect x="266" y="13" width="6" height="54" rx="3"/>
+    <rect x="280" y="11" width="6" height="58" rx="3"/>
+    <rect x="294" y="7" width="6" height="66" rx="3"/>
+    <rect x="308" y="13" width="6" height="54" rx="3"/>
+    <rect x="322" y="11" width="6" height="58" rx="3"/>
+    <rect x="336" y="5" width="6" height="70" rx="3"/>
+    <rect x="350" y="19" width="6" height="42" rx="3"/>
+    <rect x="364" y="9" width="6" height="62" rx="3"/>
+    <rect x="378" y="16" width="6" height="48" rx="3"/>
+    <rect x="392" y="16" width="6" height="48" rx="3"/>
+    <rect x="406" y="9" width="6" height="62" rx="3"/>
+    <rect x="420" y="18" width="6" height="44" rx="3"/>
+    <rect x="434" y="17" width="6" height="46" rx="3"/>
+    <rect x="448" y="16" width="6" height="48" rx="3"/>
+    <rect x="462" y="9" width="6" height="62" rx="3"/>
+    <rect x="476" y="10" width="6" height="60" rx="3"/>
+    <rect x="490" y="12" width="6" height="56" rx="3"/>
+    <rect x="504" y="10" width="6" height="60" rx="3"/>
+    <rect x="518" y="20" width="6" height="40" rx="3"/>
+    <rect x="532" y="9" width="6" height="62" rx="3"/>
+    <rect x="546" y="11" width="6" height="58" rx="3"/>
+    <rect x="560" y="16" width="6" height="48" rx="3"/>
+    <rect x="574" y="14" width="6" height="52" rx="3"/>
+    <rect x="588" y="11" width="6" height="58" rx="3"/>
+    <rect x="602" y="16" width="6" height="48" rx="3"/>
+    <rect x="616" y="13" width="6" height="54" rx="3"/>
+    <rect x="630" y="13" width="6" height="54" rx="3"/>
+    <rect x="644" y="5" width="6" height="70" rx="3"/>
+    <rect x="658" y="8" width="6" height="64" rx="3"/>
+    <rect x="672" y="6" width="6" height="68" rx="3"/>
+    <rect x="686" y="7" width="6" height="66" rx="3"/>
+    <rect x="700" y="12" width="6" height="56" rx="3"/>
+    <rect x="714" y="16" width="6" height="48" rx="3"/>
+    <rect x="728" y="5" width="6" height="70" rx="3"/>
+    <rect x="742" y="14" width="6" height="52" rx="3"/>
+    <rect x="756" y="15" width="6" height="50" rx="3"/>
+    <rect x="770" y="18" width="6" height="44" rx="3"/>
+    <rect x="784" y="18" width="6" height="44" rx="3"/>
+    <rect x="798" y="13" width="6" height="54" rx="3"/>
+    <rect x="812" y="21" width="6" height="38" rx="3"/>
+    <rect x="826" y="15" width="6" height="50" rx="3"/>
+    <rect x="840" y="21" width="6" height="38" rx="3"/>
+    <rect x="854" y="20" width="6" height="40" rx="3"/>
+    <rect x="868" y="26" width="6" height="28" rx="3"/>
+    <rect x="882" y="26" width="6" height="28" rx="3"/>
+    <rect x="896" y="30" width="6" height="20" rx="3"/>
+    <rect x="910" y="32" width="6" height="16" rx="3"/>
+    <rect x="924" y="33" width="6" height="14" rx="3"/>
+    <rect x="938" y="35" width="6" height="10" rx="3"/>
+    <rect x="952" y="37" width="6" height="6" rx="3"/>
+    <rect x="966" y="39" width="6" height="2" rx="3"/>
+    <rect x="980" y="39" width="6" height="2" rx="3"/>
+    <rect x="994" y="39" width="6" height="2" rx="3"/>
+    <rect x="1008" y="39" width="6" height="2" rx="3"/>
+    <rect x="1022" y="39" width="6" height="2" rx="3"/>
+  </g>
+</svg>