@reins-ai/voice 0.0.0-stage → 0.1.0

package/LICENSE

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

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @reins-ai/voice
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local voice for your AI: an MCP server (stdio) with a microphone that listens continuously, Whisper transcription and a natural voice (Piper) to answer, in the language you speak. Everything runs on your machine, with no external services. The AI starts it; the website knows nothing about voice.
+
+## Requirements
+
+- Node 22.
+- [ffmpeg](https://ffmpeg.org) on the PATH (or `--ffmpeg <path>`), with its `ffplay` (included in regular ffmpeg builds).
+
+The first time, it downloads what it needs and verifies each file's hash. Afterwards it works offline:
+
+| What | Purpose | Size | Where |
+| --- | --- | --- | --- |
+| Whisper `whisper-small` | Understanding what you say (about 100 languages) | ~240 MB | `~/.sanoriva-agent/models` |
+| [Silero VAD](https://github.com/snakers4/silero-vad) (MIT) | Telling your voice from noise | ~2 MB | `~/.sanoriva-agent/silero-vad` |
+| [Smart Turn v3](https://github.com/pipecat-ai/smart-turn) (BSD-2) | Telling whether you finished your turn | ~8 MB | `~/.sanoriva-agent` |
+| [Piper](https://github.com/rhasspy/piper) (MIT), pinned version | Speaking with a natural voice | ~25 MB | `~/.sanoriva-agent/piper` |
+| One Piper voice per language | The voice for each language, the first time the AI uses it | 60–110 MB | `~/.sanoriva-agent/voices` |
+
+## Connecting your AI
+
+For Claude Code, in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sanoriva-voice": { "type": "stdio", "command": "npx", "args": ["@reins-ai/voice"] }
+  }
+}
+```
+
+Then ask it to talk with you by voice, in any language.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--language <xx>` | (detected per sentence) | Fixes the 2-letter language (`es`, `en`…). Without it, the language of each sentence is detected (about 1 s more per sentence) and the AI answers in the same one. With it, each sentence is transcribed about 1 s sooner. |
+| `--tts piper \| system` | `piper` | `piper`: natural voice. `system`: the operating system voice (Windows System.Speech, macOS `say`, Linux `espeak-ng`). |
+| `--voice <name>` | (one per language) | A fixed voice from the [Piper catalog](https://huggingface.co/rhasspy/piper-voices), e.g. `es_ES-davefx-medium`. |
+| `--mic "<name>"` | Windows: the first one ffmpeg lists; macOS/Linux: the default | The microphone to use. |
+| `--ffmpeg <path>` | `ffmpeg` | Path to ffmpeg. |
+| `--ffplay <path>` | next to ffmpeg | Path to ffplay. |
+| `--model <id>` | `onnx-community/whisper-small` | The Whisper model. |
+| `--device cpu \| dml` | Windows: `dml`; elsewhere: `cpu` | Where Whisper runs. `dml`: the graphics card through DirectML (it ships with ONNX Runtime, nothing to install), about 1 s faster per sentence; if it fails to load, the CPU is used. |
+| `--setup` | off | Only prepares and exits: checks ffmpeg, ffplay and the microphone, and downloads Whisper, Silero, Smart Turn, Piper and the voice for the language (`--language`) now, so the first conversation does not wait. It reports what is fine and how to fix what is missing. It installs nothing on the system. |
+| `--verbose` | off | Logs what happens to each sentence (closed, Silero, detected language, dropped echo, what was heard, how long speaking took) to `~/.sanoriva-agent/voice.log` and stderr. For troubleshooting. |
+
+## Tools the AI sees
+
+| Tool | What it does |
+| --- | --- |
+| `listen` | Returns what the user said since the last call, or waits for their next sentence (up to 60 s). The first call opens the microphone. |
+| `speak` | Reads a text out loud and returns right away, while it plays, so the AI can act on the page at the same time. With `wait: true` it returns when playback ends (or answers "Cut off" if the user talked over it): this is for reading while highlighting, sentence by sentence. In each response the AI says the highlighted sentence and highlights the next one, which is then ready; if it is cut off, it stops everything and listens. `language` (`es`, `en`, `es_MX`…) is the language of the text, to play it with a voice for that language. |
+| `stop` | Closes the microphone and clears anything heard. |
+
+The AI converses in a loop: `listen` → does what is asked → `speak` → `listen`, answering in the language the user speaks.
+
+## How it listens
+
+- **Continuous:** the microphone stays open from the first `listen`, also while the AI talks, so the user can answer or interrupt at once.
+- **End of turn:** at every 0.3 s pause, Smart Turn (about 100 ms on CPU, 23 languages) looks at the intonation and tells whether the user finished or is only pausing. If they finished, the sentence closes there; otherwise after 1.5 s of silence. It is only asked with at least 1 s of voice (so a short question is not split), never while the AI talks (what is heard is its echo), and one question at a time. It is downloaded once, at a pinned version verified with its SHA-256 hash.
+- **"I heard you":** when the user's sentence closes while the AI listens, a short soft tone plays, so the user knows they were heard while the AI thinks. It does not play for the AI's own echo.
+- **Sentences:** `listen` returns whole sentences. If voice keeps playing in the background (a TV, a video), `listen` does not wait forever: it returns what it understood at most 3 s later, and whatever there is after 60 s; anything still playing goes to the next `listen`. Each new tool call (`speak`, `stop`) ends a waiting `listen`, so the AI can always speak.
+- **Room noise:** when the microphone opens it measures 0.3 s of background noise, and that level lasts the whole conversation: it falls fast with silence and rises very slowly, so voice is never mistaken for noise. Voice only needs to be twice as loud as the noise. It is not learned while the AI talks: the AI's echo is not room noise, and after a minute of reading the user would become inaudible.
+- **Echo:** whatever the microphone picks up of the AI's own voice is dropped by comparing it with what the AI just said. When the AI stops talking, the current sentence (its echo) closes there, so what the user says right after arrives as a separate, whole sentence.
+- **Interrupting the AI:** if the user talks while the AI talks, the AI goes quiet at once. To tell the user's voice from the AI's echo through the speakers, it compares what the microphone hears with what is playing (the Geigel double-talk detector used by hands-free phones): during the first half second of each sentence it learns how much of its voice comes back, and if the microphone hears more than twice that for 0.2 s, it stops Piper and drops its queue (without waiting for Silero, which finds too little voice in a short "stop"). If that does not fire (with loudspeakers, the user's voice and the echo may arrive equally loud), there is a second path: a sentence that started while the AI was talking and carries words the AI was not saying is the user, and it cuts the AI off as soon as Whisper transcribes it (about 1 s). Echo leftovers are dropped because they are the AI's own words. The user's sentence arrives whole on the next `listen`, which starts with "(the user interrupted you while you were speaking)". With the system voice (`--tts system`) what plays is unknown, so it does not cut off. With headphones there is no echo and it always works.
+- **Stray noises:** a "sentence" with less than 0.3 s of voice (a knock, a cough) is not even transcribed.
+- **Language of each sentence:** without `--language`, Whisper checks which language it hears before transcribing (like the original Whisper; transformers.js does not do it by itself and, without a language, would transcribe everything as English) and transcribes in that language.
+- **Only human voice reaches Whisper:** over noise, Whisper makes up sentences (from the subtitles it was trained on, such as "Subscribe!"). To avoid it, every sentence first goes through Silero VAD, which tells human voice from noise in any language; without at least 250 ms of voice it is not transcribed. Silero stops as soon as it finds those 250 ms: ONNX Runtime alternates passes of each model, and going through a whole sentence behind Smart Turn once took 30 s. There is no list of phrases: it works for any language.
+
+## How it speaks
+
+- **Piper** turns the text into audio and **ffplay** plays it while it is generated, so it starts in under half a second. `speak` returns at once; sentences play one after another, and the echo keeps being dropped until each one finishes.
+- **The voice for each language** comes from the official Piper catalog (`voices.json`, at a pinned version): one for the exact variant if any (`es_MX`), otherwise one for its language (`es`); among several, `medium` quality (natural and fast) before `high`, `low` or `x_low`, and on a tie the first by name. It is downloaded the first time and verified with the catalog hashes.
+- **Piper** is downloaded at a pinned version and verified with its SHA-256 hash: it is an executable, so nothing else is accepted.
+- If Piper fails (offline the first time, a platform without Piper…), it speaks with the system voice and logs it.
+
+## Privacy
+
+- Audio never leaves your machine: it is transcribed and spoken locally, then discarded.
+- Only the programs and models in the table above are downloaded, once, and nothing is ever sent.
+- The microphone closes with `stop` (when the user says "stop" or "goodbye") and also by itself if the AI stops listening for 30 s.
+- stdout is the MCP channel; logs go to stderr.

package/dist/barge-in.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Detects whether the user talks while the AI is talking. The microphone also hears the AI's voice from the
+ * speakers (its echo), so hearing a voice is not enough: the microphone level is compared with what is
+ * playing. This is the Geigel double-talk detector used by hands-free phones: if the microphone hears clearly
+ * more than can come back from the speaker, someone else is talking.
+ */
+/**
+ * At the start of each AI sentence, how long to learn how much of its voice comes back through the
+ * microphone.
+ */
+export declare const LEARN_MS = 500;
+/** It is the user if the microphone hears at least this many times what comes back from the speaker… */
+export declare const USER_FACTOR = 2;
+/** …for this long without a break (7 blocks of 30 ms), so a single knock does not cut the AI off. */
+export declare const MIN_USER_MS = 210;
+export declare class EchoGate {
+    private played;
+    private learnUntil;
+    private ratios;
+    /**
+     * How much of the AI's voice comes back through the microphone (0 while unknown). It lasts the whole
+     * conversation.
+     */
+    private coupling;
+    private userFrames;
+    /** Without anything played yet (e.g. with the system voice) there is no way to tell what is echo. */
+    private heardAI;
+    /** A chunk about to play: its level and when it plays. `first` marks the first chunk of a sentence. */
+    play(level: number, at: number, first?: boolean): void;
+    /**
+     * Takes a 30 ms microphone block while the AI talks, with its level and the room's voice threshold. Returns
+     * true once the user has been talking above the echo for MIN_USER_MS.
+     */
+    mic(level: number, now: number, floor: number): boolean;
+    /**
+     * Learns from the start of the sentence: the loudest level that came back, ignoring the top 10 % in case of
+     * a knock. It rises at once and falls slowly, because underestimating it would make the AI cut itself off
+     * with its own echo.
+     */
+    private learn;
+}
+//# sourceMappingURL=barge-in.d.ts.map

package/dist/barge-in.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"barge-in.d.ts","sourceRoot":"","sources":["../src/barge-in.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,QAAQ,MAAM,CAAC;AAC5B,wGAAwG;AACxG,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,qGAAqG;AACrG,eAAO,MAAM,WAAW,MAAM,CAAC;AAa/B,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAAgB;IAC9B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,UAAU,CAAK;IACvB,qGAAqG;IACrG,OAAO,CAAC,OAAO,CAAS;IAExB,uGAAuG;IACvG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,IAAI;IASpD;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAkBvD;;;;OAIG;IACH,OAAO,CAAC,KAAK;CAMd"}

package/dist/barge-in.js

@@ -0,0 +1,78 @@
+/**
+ * Detects whether the user talks while the AI is talking. The microphone also hears the AI's voice from the
+ * speakers (its echo), so hearing a voice is not enough: the microphone level is compared with what is
+ * playing. This is the Geigel double-talk detector used by hands-free phones: if the microphone hears clearly
+ * more than can come back from the speaker, someone else is talking.
+ */
+/**
+ * At the start of each AI sentence, how long to learn how much of its voice comes back through the
+ * microphone.
+ */
+export const LEARN_MS = 500;
+/** It is the user if the microphone hears at least this many times what comes back from the speaker… */
+export const USER_FACTOR = 2;
+/** …for this long without a break (7 blocks of 30 ms), so a single knock does not cut the AI off. */
+export const MIN_USER_MS = 210;
+/**
+ * What plays reaches the microphone with some delay, and the time each chunk plays is approximate (ffplay
+ * takes a while to start), so the loudest level within this window is used.
+ */
+const WINDOW_BEFORE_MS = 600;
+const WINDOW_AFTER_MS = 200;
+export class EchoGate {
+    played = [];
+    learnUntil = 0;
+    ratios = [];
+    /**
+     * How much of the AI's voice comes back through the microphone (0 while unknown). It lasts the whole
+     * conversation.
+     */
+    coupling = 0;
+    userFrames = 0;
+    /** Without anything played yet (e.g. with the system voice) there is no way to tell what is echo. */
+    heardAI = false;
+    /** A chunk about to play: its level and when it plays. `first` marks the first chunk of a sentence. */
+    play(level, at, first = false) {
+        if (first) {
+            this.learnUntil = at + LEARN_MS;
+            this.userFrames = 0;
+        }
+        this.played.push({ at, level });
+        this.heardAI = true;
+    }
+    /**
+     * Takes a 30 ms microphone block while the AI talks, with its level and the room's voice threshold. Returns
+     * true once the user has been talking above the echo for MIN_USER_MS.
+     */
+    mic(level, now, floor) {
+        if (!this.heardAI)
+            return false;
+        this.played = this.played.filter((p) => p.at > now - 2 * WINDOW_BEFORE_MS);
+        let far = 0;
+        for (const p of this.played)
+            if (p.at >= now - WINDOW_BEFORE_MS && p.at <= now + WINDOW_AFTER_MS)
+                far = Math.max(far, p.level);
+        if (now < this.learnUntil && far > 0) {
+            this.ratios.push(level / far);
+            return false;
+        }
+        if (this.ratios.length)
+            this.learn();
+        const echo = this.coupling * far;
+        const user = level > floor && level > USER_FACTOR * echo;
+        this.userFrames = user ? this.userFrames + 1 : 0;
+        return this.userFrames * 30 >= MIN_USER_MS;
+    }
+    /**
+     * Learns from the start of the sentence: the loudest level that came back, ignoring the top 10 % in case of
+     * a knock. It rises at once and falls slowly, because underestimating it would make the AI cut itself off
+     * with its own echo.
+     */
+    learn() {
+        const sorted = [...this.ratios].sort((a, b) => a - b);
+        const measured = sorted[Math.floor(sorted.length * 0.9)] ?? sorted.at(-1);
+        this.coupling = measured >= this.coupling ? measured : 0.9 * this.coupling + 0.1 * measured;
+        this.ratios = [];
+    }
+}
+//# sourceMappingURL=barge-in.js.map

package/dist/barge-in.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"barge-in.js","sourceRoot":"","sources":["../src/barge-in.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import './stdout-guard.js';
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,mBAAmB,CAAC"}

package/dist/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import './stdout-guard.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { join } from 'node:path';
+import { parseConfig } from './config.js';
+import { fileLog, silent } from './log.js';
+import { Ear } from './ear.js';
+import { createFfmpegMic, findWindowsMic } from './mic.js';
+import { createVoiceServer } from './server.js';
+import { createChime, createPiperSpeaker, createSpeaker, speechQueue } from './speak.js';
+import { runSetup, setupSteps } from './setup.js';
+import { createSileroCheck } from './speech-check.js';
+import { createWhisper } from './stt.js';
+import { createTurnCheck } from './turn.js';
+let config;
+try {
+    config = parseConfig(process.argv.slice(2));
+}
+catch (error) {
+    console.error(error.message);
+    process.exit(1);
+}
+// --setup prepares everything for the first conversation and exits without starting the server.
+if (config.setup) {
+    console.error('Preparing the voice (the first time it downloads about 300 MB)…');
+    const ok = await runSetup(setupSteps(config));
+    console.error(ok ? 'All set.' : 'Something is missing: fix it and run --setup again.');
+    process.exit(ok ? 0 : 1);
+}
+const log = config.verbose ? fileLog(join(config.dataDir, 'voice.log')) : silent;
+log('[startup] verbose mode: what happens to each sentence goes to voice.log');
+const device = config.mic ?? (process.platform === 'win32' ? findWindowsMic(config.ffmpeg) : undefined);
+if (process.platform === 'win32' && !device) {
+    console.error('No microphone (or ffmpeg) found. Choose one with --mic "<name>" and ffmpeg with --ffmpeg <path>.');
+    process.exit(1);
+}
+console.error(`Microphone: ${device ?? 'system default'}`);
+// Whisper loads in the background: the server answers right away and listen waits for the model if needed.
+const transcriber = createWhisper({ model: config.model, language: config.language, cacheDir: config.cacheDir, device: config.device, log });
+transcriber.then(() => console.error(`Whisper ready (${config.model}, ${config.device})`), (error) => console.error(`No puedo cargar Whisper: ${error.message}`));
+// Silero VAD (2 MB) separates human voice from noise before Whisper, in any language.
+const speechCheck = createSileroCheck({ cacheDir: config.dataDir });
+speechCheck.then(() => console.error('Voice detector ready (Silero VAD)'), (error) => console.error(`No voice detector (Silero): ${error.message}`));
+// Smart Turn (8 MB) tells at every 0.3 s pause whether the user has finished, so there is no need to wait for
+// 1.5 s of silence.
+const turnCheck = createTurnCheck({ cacheDir: config.dataDir });
+turnCheck.then(() => console.error('End-of-turn detector ready (Smart Turn)'), (error) => console.error(`No end-of-turn detector (Smart Turn): ${error.message}`));
+// Piper gives a natural voice, with the system voice as a fallback. Piper and the voice download in the
+// background at startup.
+const system = createSpeaker({ lang: config.language });
+// The ear gets what is about to play, to tell the AI's echo from the voice of a user who interrupts it.
+const piper = config.tts === 'piper' ? createPiperSpeaker({ ...config, dataDir: config.dataDir, onLevel: (level, at, first) => ear?.playing(level, at, first) }) : undefined;
+piper?.warm();
+const speaker = async (text, language, signal) => {
+    const started = Date.now();
+    if (piper) {
+        try {
+            await piper(text, language, signal);
+            return log(`[voice] Piper · ${language ?? 'no language'} · ${Date.now() - started} ms · «${text}»`);
+        }
+        catch (error) {
+            log(`[voice] Piper failed (${error.message}); using the system voice`);
+            console.error(`Piper could not speak (${error.message}); using the system voice`);
+        }
+    }
+    await system(text, language, signal);
+    log(`[voice] system · ${language ?? 'no language'} · ${Date.now() - started} ms · «${text}»`);
+};
+// Speaking does not block: the AI keeps working while it plays, and each sentence waits for the previous one.
+const say = speechQueue(speaker, (error) => log(`[voice] could not speak: ${error.message}`));
+// The ear starts on the first listen, so the microphone only opens when there is a conversation.
+let ear;
+const server = createVoiceServer({
+    listen: async () => {
+        ear ??= new Ear({
+            openMic: createFfmpegMic({ ffmpeg: config.ffmpeg, device }),
+            transcriber: await transcriber,
+            speechCheck: await speechCheck.catch(() => undefined),
+            turnCheck: await turnCheck.catch(() => undefined),
+            // A short tone when a user sentence closes, so the user knows they were heard while the AI thinks.
+            onPhrase: createChime(config.ffplay),
+            // The user talks over the AI: it goes quiet at once.
+            onBargeIn: () => say.cancel(),
+            log,
+        });
+        return ear.next();
+    },
+    stop: () => ear?.stop(),
+    interrupt: () => ear?.interrupt(),
+    // Returns right away (or, with wait, when playback ends) so the sentence plays while the AI goes on. The
+    // microphone stays open; the ear knows what is being said to discard its echo until playback ends.
+    speak: async (text, language, wait) => {
+        const done = ear?.saying(text);
+        const finished = say(text, language).finally(() => done?.());
+        if (wait)
+            return finished;
+    },
+});
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+import { type WhisperDevice } from './stt.js';
+export interface VoiceConfig {
+    model: string;
+    /** `dml` (the graphics card, the default on Windows) or `cpu`. */
+    device: WhisperDevice;
+    /**
+     * A 2-letter code (es, en…) to fix the language. Without it, Whisper detects the language of each sentence.
+     */
+    language?: string;
+    /** `piper` (default) for natural local voices, `system` for the operating system voice. */
+    tts: 'piper' | 'system';
+    /** A fixed voice from the Piper catalog, e.g. es_ES-davefx-medium. */
+    voice?: string;
+    ffplay: string;
+    /** On Windows, without it the first microphone ffmpeg lists is used. */
+    mic?: string;
+    ffmpeg: string;
+    cacheDir: string;
+    dataDir: string;
+    /** Logs what happens to each sentence in ~/.sanoriva-agent/voice.log. */
+    verbose: boolean;
+    /** Only prepares: checks ffmpeg, ffplay and the microphone, downloads the models and exits. */
+    setup: boolean;
+}
+/**
+ * Parses the command line. Throws an Error with the reason when an argument is invalid.
+ *
+ * @example
+ * parseConfig(['--language', 'es', '--verbose']);
+ */
+export declare function parseConfig(args: string[]): VoiceConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwC,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAEpF,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,aAAa,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,GAAG,EAAE,OAAO,GAAG,QAAQ,CAAC;IACxB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;IACjB,+FAA+F;IAC/F,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CA0CvD"}

package/dist/config.js

@@ -0,0 +1,54 @@
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { DEFAULT_WHISPER_MODEL, defaultDevice } from './stt.js';
+/**
+ * Parses the command line. Throws an Error with the reason when an argument is invalid.
+ *
+ * @example
+ * parseConfig(['--language', 'es', '--verbose']);
+ */
+export function parseConfig(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            model: { type: 'string' },
+            device: { type: 'string' },
+            language: { type: 'string' },
+            mic: { type: 'string' },
+            ffmpeg: { type: 'string' },
+            ffplay: { type: 'string' },
+            tts: { type: 'string' },
+            voice: { type: 'string' },
+            verbose: { type: 'boolean' },
+            setup: { type: 'boolean' },
+        },
+    });
+    if (values.tts !== undefined && values.tts !== 'piper' && values.tts !== 'system') {
+        throw new Error(`Invalid voice: --tts ${values.tts} (use piper or system)`);
+    }
+    if (values.language !== undefined && !/^[a-z]{2}$/.test(values.language)) {
+        throw new Error(`Invalid language: ${values.language} (use 2 letters, e.g. --language es)`);
+    }
+    if (values.device !== undefined && values.device !== 'cpu' && values.device !== 'dml') {
+        throw new Error(`Invalid device: --device ${values.device} (use cpu or dml)`);
+    }
+    const ffmpeg = values.ffmpeg ?? 'ffmpeg';
+    const dataDir = join(homedir(), '.sanoriva-agent');
+    return {
+        model: values.model ?? DEFAULT_WHISPER_MODEL,
+        device: values.device ?? defaultDevice(),
+        ...(values.language ? { language: values.language } : {}),
+        ...(values.mic ? { mic: values.mic } : {}),
+        tts: values.tts ?? 'piper',
+        ...(values.voice ? { voice: values.voice } : {}),
+        ffmpeg,
+        // ffplay ships with ffmpeg, so it sits next to a given ffmpeg.
+        ffplay: values.ffplay ?? (values.ffmpeg ? join(dirname(ffmpeg), basename(ffmpeg).replace(/ffmpeg/i, 'ffplay')) : 'ffplay'),
+        cacheDir: join(dataDir, 'models'),
+        dataDir,
+        verbose: values.verbose ?? false,
+        setup: values.setup ?? false,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/download.d.ts

@@ -0,0 +1,18 @@
+export interface Expected {
+    sha256?: string;
+    md5?: string;
+    size?: number;
+}
+export type Fetch = (url: string) => Promise<{
+    ok: boolean;
+    status: number;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+/** Checks size and hashes. Throws an Error on mismatch. */
+export declare function verify(data: Buffer, expected: Expected, name: string): void;
+/**
+ * Downloads a file once and stores it at `dest`, only if it matches what is expected; otherwise nothing is
+ * left on disk. An existing file is not downloaded again.
+ */
+export declare function download(url: string, dest: string, expected: Expected, fetchImpl?: Fetch): Promise<string>;
+//# sourceMappingURL=download.d.ts.map

package/dist/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../src/download.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CAAE,CAAC,CAAC;AAEnH,2DAA2D;AAC3D,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAU3E;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,GAAE,KAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAWvH"}

package/dist/download.js

@@ -0,0 +1,37 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** Checks size and hashes. Throws an Error on mismatch. */
+export function verify(data, expected, name) {
+    if (expected.size !== undefined && data.length !== expected.size) {
+        throw new Error(`${name}: size ${data.length}, expected ${expected.size}`);
+    }
+    for (const algorithm of ['sha256', 'md5']) {
+        const want = expected[algorithm];
+        if (!want)
+            continue;
+        const got = createHash(algorithm).update(data).digest('hex');
+        if (got !== want)
+            throw new Error(`${name}: ${algorithm} hash mismatch (corrupted or altered download)`);
+    }
+}
+/**
+ * Downloads a file once and stores it at `dest`, only if it matches what is expected; otherwise nothing is
+ * left on disk. An existing file is not downloaded again.
+ */
+export async function download(url, dest, expected, fetchImpl = fetch) {
+    if (existsSync(dest))
+        return dest;
+    console.error(`Descargando ${url}…`);
+    const response = await fetchImpl(url);
+    if (!response.ok)
+        throw new Error(`No puedo descargar ${url} (HTTP ${response.status})`);
+    const data = Buffer.from(await response.arrayBuffer());
+    verify(data, expected, url);
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(`${dest}.part`, data);
+    await rename(`${dest}.part`, dest);
+    return dest;
+}
+//# sourceMappingURL=download.js.map

package/dist/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../src/download.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,2DAA2D;AAC3D,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,QAAkB,EAAE,IAAY;IACnE,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,IAAI,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,UAAU,IAAI,CAAC,MAAM,cAAc,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,KAAK,MAAM,SAAS,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAU,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7D,IAAI,GAAG,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,SAAS,gDAAgD,CAAC,CAAC;IAC3G,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAW,EAAE,IAAY,EAAE,QAAkB,EAAE,YAAmB,KAAK;IACpG,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,CAAC,KAAK,CAAC,eAAe,GAAG,GAAG,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,UAAU,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IACzF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IACvD,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC5B,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,SAAS,CAAC,GAAG,IAAI,OAAO,EAAE,IAAI,CAAC,CAAC;IACtC,MAAM,MAAM,CAAC,GAAG,IAAI,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC"}