dsh-voice-kit

Readme

# dsh-voice-kit 🎙️

Voice input and read-aloud for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) web GUI.

[中文说明](README.zh.md)

> **Status: v0.4.0, published on npm** — `pnpm typecheck` passes, 239 unit
> tests pass, `pnpm build` emits the ecosystem-standard closure-factory bundle
> (host half + browser half). Verified inside a real DSH Desktop profile.
> Install: `dsh plugin add dsh-voice-kit`.

## Features

- 🎤 **Voice input** — mic button in the composer's left rail; records and
  transcribes **host-side**, appending the text to the draft (never clobbering
  what you already typed). Two backends: the browser **Web Speech API**
  (Chrome/Edge) or a **host-side OpenAI-compatible service** (e.g. SiliconFlow
  SenseVoice). `Esc` cancels; stop anytime.
- 🔊 **Read aloud (three engines)** — a per-message button at each assistant
  message tail:
  - **Microsoft neural voices** (free; 晓晓/云希/云健/云扬…), synthesized
    host-side via `msedge-tts` and cached; connects through the system proxy
    tunnel automatically on censored networks.
  - **Cloud neural voices** (SiliconFlow CosyVoice2 and any OpenAI-compatible
    `audio/speech`; direct from mainland China, no proxy needed) — reuses the
    same credential you already set up for speech recognition.
  - **System voices** — fully offline fallback; works everywhere.
  - Markdown and emoji are stripped before speaking; long replies are
    **streamed in sentence-boundary chunks** — the first chunk speaks within
    ~1s and later chunks download while it plays; only one voice at a time;
    the playing message is scrolled into view with an on-screen bubble showing
    what is being read; click again to stop instantly.
- ⚙️ **Settings** — a first-level section: voice engine (three choices), one-tap
  cloud preset, voice, rate, pitch, recognition language, an engine
  reachability probe (see at a glance whether Edge is reachable), and key status
  (shows only "saved / not set", never the value).

## Quick Start (5 minutes)

### 1. Install

```bash
# from npm (recommended)
dsh plugin add dsh-voice-kit

# or from a local checkout
dsh plugin --profile desktop add link:/path/to/dsh-voice-kit
```

Restart DSH Desktop and refresh the web GUI.

### 2. Hear read-aloud (pick an engine)

Open **Settings → Voice → Read aloud**:

- **Works instantly** — "**System voice**" → press 🔊 and you hear audio
  (offline; dated quality).
- **Free and natural** — "**Microsoft neural**". The page shows
  "❌ Edge unreachable / ✅ Edge reachable". If unreachable, turn on your
  proxy (the plugin routes through the system proxy automatically) and press 🔊.
- **No proxy, close to Doubao quality** — "**Cloud neural**" → tap the
  "**SiliconFlow CosyVoice2**" preset → if you already configured a speech
  recognition key, just press "**Play test**"; otherwise enter the key once
  (TTS reuses the same one).

> 💡 Cloud TTS and recognition share **one credential**: configure voice input
> first and read-aloud needs nothing more.

### 3. Speak with voice input

Open the 🎤 in the composer:
- If it says "configure a recognition service", go to **Settings → Voice →
  Voice input**, choose "host-side transcription", and enter the SiliconFlow
  base URL + key.
- Press 🎤 to talk, press again (or `Esc`) to stop; the transcript is
  **appended** to the draft.
- Use "**Microphone self-check**" first to confirm permission / device / format.

### 4. Troubleshooting

| Problem | Fix |
|---|---|
| No audio | Check the engine is reachable; Microsoft needs a proxy, cloud needs a key, system always works |
| Long text starts slowly | Optimized to ~1s to first audio; update to 0.4.0 if slower |
| Key shows "saved" but no effect | Key lives host-side; restart and press "Play test" again |
| No transcript on voice input | Confirm host-side recognition is configured |

## Install

```bash
# from npm (after publish)
dsh plugin add dsh-voice-kit

# or from a local checkout (development)
dsh plugin --profile desktop add link:/path/to/dsh-voice-kit
```

Restart the harness, refresh the web GUI.

## Development

```bash
pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest (markdown stripping / chunking / concurrent prefetch)
pnpm build       # tsdown → lib/index.js (host) + lib/client.js (browser)
```

Build pipeline is the ecosystem-standard closure-factory bundle
(`window.__ModuleLoader__.load`) driven by `shared/tsdown.client.ts`
(adapted from the official DeepSeek Harness `packages/client/tsdown.client.ts`,
MIT; `libExternal` option from the dsh-web-ui family bucket, Apache-2.0).

## License

MIT. The bundled `shared/tsdown.client.ts` adapts official DSH build tooling
(MIT) plus the dsh-web-ui `libExternal` option (Apache-2.0); see the file header.