voice # voice Talk to Pi hands-free in its terminal through a separately installed `speak_to_me` speech service. ## Use in Pi Run `/voice` to inspect the speech service, review setup, and start a call. Use a Nerd Font for widget icons. Audio devices belong to the speech-service host; remote SSH microphone transport is not provided. - `/voice setup`: prepare approved native-owned assets without starting a call. - `/voice history`: browse generated replies and playback/interruption markers. - `/voice mute` / `unmute`: suspend/resume recognition while keeping the service warm. - `/voice stop`: end Voice, not Pi's work. - `/voice resume`: retry an unavailable call or unmute an active one. - `/voice help`: list controls. Start, setup and history accept `--root ABSOLUTE_PATH` for Voice data/history; quote paths containing spaces. This does not select the native service's asset directory. Ctrl+Alt+V toggles Voice and cancels pending setup; Ctrl+Alt+B toggles mute. Configure these through `voice.toggleShortcut` / `voice.muteShortcut`; an empty string disables a binding. Shortcut changes require `/reload` and ignore project settings. Alt+PageUp/PageDown scrolls spoken captions; Alt+Shift+PageUp/PageDown scrolls recognized text. History uses `[`/`]` for pages, j/k or arrows to scroll, g/G for ends, and q/Escape to close. Recognition goes to the Voice conversation, never the editor. Spoken requests use Pi's normal execution policy and can dispatch real work. Expect about two seconds of detected silence before submission, plus recognition/classification latency. Preview text is provisional and never dispatches actions. Interrupting speech stops Voice output; explicitly request cancellation to stop Pi's work. Pi questions still require the ordinary UI. Session changes and reload end the call; conversation history is retained per Pi session. ## Setup and availability Install `speak_to_me` separately and make its executable available to Pi. Voice defaults to `["speak_to_me"]`, launches it directly without a shell, and uses its JSON-RPC stdio interface. It appends `serve` unless the argument vector already contains that subcommand; include `serve` before native fixture arguments when selecting explicit test I/O. For a custom executable, set the argument vector in your existing Pi settings: ```json { "voice.command": ["/absolute/path/to/speak_to_me"], "voice.preview": true } ``` `PI_VOICE_COMMAND` takes the same array encoded as JSON. An optional `voice.profile` selects a native catalog profile; otherwise Voice selects the sole suitable profile or asks. Profiles must support duplex recognition/synthesis, AEC and cues; preview additionally requires preview support. `voice.preview: false` disables provisional transcription. Native profiles choose engines, models, threads and storage; Voice does not configure or bundle them. Setup shows native-provided sizes, destinations, sources, checksums and licenses before any installation. Tab expands details; y confirms the displayed approval, n/Escape cancels. Missing executables, unavailable profiles and blocked plans fail explicitly. Voice neither builds native code nor downloads models itself. The package ships the thin client, not a native executable, model weights or audio-build sources. No automatic fake or alternate speech backend is used. Native-platform, device and model compatibility depend on the separately installed service and require their own verification. ## History and privacy Voice has bounded working context and read-only recall of archived conversation and settled work. History distinguishes generated text from certified consumed playback, not physical audibility or exact word timing. Idle progress commentary reports meaningful task changes, not tool activity; unavailable or repeated summaries stay silent. Voice saves conversation text, not raw microphone recordings. The conversational model provider may be remote. The native service owns microphone access, inference, asset storage and any explicitly selected audio test recordings. OS memory exhaustion can still kill either process. Default Voice data locations: - Linux/Termux: `${XDG_DATA_HOME:-~/.local/share}/pi/voice`. - macOS: `~/Library/Application Support/pi/voice`. - Windows: `%LOCALAPPDATA%\pi\voice`. ## Verification [Voice verification](TESTING.md) distinguishes fake-backed client checks, native fixture calls and physical acceptance. Fake integration results do not establish STT/TTS quality, AEC, device compatibility or real-time performance. ## Licenses Voice identifies four [UI SFX cues](https://github.com/romainsimon/uisfx/blob/07d65415cb3dc8f94fd6177ca4699ba7dc496f24/LICENSE-AUDIO) by recording digest. The recordings are CC0; availability and approved provisioning belong to the native service. Native runtime/model licenses appear in its setup plan, not a fixed Voice engine list. [Installation](../../README.md#install) ## Reference ### Commands | Command | Purpose | | --- | --- | | `/voice` | Start Voice through speech service or manage setup, history and call controls | ### Setting names | Setting | Environment | | --- | --- | | `voice.classifierModel` | `PI_VOICE_CLASSIFIER_MODEL` | | `voice.command` | `PI_VOICE_COMMAND` | | `voice.maxSentences` | `PI_VOICE_MAX_SENTENCES` | | `voice.maxSpeechSeconds` | `PI_VOICE_MAX_SPEECH_SECONDS` | | `voice.model` | `PI_VOICE_MODEL` | | `voice.muteShortcut` | `PI_VOICE_MUTE_SHORTCUT` | | `voice.preview` | `PI_VOICE_PREVIEW` | | `voice.profile` | `PI_VOICE_PROFILE` | | `voice.toggleShortcut` | `PI_VOICE_TOGGLE_SHORTCUT` | #### Setting values | Setting | Default | Valid values | Purpose | | --- | --- | --- | --- | | `voice.classifierModel` | `"auto"` | Parser-validated | Classifier model: Use auto or an authenticated provider/model identifier. | | `voice.command` | `["speak_to_me"]` | Parser-validated | Speech service command: Executable and arguments for the external speech service. | | `voice.maxSentences` | `6` | Integer 1–20 | Reply sentence limit: Maximum sentences per spoken reply. | | `voice.maxSpeechSeconds` | `40` | Integer 1–120 | Reply duration limit: Maximum seconds of generated speech per reply. | | `voice.model` | `"auto"` | Parser-validated | Conversation model: Use auto or an authenticated provider/model identifier. | | `voice.muteShortcut` | `"ctrl+alt+b"` | Parser-validated | Voice mute shortcut: Key combination for toggling native voice mute; empty disables it. | | `voice.preview` | `true` | Parser-validated | Live transcription preview: Show provisional transcription while the speech service recognizes input. | | `voice.profile` | Unset | Parser-validated | Speech service profile: Optional opaque profile ID supplied by the speech service. | | `voice.toggleShortcut` | `"ctrl+alt+v"` | Parser-validated | Voice start/stop shortcut: Key combination for starting or stopping native voice; empty disables it. |