@juicesharp/rpiv-voice 1.4.2

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to `@juicesharp/rpiv-voice` are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.2] - 2026-05-11
+
+### Changed
+- Published to npm — install via `pi install npm:@juicesharp/rpiv-voice`.
+
+## [1.4.1] - 2026-05-11
+
+## [1.4.0] - 2026-05-10
+
+## [1.3.1] - 2026-05-10
+
+### Added
+- Settings screen with ↑/↓ field navigation, equalizer toggle (default off), and auto-persist on close.
+- Live audio-level equalizer bar in the overlay chrome.
+
+### Changed
+- README rewritten with feature overview, key-binding table, and configuration reference.
+
+### Fixed
+- Preflight stage tag preserved across voice-session initialization.
+
+## [1.3.0] - 2026-05-08
+
+### Added
+- `/voice` command for local speech-to-text dictation backed by sherpa-onnx Whisper, with mic capture, live transcript overlay, and settings screen.
+- Rolling partial transcript shown in real time while speaking.
+- Download progress indicator with percent and byte counter on the model splash screen.
+- Configurable keybinding support for the cancel action (no longer hardcoded to Escape).
+
+### Changed
+- Package marked `private: true` (opt-in install only; not part of the auto-install bundle).
+- Internal constants and helper functions extracted for readability (magic numbers named, idioms centralized).
+
+### Fixed
+- Whisper spurious terminal punctuation reduced via longer VAD hangover and trailing-silence padding.
+- Partial model installs are rolled back on failure; stale model directories detected and re-downloaded automatically.
+- STT recognition failures logged to `~/.config/rpiv-voice/errors.log` instead of being silently swallowed.
+- Download splash text uses a simplified Whisper model name.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+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.

package/README.md

@@ -0,0 +1,116 @@
+# rpiv-voice
+
+<div align="center">
+  <a href="https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-voice">
+    <picture>
+      <img src="https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-voice/docs/cover.png" alt="rpiv-voice cover" width="50%">
+    </picture>
+  </a>
+</div>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Talk to [Pi Agent](https://github.com/badlogic/pi-mono) instead of typing. `rpiv-voice` adds the `/voice` slash command — open the overlay, speak, hit `Enter`, and your transcript drops straight into Pi's editor. Speech-to-text runs **entirely on your machine** via [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) Whisper (base multilingual int8). No cloud, no API keys, no telemetry.
+
+![Voice dictation overlay above the Pi editor](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-voice/docs/overlay.jpg)
+
+## Features
+
+- **100% on-device** — audio never leaves your laptop. No accounts, no API keys, no network calls after the first model download.
+- **~99 languages, autodetected** — Whisper base multilingual handles the full Whisper language set with per-utterance autodetection. Switch languages mid-session without changing settings.
+- **Live transcript** — committed lines render as you finish phrases, with a dim rolling partial showing the still-active utterance in real time. What you see is what gets pasted (no waiting for a "proper" final).
+- **VAD-driven chunking** — Silero voice-activity detection breaks long monologues at natural pauses, so latency stays bounded even on a 5-minute rant.
+- **Settings screen built-in** — `Tab` flips to a settings panel showing your active mic, detected language, and a hallucination filter toggle. `Ctrl-S` to save, `Esc` or `Tab` to return to dictation.
+- **Whisper hallucination filter** — strips spurious "Thanks for watching", "[Music]", and repeating-token loops that Whisper sometimes emits on silence. Toggle off if you're dictating short single words.
+- **Pause / resume** — hit `Space` to mute the mic without closing the overlay; great for stepping aside mid-thought.
+- **Localized UI** — overlay, status bar, and settings render in German, English, Spanish, French, Portuguese (European + Brazilian), Russian, and Ukrainian when [`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) is installed. Falls back to English when it isn't.
+- **Honest first-run UX** — the splash overlay shows download progress (percent + bytes), then `Extracting…`, `Verifying…`, `Loading engine…`, `Initializing mic…` before the dictation overlay opens. Half-loaded states never reach you.
+- **Configurable cancel keybinding** — bind cancel to whatever your fingers prefer; no longer hardcoded to `Esc`.
+- **Errors persisted, not swallowed** — recognition failures land in `~/.config/rpiv-voice/errors.log` so you can see why a phrase didn't transcribe.
+
+## Install
+
+`rpiv-voice` is **opt-in** — it's not part of `/rpiv-setup` because the native deps (sherpa-onnx, decibri) are heavyweight. Install it directly:
+
+```sh
+pi install npm:@juicesharp/rpiv-voice
+```
+
+Then restart your Pi session.
+
+### Optional: localized UI
+
+Install `@juicesharp/rpiv-i18n` alongside it to flip the overlay, status bar, and settings strings to your active locale:
+
+```sh
+pi install npm:@juicesharp/rpiv-i18n
+```
+
+`/languages` switches the locale live — no restart.
+
+## Usage
+
+Type `/voice` in Pi's input — the overlay opens with a recording glyph, a session timer, and `Listening…`.
+
+| Key | Action |
+|---|---|
+| *(speak)* | Equalizer animates; transcript fills in live as Whisper decodes |
+| `Enter` | Close overlay, paste transcript into the Pi editor |
+| `Esc` | Close overlay, paste nothing (configurable — see below) |
+| `Space` | Pause / resume the mic |
+| `Tab` | Flip between dictation and settings screens |
+| `Ctrl-S` *(in Settings)* | Save settings to disk |
+
+The dim trailing text after the committed transcript is the rolling partial — it's already part of what will paste, so you can hit `Enter` the moment you're done.
+
+### First run
+
+The first time you run `/voice`, the splash overlay downloads the Whisper base multilingual model (~198 MB compressed, ~157 MB on disk) into `~/.pi/models/whisper-base/`. Subsequent runs load directly from disk in under a second. If a previous download was interrupted, the stale model directory is detected and re-downloaded automatically.
+
+## Configuration
+
+`rpiv-voice` works without any config file. To customize, drop a JSON file at `~/.config/rpiv-voice/voice.json`:
+
+```json
+{
+  "hallucinationFilterEnabled": false
+}
+```
+
+| Field | Default | Effect |
+|---|---|---|
+| `hallucinationFilterEnabled` | `true` | When `false`, keeps Whisper's "Thanks for watching" / "[Music]" / repeating-token loops. Useful when dictating short single words that the filter might mistake for noise. |
+
+You can also flip the toggle interactively from the **Settings** screen (`Tab` from dictation, `Ctrl-S` to save).
+
+The microphone is the OS default input — `rpiv-voice` does not expose device selection. The bundled Whisper base multilingual model is loaded from `~/.pi/models/whisper-base/`; alternative models aren't supported today.
+
+## Privacy
+
+- **No cloud STT.** Audio is decoded on your CPU via sherpa-onnx; nothing leaves the machine.
+- **No telemetry.** No usage events, no crash reports, no install pings. Errors are written to a local log only.
+- **No API keys.** Nothing to provision, nothing to revoke.
+- **Network only on first run** — to download the model. After that, `/voice` works offline.
+
+## Requirements
+
+- [Pi Agent CLI](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
+- A working microphone reachable by [`decibri`](https://www.npmjs.com/package/decibri) (mic permission granted to your terminal on macOS)
+- ~200 MB free disk under `~/.pi/models/whisper-base/`
+- Network access on first run only
+
+## Troubleshooting
+
+- **"Microphone init failed"** on the splash — grant your terminal app microphone access (System Settings → Privacy & Security → Microphone on macOS), then re-run `/voice`.
+- **Transcript looks like "Thanks for watching"** — Whisper hallucinated on near-silence; either speak louder/closer, or leave the hallucination filter on (the default).
+- **`/voice` not found** — restart your Pi session after install. If it's still missing, confirm the entry exists in `~/.pi/agent/settings.json`.
+- **Recognition errors** — check `~/.config/rpiv-voice/errors.log` for the underlying sherpa-onnx error.
+
+## Related packages
+
+- [`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) — localizes the `/voice` overlay UI.
+- [`@juicesharp/rpiv-pi`](https://www.npmjs.com/package/@juicesharp/rpiv-pi) — umbrella + `/rpiv-setup` for the rest of the `rpiv-*` family.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/audio/error-log.ts

@@ -0,0 +1,37 @@
+/**
+ * error-log — append-only diagnostic sink for the dictation pipeline.
+ *
+ * The pipeline cannot write to stderr (corrupts the active TUI render) and
+ * cannot surface failures via `notify` without churning the chat history. So
+ * recognition errors went silent, leaving users with mysterious gaps in the
+ * transcript and no breadcrumbs.
+ *
+ * This module appends one line per failure to
+ * `~/.config/rpiv-voice/errors.log`. Writes are best-effort and synchronous —
+ * a write failure is itself swallowed (we cannot log the log failure without
+ * re-entering the same hazard).
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const LOG_DIR = join(homedir(), ".config", "rpiv-voice");
+const LOG_PATH = join(LOG_DIR, "errors.log");
+
+export function getErrorLogPath(): string {
+	return LOG_PATH;
+}
+
+export function appendErrorLog(scope: string, err: unknown): void {
+	try {
+		mkdirSync(LOG_DIR, { recursive: true });
+		const message = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+		const line = `${new Date().toISOString()} [${scope}] ${message}\n`;
+		appendFileSync(LOG_PATH, line, "utf-8");
+	} catch {
+		// Best-effort: a logging-path failure must never re-throw into the
+		// dictation pipeline. The TUI is the user's only feedback channel and
+		// stderr would corrupt it.
+	}
+}

package/audio/hallucination-filter.ts

@@ -0,0 +1,71 @@
+// Post-recognition filter for Whisper's well-known silence/near-silence
+// hallucinations. sherpa-onnx-node (and sherpa-onnx itself) don't expose the
+// openai-whisper decoder thresholds — `no_speech_threshold`,
+// `logprob_threshold`, `compression_ratio_threshold` — so we filter the
+// output instead. Combined with the input-side RMS gate this catches the
+// long tail without an engine swap.
+
+// Phrases Whisper emits as the *entire* output of a quiet segment. Matched
+// against the normalized form (lowercase, punctuation+symbols stripped, whitespace
+// collapsed) so "Thanks for watching!" and "thanks  for  watching." both hit.
+const HALLUCINATION_PHRASES: ReadonlySet<string> = new Set([
+	"thanks for watching",
+	"thanks for watching everyone",
+	"thank you for watching",
+	"please subscribe",
+	"please like and subscribe",
+	"see you in the next video",
+	"see you next time",
+	"ill see you in the next video",
+	"subtitles by the amaraorg community",
+	"transcribed by esoteric",
+	"music",
+	"applause",
+	"silence",
+	"you",
+	"thank you",
+	"bye",
+	// Frequent non-English variants (Whisper's multilingual decoder picks these
+	// up on quiet segments regardless of the actual spoken language):
+	"ご視聴ありがとうございました",
+	"次回もお楽しみに",
+	"시청해주셔서 감사합니다",
+	"다음 영상에서 만나요",
+]);
+
+export function isHallucination(text: string): boolean {
+	const normalized = normalize(text);
+	if (!normalized) return true;
+	if (HALLUCINATION_PHRASES.has(normalized)) return true;
+	if (isRepetitionLoop(normalized)) return true;
+	return false;
+}
+
+function normalize(text: string): string {
+	return text
+		.toLowerCase()
+		.replace(/[\p{P}\p{S}]/gu, "")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+// Catches "1/2 1/2 1/2 1/2", "ok ok ok ok", "yes no yes no yes no" — the
+// decoder loop output Whisper falls into on borderline-silent input. Single-
+// token repeats need 4 reps so real emphasis ("yeah yeah yeah") is preserved.
+function isRepetitionLoop(normalized: string): boolean {
+	const tokens = normalized.split(" ").filter(Boolean);
+	if (tokens.length < 4) return false;
+	for (let groupSize = 1; groupSize <= 3; groupSize++) {
+		const minRepeats = groupSize === 1 ? 4 : 3;
+		if (tokens.length < groupSize * minRepeats) continue;
+		let allMatch = true;
+		for (let i = groupSize; i < tokens.length; i++) {
+			if (tokens[i] !== tokens[i % groupSize]) {
+				allMatch = false;
+				break;
+			}
+		}
+		if (allMatch) return true;
+	}
+	return false;
+}

package/audio/mic-source.ts

@@ -0,0 +1,38 @@
+export const TARGET_SAMPLE_RATE = 16000;
+export const FRAMES_PER_BUFFER = 1600;
+
+const VAD_THRESHOLD = 0.5;
+// Hangover before emitting `silence`. decibri's 300 ms default flushed mid-
+// clause at natural breath pauses, which forced Whisper to "complete" an
+// unterminated phrase with a spurious period. 700 ms eliminated that but felt
+// laggy at the user-perceived "I stopped → text appears" gap. 500 ms is the
+// LiveKit value: covers most natural breath pauses, keeps the perceived gap
+// to ~half a second, and the transcribing spinner now papers over the rest.
+const VAD_HOLDOFF_MS = 500;
+
+export interface DecibriLike {
+	on(event: "data", listener: (chunk: Buffer) => void): unknown;
+	on(event: "speech" | "silence", listener: () => void): unknown;
+	once(event: "end" | "error" | "close", listener: (err?: Error) => void): unknown;
+	stop(): void;
+}
+
+interface DecibriCtor {
+	new (opts: Record<string, unknown>): DecibriLike;
+}
+
+export async function createMic(): Promise<DecibriLike> {
+	// decibri ships as CJS (`module.exports = Decibri`); under ESM the ctor lands on `.default`.
+	const mod = (await import("decibri")) as { default: DecibriCtor };
+	const Decibri = mod.default;
+	return new Decibri({
+		sampleRate: TARGET_SAMPLE_RATE,
+		channels: 1,
+		framesPerBuffer: FRAMES_PER_BUFFER,
+		format: "int16",
+		vad: true,
+		vadMode: "silero",
+		vadThreshold: VAD_THRESHOLD,
+		vadHoldoff: VAD_HOLDOFF_MS,
+	});
+}

package/audio/model-download.ts

@@ -0,0 +1,268 @@
+/**
+ * model-download — fetches the multilingual Whisper base model archive into
+ * `~/.pi/models/whisper-base/`, extracts it, prunes unused fp32 duplicates,
+ * and writes a sentinel file marking the install complete.
+ *
+ * The upstream archive ships BOTH fp32 (~290 MB) and int8 (~155 MB) variants
+ * in one tarball. We use int8 for CPU inference, so we delete the fp32
+ * duplicates after extraction to keep on-disk usage to ~157 MB.
+ *
+ * Progress is surfaced phase-by-phase (downloading → extracting → verifying);
+ * we deliberately don't forward per-chunk fetch progress, because callers
+ * pipe phase strings into a single-line ctx.ui.setStatus and per-chunk would
+ * spam the status surface.
+ */
+
+import { execFile } from "node:child_process";
+import { createWriteStream, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { promisify } from "node:util";
+import { t } from "../state/i18n-bridge.js";
+
+const execFileAsync = promisify(execFile);
+
+// ── Paths ────────────────────────────────────────────────────────────────────
+const MODEL_DIR_NAME = "whisper-base";
+export const MODELS_DIR = join(homedir(), ".pi", "models");
+export const WHISPER_BASE_DIR = join(MODELS_DIR, MODEL_DIR_NAME);
+export const SENTINEL_FILE = ".download-complete";
+
+// ── Source archive ───────────────────────────────────────────────────────────
+// Approx archive size on the wire is ~198 MB; the splash now shows the exact
+// total once Content-Length is parsed, so we no longer encode the estimate
+// in any user-facing string. Kept here for documentation only.
+const MODEL_RELEASE_TAG = "asr-models";
+const MODEL_ARCHIVE_NAME = "sherpa-onnx-whisper-base.tar.bz2";
+const MODEL_URL = `https://github.com/k2-fsa/sherpa-onnx/releases/download/${MODEL_RELEASE_TAG}/${MODEL_ARCHIVE_NAME}`;
+
+// ── Files we keep (int8 quantized) ──────────────────────────────────────────
+const ENCODER_FILE = "base-encoder.int8.onnx";
+const DECODER_FILE = "base-decoder.int8.onnx";
+const TOKENS_FILE = "base-tokens.txt";
+const REQUIRED_FILES: readonly string[] = [ENCODER_FILE, DECODER_FILE, TOKENS_FILE];
+
+// ── Files we delete after extraction (fp32 dupes we don't need on CPU) ──────
+const FP32_ENCODER_FILE = "base-encoder.onnx";
+const FP32_DECODER_FILE = "base-decoder.onnx";
+const FP32_DUPLICATE_FILES: readonly string[] = [FP32_ENCODER_FILE, FP32_DECODER_FILE];
+
+// ── Tar invocation ───────────────────────────────────────────────────────────
+const TAR_BIN = "tar";
+// `--strip-components=1` flattens sherpa's top-level wrapper directory so the
+// REQUIRED_FILES land directly inside WHISPER_BASE_DIR.
+const TAR_FLAGS: readonly string[] = ["-xjf"];
+const TAR_STRIP_FLAG = "--strip-components=1";
+
+// ── Status messages ──────────────────────────────────────────────────────────
+// Resolved at progress-emit time (not module load) so live `/languages` flips
+// take effect mid-download.
+const msgDownloading = (): string => t("splash.downloading", "Downloading Whisper…");
+const msgExtracting = (): string => t("splash.extracting", "Extracting model files…");
+const msgVerifying = (): string => t("splash.verifying", "Verifying model files…");
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export interface DownloadProgress {
+	phase: "downloading" | "extracting" | "verifying";
+	/** 0-100 integer when total size is known. Omitted when the server didn't
+	 *  send a Content-Length, or when the phase isn't byte-bounded. */
+	percent?: number;
+	/** Bytes received so far during the download phase (cumulative). */
+	bytesReceived?: number;
+	/** Total expected bytes when known via Content-Length. */
+	totalBytes?: number;
+	message?: string;
+}
+export type ProgressCallback = (progress: DownloadProgress) => void;
+
+// Bound how often we surface byte-count updates: terminals re-flow on every
+// emit and a fast network can fire chunks at >1 kHz, which would burn CPU on
+// no-op renders. 200 ms feels lively without being chatty.
+const PROGRESS_THROTTLE_MS = 200;
+
+export interface ModelPaths {
+	encoderPath: string;
+	decoderPath: string;
+	tokensPath: string;
+}
+
+export type ModelInstallStage = "download" | "extract" | "verify";
+
+/**
+ * Tagged failure surface for `ensureModelDownloaded` — lets callers distinguish
+ * "couldn't fetch the bytes" (network / HTTP) from "got the bytes but the
+ * archive was bad" (tar exit, missing file). Diagnostics matter: previously
+ * every stage rolled up to the same "check your internet connection" string.
+ */
+export class ModelInstallError extends Error {
+	constructor(
+		readonly stage: ModelInstallStage,
+		cause: unknown,
+	) {
+		super(`model install failed at ${stage}`, { cause: cause as Error });
+		this.name = "ModelInstallError";
+	}
+}
+
+export function isModelDownloaded(): boolean {
+	return existsSync(join(WHISPER_BASE_DIR, SENTINEL_FILE));
+}
+
+export function getModelPaths(): ModelPaths {
+	return {
+		encoderPath: join(WHISPER_BASE_DIR, ENCODER_FILE),
+		decoderPath: join(WHISPER_BASE_DIR, DECODER_FILE),
+		tokensPath: join(WHISPER_BASE_DIR, TOKENS_FILE),
+	};
+}
+
+/**
+ * Re-runs the post-extraction file existence check against an "already
+ * downloaded" install. The sentinel only proves the *previous* run wrote it —
+ * a user (or another tool) can have removed a required `.onnx` since then,
+ * which would otherwise surface as an opaque native crash inside
+ * sherpa-onnx's `OfflineRecognizer` constructor. Callers should call this
+ * after `isModelDownloaded()` returns true and *before* loading the engine,
+ * and on failure should `removeModelInstall()` so the next launch redownloads.
+ */
+export function assertModelIntact(): void {
+	verifyModelFiles();
+}
+
+/** Wipe the entire model directory — used to recover from any partial /
+ * corrupt install state. Idempotent and silent on missing dir. */
+export function removeModelInstall(): void {
+	rmSync(WHISPER_BASE_DIR, { recursive: true, force: true });
+}
+
+export async function ensureModelDownloaded(onProgress: ProgressCallback, signal?: AbortSignal): Promise<ModelPaths> {
+	if (isModelDownloaded()) return getModelPaths();
+
+	mkdirSync(WHISPER_BASE_DIR, { recursive: true });
+	const archivePath = join(WHISPER_BASE_DIR, MODEL_ARCHIVE_NAME);
+
+	// Any failure between mkdir and writeSentinel leaves a half-populated
+	// directory (partial archive, partially-extracted .onnx, etc.) but no
+	// sentinel — so the next run would re-enter this function and overwrite,
+	// but only after wasting bandwidth. Wiping the dir on failure makes that
+	// redownload start from a clean slate and prevents a hypothetical
+	// race where another caller observes the partial state mid-run.
+	try {
+		onProgress({ phase: "downloading", message: msgDownloading() });
+		try {
+			let lastEmitMs = 0;
+			await downloadArchive(MODEL_URL, archivePath, signal, (stats) => {
+				const now = Date.now();
+				const isFinal = stats.totalBytes !== undefined && stats.bytesReceived >= stats.totalBytes;
+				if (!isFinal && now - lastEmitMs < PROGRESS_THROTTLE_MS) return;
+				lastEmitMs = now;
+				const percent =
+					stats.totalBytes && stats.totalBytes > 0
+						? Math.min(100, Math.floor((stats.bytesReceived / stats.totalBytes) * 100))
+						: undefined;
+				onProgress({
+					phase: "downloading",
+					message: msgDownloading(),
+					percent,
+					bytesReceived: stats.bytesReceived,
+					totalBytes: stats.totalBytes,
+				});
+			});
+		} catch (err) {
+			throw new ModelInstallError("download", err);
+		}
+
+		onProgress({ phase: "extracting", message: msgExtracting() });
+		try {
+			await extractArchive(archivePath, WHISPER_BASE_DIR);
+			rmSync(archivePath, { force: true });
+			pruneFp32Duplicates();
+		} catch (err) {
+			throw new ModelInstallError("extract", err);
+		}
+
+		onProgress({ phase: "verifying", message: msgVerifying() });
+		try {
+			verifyModelFiles();
+		} catch (err) {
+			throw new ModelInstallError("verify", err);
+		}
+
+		writeSentinel();
+		return getModelPaths();
+	} catch (err) {
+		removeModelInstall();
+		throw err;
+	}
+}
+
+// ── Internals ────────────────────────────────────────────────────────────────
+
+interface DownloadStats {
+	bytesReceived: number;
+	totalBytes?: number;
+}
+
+async function downloadArchive(
+	url: string,
+	destPath: string,
+	signal: AbortSignal | undefined,
+	onStats?: (stats: DownloadStats) => void,
+): Promise<void> {
+	const response = await fetch(url, { signal });
+	if (!response.ok || !response.body) {
+		throw new Error(`Model download failed: HTTP ${response.status}`);
+	}
+
+	// Servers occasionally omit `Content-Length` for chunked / proxied
+	// responses; downstream we treat undefined as "unknown total" and the
+	// splash falls back to a byte-counter without a percentage.
+	const totalBytes = parsePositiveInt(response.headers.get("content-length"));
+
+	let bytesReceived = 0;
+	const tap = new Transform({
+		transform(chunk: Buffer, _enc, cb) {
+			bytesReceived += chunk.length;
+			onStats?.({ bytesReceived, totalBytes });
+			cb(null, chunk);
+		},
+	});
+
+	const out = createWriteStream(destPath);
+	await pipeline(Readable.fromWeb(response.body as never), tap, out, { signal });
+}
+
+const DECIMAL_RADIX = 10;
+
+function parsePositiveInt(raw: string | null | undefined): number | undefined {
+	if (!raw) return undefined;
+	const value = Number.parseInt(raw, DECIMAL_RADIX);
+	return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+async function extractArchive(archivePath: string, destDir: string): Promise<void> {
+	await execFileAsync(TAR_BIN, [...TAR_FLAGS, archivePath, "-C", destDir, TAR_STRIP_FLAG]);
+}
+
+// The Whisper archive ships fp32 + int8 side-by-side (~290 MB of fp32 we
+// don't use on CPU). Drop them so the install settles around ~157 MB.
+function pruneFp32Duplicates(): void {
+	for (const name of FP32_DUPLICATE_FILES) {
+		rmSync(join(WHISPER_BASE_DIR, name), { force: true });
+	}
+}
+
+function verifyModelFiles(): void {
+	for (const name of REQUIRED_FILES) {
+		if (!existsSync(join(WHISPER_BASE_DIR, name))) {
+			throw new Error(`Model verification failed: missing ${name}`);
+		}
+	}
+}
+
+function writeSentinel(): void {
+	writeFileSync(join(WHISPER_BASE_DIR, SENTINEL_FILE), "", "utf-8");
+}

package/audio/pcm.ts

@@ -0,0 +1,45 @@
+// decibri delivers Int16 LE; the STT engine wants Float32 in [-1, +1].
+
+const BYTES_PER_INT16_SAMPLE = 2;
+const INT16_FULL_SCALE = 0x8000;
+
+export function bufferToFloat32(buf: Buffer): Float32Array {
+	const sampleCount = buf.length / BYTES_PER_INT16_SAMPLE;
+	const samples = new Float32Array(sampleCount);
+	for (let i = 0, j = 0; i < buf.length; i += BYTES_PER_INT16_SAMPLE, j++) {
+		samples[j] = buf.readInt16LE(i) / INT16_FULL_SCALE;
+	}
+	return samples;
+}
+
+export function computeRmsInt16(buf: Buffer): number {
+	const sampleCount = Math.floor(buf.length / BYTES_PER_INT16_SAMPLE);
+	if (sampleCount === 0) return 0;
+	let sumSquares = 0;
+	for (let i = 0; i < sampleCount; i++) {
+		const s = buf.readInt16LE(i * BYTES_PER_INT16_SAMPLE) / INT16_FULL_SCALE;
+		sumSquares += s * s;
+	}
+	const rms = Math.sqrt(sumSquares / sampleCount);
+	return clamp01(rms);
+}
+
+export function computeRmsFloat32(samples: Float32Array): number {
+	if (samples.length === 0) return 0;
+	let sumSquares = 0;
+	for (let i = 0; i < samples.length; i++) sumSquares += samples[i] * samples[i];
+	return Math.sqrt(sumSquares / samples.length);
+}
+
+export function clamp01(n: number): number {
+	if (n < 0) return 0;
+	if (n > 1) return 1;
+	return n;
+}
+
+export const BYTES_PER_INT16 = BYTES_PER_INT16_SAMPLE;
+
+/** How many Int16 samples sit in a raw PCM chunk. */
+export function samplesInInt16Chunk(chunk: Buffer): number {
+	return chunk.length / BYTES_PER_INT16_SAMPLE;
+}