dsh-live-voice 0.2.2 → 0.3.0

package/PLAN.md

@@ -186,6 +186,34 @@ Pausing playback need not stop text generation. If the user introduces a new req
 
 For spoken streaming, collect suitable text segments, synthesize them, and play them in order. Cancellation must invalidate pending work so delayed results from an old response cannot start playing later. Sentence boundaries, latency, buffering limits, and error recovery need evaluation.
 
+### Dual-audio meeting transcription (planned)
+
+Add an opt-in meeting mode with two independent audio-input pipelines. The primary pipeline remains the user’s normal microphone and labels finalized transcription with **“Me:”**. A secondary pipeline captures meeting participants from a user-selected shared-screen/system-audio stream, rather than assuming a second physical microphone, and labels finalized transcription with **“Them:”**. Each pipeline needs independent capture permission, meter/waveform, recognition work, segmentation, pending/error state, and cancellation; it must be possible to run either one alone or both together.
+
+Meeting mode appends final segments from both pipelines to the current composer in arrival order, preserving the speaker labels so the editable draft becomes a live meeting transcript: “Me: …”, “Them: …”, and so on. It must not use voice commands or automatically send messages. The user remains free to edit the composer and manually submit any selected portion as a question to the agent, retaining the preceding live transcript as context for code reviews or other meeting discussion.
+
+The design must account for browser screen/system-audio capture support, permission and device-selection UX, concurrent transcription ordering, overlap/echo between microphone and shared audio, and cleanup when either capture ends. It must never imply that system-audio capture is universally supported or silently capture meeting audio.
+
+#### Expected structural change
+
+This is a substantial input-flow refactor, not a complete plugin rewrite. The current session coordinator owns one microphone meter, one recognition instance, and one incremental composer transcript. Refactor it so the coordinator continues to own the conversation, composer integration, and shared policies, while reusable input pipelines own capture, meter/waveform, recognition, segmentation, pending work, errors, cancellation, and final-segment delivery.
+
+The target shape is one VoiceCoordinator with an independent primary microphone pipeline and an optional shared-system-audio pipeline. The existing microphone adapter must accept an externally supplied MediaStream as well as getUserMedia(), because system audio originates through explicit getDisplayMedia() sharing. Composer delivery must serialize concurrent final segments and use an explicit ordering policy, likely segment-end time plus a small buffer, because recognition completion order can differ from speaking order.
+
+The shared-audio pipeline must remain policy-isolated: it does not execute voice commands, trigger automatic delivery, or participate in microphone/TTS interruption as though meeting participants were the user. Initial implementation need not change the TTS queue; the meeting transcript stays manually editable and manually submitted. The planned backend-owned automatic-speech queue is complementary and will later make cross-chat output state independent from mounted frontend sessions.
+
+### Settings changes should not restart voice (planned bug fix)
+
+Changing a Live Voice preference currently stops active voice resources and makes the plugin behave as if it were restarting, even for values that can be applied live. Settings updates must be classified by effect: presentation and policy values should update immediately without interrupting capture, playback, queued speech, or the current conversation; engine, device, and other resource-boundary changes may require a targeted replacement only when necessary. The interface must state when a particular change will take effect on the next operation rather than silently resetting the whole plugin.
+
+### Backend-owned automatic speech queue (planned)
+
+The browser currently observes visible chat nodes and decides which assistant text enters its automatic-speech queue. This makes queue state dependent on the focused conversation and mounted frontend: switching chats can discard or duplicate state, and opening an older conversation can incorrectly announce historical assistant messages as if they were new.
+
+Move automatic-speech admission, streaming-segment tracking, ordering, cancellation, and queue state to the DSH host. The host must retain per-chat/turn provenance and a durable high-water mark for consumed assistant text, then dispatch synthesized audio or playback work to the appropriate connected browser client. A client must be able to receive an announcement for a non-focused chat with clear contextual phrasing, for example identifying the chat before its message.
+
+When several chats produce assistant output, the host must serialize announcements according to an explicit cross-chat policy: finish the active announcement, group pending segments by chat where appropriate, and announce one chat at a time rather than interleaving unrelated messages. The design must define how multiple browser clients are selected, how inactive clients are handled, and whether one client owns playback at a time. It must preserve correct queue state across navigation, avoid creating new work from historical chat content when an old chat is opened, and invalidate queued/in-flight speech on cancellation or an obsolete turn.
+
 ### Engine selection and interface
 
 Provide one place to select microphone, output device, conversation mode, STT engine, TTS engine, and shortcuts. Keep provider-specific complexity behind clear options without hiding important costs, permissions, or data transmission.

package/README.md

@@ -1,137 +1,92 @@
 # DSH Live Voice
 
 [![npm version](https://img.shields.io/npm/v/dsh-live-voice?logo=npm&label=npm&color=brightgreen)](https://www.npmjs.com/package/dsh-live-voice)
-[![dsh.pub registry status](https://dsh.pub/api/badges/victorwads/dsh-live-voice.svg)](https://dsh.pub/en/plugins/dsh-live-voice/)
-[![license](https://img.shields.io/badge/license-GPL--3.0--only-blue)](LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-v0.1.6--alpha.2-5c5cff?logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness/releases/tag/v0.1.6-alpha.2)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 
-**A local-first, hands-free voice assistant plugin for DeepSeek Harness (DSH). Speak, listen, answer prompts, and keep working without touching the computer.**
+**A local-first, hands-free voice assistant plugin for DeepSeek Harness (DSH).**
+*Built in Brazil 🇧🇷 and tested daily with Brazilian Portuguese on macOS.*
 
-Looking for a DeepSeek Harness voice plugin, DSH microphone plugin, speech-to-text, text-to-speech, or hands-free AI assistant? DSH Live Voice brings those capabilities together in one coordinated plugin.
+Speak, listen, answer prompts, and code without touching your keyboard. DSH Live Voice coordinates speech-to-text (STT) and text-to-speech (TTS) into a single, conflict-free conversational flow.
 
-It coordinates the microphone, composer, assistant messages, structured questions, and speech output without letting listening and speaking compete. Once voice conversation mode is running, DSH can narrate responses and questions, capture your spoken answers, and continue the conversation while your hands stay free.
+---
 
-[![DSH tested](https://img.shields.io/badge/DSH%20tested-0.1.6--alpha.2-5c5cff?logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness/releases/tag/v0.1.6-alpha.2)
+## ⚡ Quick Start
 
-## Built for daily use, maintained with you
+Install with `npx dsh` into your DSH web profile:
 
-I use DSH Live Voice for at least eight hours a day. For me, it is the best voice plugin for DSH — and I am committed to making it better through real, everyday use.
+```sh
+npx dsh plugin add --profile web dsh-live-voice
+```
 
-Have a bug to report, a feature you need, or a pull request to share? [Open an issue](https://github.com/victorwads/dsh-live-voice/issues) or [send a PR](https://github.com/victorwads/dsh-live-voice/pulls). I aim to respond quickly, review contributions promptly, and turn useful suggestions into features. Not every request will be implemented, but I welcome the conversation and will consider what you bring.
+Open **DSH Settings → Live Voice** after your next DSH startup.
 
-## Install
+---
 
-Install the public repository through dsh.pub into your DSH web profile:
+## 🌍 Interface Languages
 
-```sh
-npx dshpub add victorwads/dsh-live-voice --profile web
-```
+DSH Live Voice’s plugin interface is translated into the following languages. This refers to the visible plugin UI—not speech-recognition or text-to-speech language support.
 
-The installer resolves the public repository to an exact commit before adding the bundle. Open **DSH Settings → Live Voice** after the next normal DSH startup.
-
-## Why this project exists and Acknowledgments
-
-Listening and speaking should work together, so you can interrupt and be heard without the assistant’s voice getting in the way. [Read the story behind the project](HISTORY.md).
-
-A heartfelt thank you to [GooDAnDReaDY](https://github.com/GooDAnDReaDY) for [dsh-voice](https://github.com/GooDAnDReaDY/dsh-voice) and [Alan2Z](https://github.com/Alan2Z) for [dsh-speak](https://github.com/Alan2Z/dsh-speak). Your projects solved my voice needs in DSH for a while, and I am grateful for the work you shared. Eventually, I reached a point where I needed one codebase to coordinate both listening and speaking. [Read the full story](HISTORY.md).
-
-## Features
-
-|     | Capability                                                                                                                |
-| --- | ------------------------------------------------------------------------------------------------------------------------- |
-| 🎙️  | Voice typing directly into the DSH composer                                                                               |
-| 👐  | Hands-free conversations: speak, hear responses, and continue without touching the computer                               |
-| ❓  | Spoken DSH structured questions with automatic capture and submission of your answer                                      |
-| 💬  | Continuous voice conversations that stay active while you navigate between chats                                          |
-| 🗣️  | Configurable voice commands for sending, queueing, clearing, muting, resuming, stopping speech, and ending a conversation |
-| ⌨️  | Optional hold-Control push-to-talk anywhere on the page while a composer is open                                          |
-| 🧠  | Browser SpeechRecognition, local loopback whisper.cpp, or Qwen3-ASR on Apple MLX                                          |
-| 🔊  | Browser speech synthesis, native macOS `say`, or Qwen3-TTS on Apple MLX                                                   |
-| ⏱️  | Manual or automatic sending after configurable silence                                                                    |
-| 🫁  | Stable-silence delay prevents breathing pauses from starting assistant speech                                             |
-| 🎧  | Open-microphone mode for headphones                                                                                       |
-| 🔒  | Gated microphone mode for speakers                                                                                        |
-| ✋  | Pause, resume, stop, and manual interruption controls                                                                     |
-| 🔈  | Play individual assistant messages on demand                                                                              |
-| 🏠  | Whisper audio reaches the local server only through the authenticated DSH host                                            |
-
-## Hands-free experience
-
-Start voice conversation mode and choose an automatic delivery mode to keep a conversation moving without returning to the keyboard. DSH Live Voice can:
-
-1. Listen for your next message and deliver it after the configured silence period.
-2. Read assistant responses aloud as they arrive.
-3. Narrate DSH structured questions, listen for your next spoken response, and submit it as a custom answer.
-4. Keep voice conversation mode active when you move between chats until you explicitly end it.
-5. Accept configurable spoken commands for common conversation controls.
-6. Start temporary push-to-talk from anywhere on the page by holding Control, even when the voice bar is off; release to finish queued transcription and automatic delivery, or press Escape to cancel.
-
-The hands-free experience coordinates speech input and output locally when you select local engines. The DSH language model itself may still be remote.
-
-## Conversation flow
-
-The assistant never starts automatic playback while you are speaking. If a response is already waiting — including another assistant message — it waits until you finish and the configured continuous-silence delay has passed.
-
-### Speakers — gated listening (default)
-
-Listening and playback take turns so the assistant does not hear its own voice.
-
-```mermaid
-sequenceDiagram
-    participant Interface
-    actor Você
-    actor Assistente
-
-    Note over Interface,Assistente: Aguardando você falar…
-    activate Você
-    Você->>Assistente: Começa a falar
-    Assistente-->>Você: Escuta enquanto você fala
-    Note over Interface,Assistente: Você parou de falar
-    opt Envio manual
-        Você->>Interface: Revisa a mensagem reconhecida
-        Interface-->>Você: Envia quando estiver pronto
-    end
-    opt Envio automático
-        Note over Você,Assistente: Envia após a contagem de silêncio
-    end
-    deactivate Você
-    Você->>Assistente: Entrega sua mensagem
-    Assistente-->>Você: Resposta pronta — aguarda silêncio contínuo
-    Assistente-->>Você: Para de escutar
-    activate Assistente
-    Assistente->>Você: Fala a resposta em voz alta
-    deactivate Assistente
-    Note over Interface,Assistente: Escutando novamente — aguardando você falar…
-```
+- 🇺🇸 **English**
+- 🇧🇷 **Portuguese (Brazil)**
+- 🇪🇸 **Spanish**
+- 🇫🇷 **French**
+- 🇮🇳 **Hindi**
+- 🇨🇳 **Chinese**
+
+---
+
+## 📚 Documentation
+
+Detailed guides for deep-diving into engines and configurations:
+
+- ⚙️ **[Configuration & Conversation Flow Guide](docs/CONFIGURATION.md)** — Settings overview, speaker vs. headphone modes, sequence diagrams, silence delays, and external engine setup.
+- 🧠 **[Choosing a Speech Recognition Engine](docs/CHOOSING-AN-ENGINE.md)** — Comparison between Browser STT, Qwen3 ASR, and Whisper, with RAM footprints and OS compatibility.
+- 📖 **[The Story Behind the Project](HISTORY.md)** — Why this project was built and the human story behind coordinating voice.
+
+---
+
+## 🎯 Which Speech Engine Should I Use?
+
+| Scenario | Recommendation | RAM | Why |
+| --- | --- | --- | --- |
+| 🇧🇷 **Portuguese on macOS** | **Qwen3 ASR (HTTP API)** | ~3 GB | Best accuracy in daily maintainer use. Whisper is second choice. |
+| 🇺🇸 **English on macOS** | **Browser SpeechRecognition** | ~0 GB | Built-in macOS/browser API. Fast, zero extra RAM. |
+| 🪟 **Windows** | **Qwen3 ASR** or **Whisper HTTP** | ~2–3 GB | Recommended starting point; Windows browser STT varies. |
+| 🌐 **Multilingual / Other** | **Whisper HTTP (auto)** | ~2 GB | Automatic language detection across dozens of languages. |
 
-### Headphones — open microphone
+👉 *For model requirements and server setup, see [Choosing a Speech Engine](docs/CHOOSING-AN-ENGINE.md).*
 
-The microphone remains open during playback, allowing your voice to pause the assistant.
+---
 
-### Other conversation settings
+## ✨ Features at a Glance
 
-- **Sending mode:** review and send manually by default, or send automatically after a configurable silence countdown.
-- **Assistant response delay:** choose how long you must remain silent before automatic playback starts; speaking again restarts the wait.
-- **Automatic assistant speech:** turn automatic playback of new assistant messages on or off.
-- **Sent-message interruption:** sending another message does not stop current audio by default, but you can enable that behavior.
-- **Manual playback:** play any individual assistant message on demand without waiting for the automatic-playback delay.
+- 🎙️ **Voice Typing:** Speak directly into the DSH composer with live interim transcription.
+- 👐 **Hands-Free Conversation:** Continuous dialogue that stays active across chat sessions.
+- ❓ **Spoken Structured Questions:** Narrates DSH prompt questions and submits your spoken answer.
+- ⌨️ **Hold-to-Talk (Push-to-Talk):** Hold `Control` anywhere on the page to speak; release to send.
+- 🎧 **Acoustic Mode Isolation:** Gated listening for speakers (no echo) and open-mic interruption for headphones.
+- 🗣️ **Spoken Commands:** Control the chat using phrases like *"send"*, *"mute"*, *"clear"*, and *"stop speaking"*.
+- 🧹 **Smart Code Filtering:** Automatically skips or summarizes large code blocks instead of reading syntax out loud.
+- 🏠 **Local-First & Private:** Audio runs locally on your machine (via Browser APIs, Apple MLX, or whisper.cpp); no external voice telemetry.
+- 🌐 **Remote-Ready Host Audio:** Qwen and macOS Say synthesize on the DSH host, then DSH delivers compact audio to your browser—so playback works over remote and LAN connections.
 
-## Local-first architecture
+### 🧑‍💻 Coming Soon: Meeting Mode
 
-- **Recognition:** Browser SpeechRecognition, loopback whisper.cpp HTTP, or Qwen3-ASR through a host-local Apple MLX server.
-- **Speech output:** browser/device audio, native macOS `say`, or host-local Qwen3-TTS with WAV playback in the browser.
-- **Whisper transport:** complete WAV utterances through authenticated same-origin DSH routes.
-- **Privacy:** raw audio and transcripts are not logged by default.
+**Meeting Mode** is a planned differentiator for collaborative coding conversations. It will keep two independent live transcription streams in the DSH composer: your microphone as **“Me:”**, and meeting participants from an explicitly shared screen/system-audio stream as **“Them:”**. This creates an editable, real-time record of a code review or technical discussion, so you can manually ask DSH a question with the meeting context already in the composer.
 
-Speech processing can run locally, but the DSH language model may still be remote.
+It will never automatically send the transcript or use meeting audio for voice commands. Sharing system audio will always require explicit browser permission and depends on browser and operating-system support.
 
-## Qwen3 HTTP engine
+---
 
-When a compatible Qwen3 speech API is already running on the DSH host, choose **Qwen3 ASR — local MLX server** under Speech recognition and **Qwen3 TTS — local MLX server** under Speech output. Configure its base URL in **DSH Settings → Live Voice**. The Qwen server may use any HTTP or HTTPS base URL reachable from the DSH host. The plugin supports the OminiX-API contract and standard OpenAI-style speech endpoints at `GET /health`, `POST /v1/audio/transcriptions`, and `POST /v1/audio/speech`; it does not install, start, stop, or manage that external service or its model weights.
+## 🤝 Acknowledgments & Community
 
-## License
+Listening and speaking should work together. A heartfelt thank you to [GooDAnDReaDY](https://github.com/GooDAnDReaDY) for [dsh-voice](https://github.com/GooDAnDReaDY/dsh-voice) and [Alan2Z](https://github.com/Alan2Z) for [dsh-speak](https://github.com/Alan2Z/dsh-speak), which inspired this unified coordinator. [Read the full story](HISTORY.md).
 
-[GPL-3.0-only](LICENSE). Commercial use and redistribution are allowed subject to the GPL. Third-party speech engines and models may have separate licenses.
+I use DSH Live Voice for at least 8 hours every day. Feedback, ideas, and contributions are welcome:
+- [Open an Issue](https://github.com/victorwads/dsh-live-voice/issues)
+- [Send a Pull Request](https://github.com/victorwads/dsh-live-voice/pulls)
 
-## Keywords
+---
 
-`dsh`, `dsh-plugin`, `deepseek-harness`, `local-first`, `local-voice`, `hands-free`, `hands-free-ai`, `hands-free-assistant`, `voice-control`, `voice-commands`, `voice-assistant`, `voice-conversation`, `conversational-ai`, `continuous-conversation`, `voice-dictation`, `spoken-prompts`, `speech-to-text`, `text-to-speech`, `speech-recognition`, `speech-synthesis`, `stt`, `tts`, `whisper`, `whisper-cpp`, `qwen3-asr`, `qwen3-tts`, `mlx`, `apple-silicon`, `web-speech-api`, `macos-say`, `turn-taking`, `voice-interruption`, `silence-detection`
+### 📄 License [Apache-2.0](LICENSE)

package/docs/ARCHITECTURE.md

@@ -0,0 +1,40 @@
+# Architecture
+
+DSH Live Voice uses application composition roots, domain modules, and a domain-independent design system. There are no legacy client, core, or engine source trees.
+
+## Dependency direction
+
+1. `src/app` composes DSH services, slots, routes, modules, styles, and client language boundaries.
+2. `src/modules` owns product behavior, feature UI, policies, engines, provider hosts, services, and models.
+3. `src/shared` owns reusable domain-independent React primitives.
+4. App code may import modules and shared code. Modules may import shared code. Shared code never imports modules.
+5. Feature modules use the intentionally centralized client i18n API, but never register DSH slots or host routes.
+6. Browser and host dependency graphs remain separate. Host-only Node imports must never enter the client bundle.
+
+## Composition roots
+
+- Client: `src/app/client/apply.tsx`.
+- Server: `src/app/server/apply.ts`.
+- Slot definitions and registration: `src/app/client/slotDefinitions.ts` and `registerSlots.tsx`.
+- Styles: `src/styles/index.ts`.
+
+## Internationalization
+
+The only client language tree is `src/app/client/i18n`. It owns typed catalogs, the React runtime, DSH catalog registration, and synchronization with `ctx.locale`. Every DSH slot component is wrapped by the application language boundary. UI locale, recognition language, synthesis language, and user-defined command phrases are independent values.
+
+## Modules
+
+- `modules/core`: shared voice-domain coordination, settings normalization, ownership, transcript handling, microphone policy, filters, and shared Qwen configuration.
+- `modules/conversation`: composer/chat UI, conversation components, chat models, and session-facing behavior.
+- `modules/settings`: modular Settings shell, hooks, services, and Conversation/Recognition/Speech sections.
+- `modules/recognition/engines/{browser,qwen,whisper}`: recognition adapters and provider-specific host/UI code.
+- `modules/speak/engines/{browser,qwen,say,audio}`: speech adapters, host audio, transcoding, and provider clients.
+
+## Stable contracts
+
+- Preserve DSH slot names, IDs, order, and injected services.
+- Preserve authenticated same-origin API routes.
+- Preserve persisted key `dsh-live-voice.settings` and normalization.
+- Preserve pause, resume, cancel, ownership, interruption, and stale-result semantics.
+- Do not log raw audio or transcripts by default.
+- Treat lifecycle behavior in [VOICE-LIFECYCLE.md](VOICE-LIFECYCLE.md) as the natural-language behavioral contract.

package/docs/CHOOSING-AN-ENGINE.md

@@ -0,0 +1,120 @@
+# Choosing a Speech Recognition Engine
+
+DSH Live Voice brings hands-free voice conversations to DeepSeek Harness (DSH). Because speech recognition (STT) runs local-first, choosing the right engine depends on your **operating system**, **language**, and **available RAM**.
+
+This guide summarizes practical recommendations based on real-world daily use, observed resource footprints, and platform compatibility.
+
+---
+
+## Quick Recommendations
+
+| Language | Platform | Recommended Engine | RAM Footprint | Notes |
+| --- | --- | --- | --- | --- |
+| **Portuguese (Brazil)** | macOS | **Qwen3 ASR (HTTP API)** | ~3 GB | **Best accuracy.** Maintainer's daily driver. Whisper is second choice. |
+| **English (US)** | macOS | **Browser SpeechRecognition** | ~0 GB | Built-in macOS/browser API. Fast and lightweight. |
+| **English / Portuguese** | Windows | **Qwen3 ASR** or **Whisper HTTP** | ~2–3 GB | Recommended starting point. Windows browser STT is inconsistent. |
+| **Chinese (Mandarin)** | Any | **Qwen3 ASR** or **Whisper HTTP** | ~2–3 GB | Strong multilingual support in underlying models. |
+| **Multilingual / Other** | Any | **Whisper HTTP (auto)** | ~2 GB | Automatic language detection (`auto`). |
+
+---
+
+## Engine Breakdown
+
+### 1. Browser SpeechRecognition (Web Speech API)
+*Default option in DSH Live Voice settings.*
+
+- **How it works:** Uses the browser's native `SpeechRecognition` interface. On macOS/Chrome/Safari, it can leverage system dictation and locally downloaded language packs.
+- **RAM usage:** Negligible (~0 GB extra), since it runs within the browser and operating system frameworks.
+- **Strengths:**
+  - Zero setup required: no local server or model weights to download.
+  - Extremely responsive and lightweight.
+  - Outstanding recognition for **English** on macOS.
+- **Trade-offs:**
+  - Availability and accuracy depend heavily on your browser vendor and operating system.
+  - When *Process recognition locally on this device* is checked, your browser must have the language pack installed (e.g. via browser settings or the auto-install prompt).
+  - Inconsistent across different platforms (especially Windows).
+
+### 2. Qwen3 ASR (HTTP API)
+*Local-first inference via host-local HTTP server (e.g. Apple MLX or OminiX-API).*
+
+- **How it works:** Transcribes bounded audio utterances by posting 16 kHz mono WAV to an OpenAI-compatible `/v1/audio/transcriptions` endpoint running on your machine.
+- **RAM usage:** ~3 GB RAM observed during typical local MLX inference.
+- **Strengths:**
+  - **Highest accuracy for Brazilian Portuguese** in real-world testing.
+  - Native support for Portuguese, English, and Chinese.
+  - Decoupled from browser quirks and system dictation bugs.
+- **Trade-offs:**
+  - Requires running a separate local HTTP process (e.g., via Python or MLX).
+  - Uses ~3 GB of memory.
+
+### 3. Whisper (HTTP API)
+*Local-first inference via whisper.cpp or compatible server.*
+
+- **How it works:** Posts complete audio chunks to a host-local loopback server (e.g., `http://127.0.0.1:8080/inference` or standard `/v1/audio/transcriptions`).
+- **RAM usage:** ~2 GB RAM observed in typical setups (e.g., `small` or quantized models).
+- **Strengths:**
+  - Strong, reliable multilingual recognition across dozens of languages.
+  - Supports **Automatic — detect language** (`auto`), switching seamlessly without manual reconfiguration.
+  - Highly optimized C/C++ runtimes via `whisper.cpp`.
+- **Trade-offs:**
+  - Requires running a separate local Whisper server.
+  - Transcription is chunk-based rather than real-time streaming.
+
+---
+
+## Platform & OS Guidance
+
+### macOS (Apple Silicon / Intel)
+macOS is the primary development and daily-testing platform for DSH Live Voice:
+- **For Brazilian Portuguese:** Run **Qwen3 ASR** on Apple MLX. It delivers the most natural transcription with punctuation and handles conversational Portuguese with high precision.
+- **For English:** Use **Browser SpeechRecognition**. It uses the native macOS speech synthesis and dictation stack, keeping your RAM free for local LLMs or developer tools.
+- **Whisper:** A great fallback if you prefer a single model for multiple languages.
+
+### Windows
+- **Browser SpeechRecognition:** Often poorly implemented or inconsistent across Chromium builds on Windows, sometimes requiring external cloud endpoints or failing capability checks.
+- **Recommendation:** Use **Qwen3 ASR** or **Whisper HTTP** running locally (e.g. via WSL, Docker, or native Windows binaries).
+- *Validation notice:* The maintainer primarily develops and tests on macOS. Windows users are encouraged to test and submit feedback.
+
+---
+
+## Resource & Memory Comparison
+
+| Metric | Browser SpeechRecognition | Whisper HTTP | Qwen3 ASR |
+| --- | --- | --- | --- |
+| **Additional Process** | None | Separate HTTP server | Separate HTTP server |
+| **Typical RAM Usage** | Minimal (~0 GB) | ~2 GB | ~3 GB |
+| **Setup Complexity** | Zero configuration | Moderate (run server binary) | Moderate (run MLX/Python server) |
+| **Language Detection** | Specific locale only | Manual or `auto` | Manual locale mapping |
+| **Local Privacy** | Configurable (local pack or cloud) | 100% local loopback | 100% local loopback |
+
+---
+
+## Language Support Details
+
+1. **Portuguese (Brazil - `pt-BR`):**
+   - First-class citizen in DSH Live Voice.
+   - Mapped directly as `portuguese` for Qwen3 and `pt` for Whisper.
+2. **English (United States - `en-US`):**
+   - Full native support across all three engines.
+3. **Chinese:**
+   - Supported natively by Qwen3 and Whisper backends.
+4. **Other Languages:**
+   - Select **Whisper HTTP API** with language set to **Automatic — detect language** to speak in Spanish, French, German, Japanese, and more.
+
+---
+
+## Speech Output (TTS) Note
+
+Speech recognition (hearing you) and speech output (speaking back) are configured independently:
+- **Browser Speech:** Uses local system voices installed in your OS.
+- **macOS `say`:** Native host CLI synthesis. The host renders temporary WAV audio, transcodes it to compact AAC/M4A, removes temporary files, and the browser controls playback.
+- **Qwen3 TTS:** High-quality neural synthesis running on the DSH host via MLX; its internal WAV response receives the same AAC/M4A transport conversion.
+
+For both host engines, Live Voice preserves segment order and prepares at most three upcoming segments to reduce gaps. Stop, engine changes, and session teardown cancel or discard obsolete preparation. AAC in an M4A container is the shared browser transport; macOS `afconvert` provides the local conversion without a package dependency.
+
+---
+
+## Help Us Improve
+
+Have you tested DSH Live Voice on Windows, Linux, or in other languages?
+Please [open an issue](https://github.com/victorwads/dsh-live-voice/issues) or submit a pull request with your system specifications, engine configuration, and experience!

package/docs/CONFIGURATION.md

@@ -0,0 +1,149 @@
+# Configuring DSH Live Voice & Conversation Flow
+
+DSH Live Voice integrates directly into DeepSeek Harness settings under **DSH Settings → Live Voice**.
+
+This guide covers all conversation modes, acoustic settings, silence thresholds, audio device routing, voice commands, and external engine configurations.
+
+---
+
+## 1. Acoustic Modes & Turn-Taking
+
+How listening and speaking coordinate depends on whether you use speakers or headphones:
+
+### Speakers — Gated Listening (Default)
+When using speakers, microphone input is automatically gated while the assistant is speaking so the assistant never hears its own voice or transcribes its own output.
+
+```mermaid
+sequenceDiagram
+    participant Interface
+    actor You as User
+    actor Assistant
+
+    Note over Interface,Assistant: Waiting for you to speak…
+    activate You
+    You->>Assistant: Starts speaking
+    Assistant-->>You: Listens to speech
+    Note over Interface,Assistant: You pause / stop speaking
+    opt Manual Send
+        You->>Interface: Review transcribed draft
+        Interface-->>You: Send when ready
+    end
+    opt Automatic Send
+        Note over You,Assistant: Sends after silence countdown
+    end
+    deactivate You
+    You->>Assistant: Message delivered
+    Assistant-->>You: Response ready — waits for stable silence
+    Assistant-->>You: Pauses listening
+    activate Assistant
+    Assistant->>You: Speaks response aloud
+    deactivate Assistant
+    Note over Interface,Assistant: Listening resumed — ready for next turn
+```
+
+- **Interrupting on speakers:** Click **Take microphone** or use the push-to-talk shortcut to take your turn immediately and pause the assistant.
+
+### Headphones — Open Microphone
+With headphones, the microphone remains open during playback:
+- **Speech-detected pause:** When you begin speaking, the assistant automatically pauses.
+- **Debounced interruption:** Requires at least one recognized word to prevent accidental pauses from coughs or background noise.
+- **Explicit resumption:** Silence alone does not automatically resume obsolete playback.
+
+---
+
+## 2. Conversation Settings
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| **Sending Mode** | `Manual` | `Manual` (review before sending), `Automatic` (sends after silence countdown), or `Steer` (send directly to running agent). |
+| **Auto-Send Delay** | `4 seconds` | Silence countdown before automatically submitting your draft (configurable from 2 to 10 seconds). |
+| **Assistant Response Delay** | `3 seconds` | Continuous silence required after you stop speaking before the assistant begins automatic audio playback. |
+| **Automatic Assistant Speech** | `Enabled` | Automatically reads new assistant responses aloud as they stream in. |
+| **Stop Speech on Send** | `Disabled` | Immediately stops current assistant playback whenever you submit a new message. |
+| **Hold-to-Talk (Push-to-Talk)** | `Enabled` | Hold `Control` anywhere on the page to speak; release to transcribe and auto-send, or press `Escape` to cancel. |
+| **Hands-Free Structured Questions** | Automatic | Narrates DSH structured questions, captures your spoken response, and submits it as a custom answer. |
+
+---
+
+## 3. Speech Recognition (Input)
+
+Configure your microphone and speech-to-text (STT) engine:
+
+- **Recognition Engine:**
+  - **Browser SpeechRecognition:** Uses the browser/system dictation engine.
+  - **Qwen3 ASR — HTTP API:** Connects to a host-local Qwen3 model server.
+  - **Whisper — HTTP API:** Connects to a host-local whisper.cpp server.
+- **Input Device:** Explicitly select a microphone (USB mic, headset, or built-in).
+- **Recognition Language:** Choose **Português (Brasil)**, **English (United States)**, or **Automatic — detect language** (available on Qwen3 and Whisper).
+- **Local Processing:**
+  - *Process recognition locally on this device:* Ensures speech is not sent to external browser vendor cloud servers.
+  - *Automatically install language pack:* Allows the browser to download offline language packs on demand.
+- **Silence Detection (VAD) Profiles:**
+  - *Short (900 ms):* Fast turnaround for concise commands.
+  - *Natural (1500 ms - default):* Balanced for conversational cadence.
+  - *Long (2200 ms):* Accommodates thinking pauses during complex prompts.
+- **Maximum Utterance Limit:** Split continuous speech after 10 to 300 seconds (default: 60s) to keep transcription chunks manageable.
+
+---
+
+## 4. Speech Output (Speaking)
+
+Configure how assistant messages are read aloud:
+
+- **Speech Engine:**
+  - **Browser speech:** Plays audio through the browser device using local system voices.
+  - **macOS `say`:** Host-local synthesis to temporary WAV, converted to compact AAC/M4A for browser playback; temporary files are removed after conversion.
+  - **Qwen3 TTS:** Neural voice synthesis with WAV streaming playback in the browser.
+- **Output Device:** Route playback to specific speakers or headphones.
+- **Speech Rate:** Adjust reading speed from 0.1x to 3.0x (1.0 is normal).
+- **Code Block Filtering:**
+  - Automatically filter out lengthy Markdown code blocks so the assistant doesn't recite syntax line by line.
+  - Read code blocks up to a configured line count (e.g. 5 lines).
+  - Replace larger code blocks with a custom spoken notice (e.g. *"Look at the code in our conversation"*).
+
+---
+
+## 5. Spoken Voice Commands
+
+When voice commands are enabled, you can speak exact trigger phrases to control the conversation hands-free:
+
+| Action | Default Trigger Phrases |
+| --- | --- |
+| **Send Message** | `send`, `send message` |
+| **Queue Message** | `queue`, `queue message` |
+| **End Conversation** | `end`, `end conversation` |
+| **Mute Microphone** | `mute`, `stop listening` |
+| **Resume Microphone** | `resume`, `start listening` |
+| **Stop Speech** | `stop talking`, `stop speaking`, `shut up` |
+| **Clear Input** | `clear all`, `clear message` |
+
+*Phrases are configurable in Settings → Live Voice → Commands, supporting comma-separated alternatives.*
+
+---
+
+## 6. External Host Engine Setup
+
+### Qwen3 HTTP Service
+When using Qwen3 ASR or TTS:
+- Runs as an external local process (e.g. via Apple MLX, OminiX-API, or Python).
+- Configured via base URL (default: `http://127.0.0.1:8080/`).
+- Exposes standard OpenAI-compatible endpoints:
+  - `GET /health`
+  - `POST /v1/audio/transcriptions`
+  - `POST /v1/audio/speech`
+- Credentials and host settings are stored with owner-only permissions in `~/.dsh/dsh-live-voice-qwen.json`.
+
+### Whisper HTTP Service
+When using Whisper:
+- Connects to `whisper.cpp` server or compatible loopback HTTP daemon.
+- Configured via inference endpoint URL (default: `http://127.0.0.1:8080/inference`).
+- Audio is validated as bounded 16 kHz mono PCM16 WAV and passed strictly through authenticated same-origin DSH routes.
+- Configuration is stored with owner-only permissions in `~/.dsh/dsh-live-voice-whisper.json`.
+
+---
+
+## 7. Privacy & Local Architecture
+
+- **No Remote Telemetry:** Transcripts and raw microphone audio are never logged or phoned home.
+- **Strict Loopback:** External engine bridges only accept unauthenticated loopback addresses (`127.0.0.1`, `::1`, `localhost`), preventing external network leakage.
+- **Browser vs. Host:** Speech processing runs on your own hardware. Keep in mind that the DeepSeek Harness language model itself may be remote depending on your DSH setup.

package/docs/REVIEW.md

@@ -0,0 +1,35 @@
+# Architecture Review Guide
+
+## Authoritative boundaries
+
+- Client root: `src/app/client/apply.tsx`.
+- Server root: `src/app/server/apply.ts`.
+- Client i18n: `src/app/client/i18n`.
+- Conversation UI: `src/modules/conversation`.
+- Settings runtime: `src/modules/settings/components/LiveVoiceSettings.tsx`.
+- Recognition engines: `src/modules/recognition/engines`.
+- Speech engines: `src/modules/speak/engines`.
+- Shared UI primitives: `src/shared/design-system`.
+
+No compatibility implementation remains under `src/client`, `src/core`, or `src/engines`; those trees must not be recreated. Barrels expose implementations physically owned by their modules rather than forwarding to legacy trees.
+
+## Review rules
+
+1. App composes modules; modules may import shared code; shared code never imports modules.
+2. The centralized client i18n API is the sole intentional module-to-app dependency.
+3. Every registered slot is wrapped by the DSH language boundary.
+4. Provider adapters remain separate from conversation policy.
+5. Browser bundles contain no Node built-ins.
+6. Storage keys, routes, slot IDs, and established CSS classes remain stable.
+
+## High-risk manual checks
+
+- Start, stop, cancel, mute, and resume input.
+- Start a conversation, switch chats, and verify transient mute does not leak into a new session.
+- Test Speakers and Headphones turn-taking.
+- Test pause, resume, next segment, and stop-all playback.
+- Exercise queue and steer delivery, pending questions, devices, permissions, and provider settings.
+- Change DSH UI language without changing STT/TTS selections.
+- Test authenticated routes with real providers when available.
+
+The automated suite covers cancellation, stale results, engines, routes, normalization, locale completeness, lifecycle, slots, modular UI, and design-system contracts. Physical devices and the authenticated GUI still require manual verification.