# junarch/voice_for_dsh architecture

> Architecture diagram of the GitHub repository junarch/voice_for_dsh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/junarch/voice_for_dsh
- Repository: https://github.com/junarch/voice_for_dsh

## Overview

voice-for-dsh adds automatic or manual spoken playback to DSH conversations. The main path is a user action or completed assistant turn in the client, host-side transcript generation and speech cleanup, then audio synthesis and playback. The host also supports browser speech, Volcengine streaming, local Kokoro with downloadable models, and configurable chimes. The host excerpt and SOURCE INDEX establish several internal module relationships; broader feature links below are documented in the README, while unsampled implementation details are not inferred.

Main entry points: [`packages/voice-for-dsh/lib/index.js`](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js) (Host plugin), [`packages/voice-for-dsh/lib/model-installer.js`](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/model-installer.js) (Model installer), [`packages/voice-for-dsh/lib/client.js`](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/client.js) (Conversation client), [`packages/voice-for-dsh/lib/volcengine-ws.js`](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/volcengine-ws.js) (Volcengine TTS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation and controls"]
  node_client["Conversation client<br/>[client.js]"]
end

subgraph group_host["Speech orchestration"]
  node_host_api["Host plugin<br/>[index.js]"]
  node_transcription["LLM transcription<br/>[index.js]"]
  node_transcript_cache[("Transcript cache<br/>[index.js]")]
  node_speech_cleanup["Speech cleanup<br/>[speech-clean.js]"]
  node_audio_delivery["Audio delivery<br/>[index.js]"]
  node_chimes[("Local chimes<br/>[index.js]")]
end

subgraph group_engines["Speech engines"]
  node_browser_tts["Browser TTS<br/>[client.js]"]
  node_volcengine["Volcengine TTS<br/>[volcengine-ws.js]"]
  node_kokoro_runtime["Kokoro runtime<br/>[local-runtime.js]"]
  node_voice_compat["Voice compatibility<br/>[voice-compat.js]"]
end

subgraph group_local["Local model lifecycle"]
  node_runtime_pool["Runtime pool<br/>[runtime-pool.js]"]
  node_model_installer["Model installer<br/>[model-installer.js]"]
  node_model_manifest["Model manifest<br/>[model-manifest.js]"]
end

node_user(("DSH user"))
node_model_source(("Model download source"))
node_volcengine_service(("Volcengine service"))
node_llm_provider(("Configured LLM"))

node_user -->|"uses"| node_client
node_client -->|"requests speech"| node_host_api
node_host_api -->|"generates transcript"| node_transcription
node_transcription -->|"calls"| node_llm_provider
node_host_api -->|"caches transcripts"| node_transcript_cache
node_host_api -->|"cleans text"| node_speech_cleanup
node_host_api -->|"uses fallback"| node_browser_tts
node_host_api -->|"streams speech"| node_volcengine
node_volcengine -->|"sends audio requests"| node_volcengine_service
node_host_api -->|"synthesizes locally"| node_kokoro_runtime
node_host_api -->|"normalizes config"| node_voice_compat
node_host_api -->|"stores audio segments"| node_audio_delivery
node_audio_delivery -->|"serves audio"| node_client
node_client -->|"plays speech"| node_browser_tts
node_host_api -->|"stores sound assets"| node_chimes
node_host_api -->|"acquires runtime"| node_runtime_pool
node_host_api -->|"manages model"| node_model_installer
node_model_installer -->|"reads manifest"| node_model_manifest
node_model_installer -->|"prepares model"| node_kokoro_runtime
node_model_installer -->|"downloads model"| node_model_source

click node_client "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/client.js"
click node_host_api "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js"
click node_transcription "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js"
click node_transcript_cache "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js"
click node_speech_cleanup "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/speech-clean.js"
click node_audio_delivery "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js"
click node_browser_tts "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/client.js"
click node_volcengine "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/volcengine-ws.js"
click node_kokoro_runtime "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/local-runtime.js"
click node_voice_compat "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/voice-compat.js"
click node_runtime_pool "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/runtime-pool.js"
click node_model_installer "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/model-installer.js"
click node_model_manifest "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/model-manifest.js"
click node_chimes "https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_user toneBlue
class node_host_api,node_transcription,node_transcript_cache,node_speech_cleanup,node_audio_delivery,node_chimes toneAmber
class node_browser_tts,node_volcengine,node_kokoro_runtime,node_voice_compat toneMint
class node_runtime_pool,node_model_installer,node_model_manifest toneRose
class node_model_source,node_volcengine_service,node_llm_provider toneIndigo
```

## Components

### Conversation and controls

- [Conversation client](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/client.js): `packages/voice-for-dsh/lib/client.js`

### Speech orchestration

- [Host plugin](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js): `packages/voice-for-dsh/lib/index.js`
- [LLM transcription](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js): `packages/voice-for-dsh/lib/index.js`
- [Transcript cache](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js): `packages/voice-for-dsh/lib/index.js`
- [Speech cleanup](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/speech-clean.js): `packages/voice-for-dsh/lib/speech-clean.js`
- [Audio delivery](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js): `packages/voice-for-dsh/lib/index.js`
- [Local chimes](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/index.js): `packages/voice-for-dsh/lib/index.js`

### Speech engines

- [Browser TTS](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/client.js): `packages/voice-for-dsh/lib/client.js`
- [Volcengine TTS](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/volcengine-ws.js): `packages/voice-for-dsh/lib/volcengine-ws.js`
- [Kokoro runtime](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/local-runtime.js): `packages/voice-for-dsh/lib/local-runtime.js`
- [Voice compatibility](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/voice-compat.js): `packages/voice-for-dsh/lib/voice-compat.js`

### Local model lifecycle

- [Runtime pool](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/runtime-pool.js): `packages/voice-for-dsh/lib/runtime-pool.js`
- [Model installer](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/model-installer.js): `packages/voice-for-dsh/lib/model-installer.js`
- [Model manifest](https://github.com/junarch/voice_for_dsh/blob/main/packages/voice-for-dsh/lib/model-manifest.js): `packages/voice-for-dsh/lib/model-manifest.js`

### Other components

- **DSH user**
- **Model download source**
- **Volcengine service**
- **Configured LLM**

## Connections

- DSH user → Conversation client: uses (evidence: `README.md`)
- Conversation client → Host plugin: requests speech (evidence: `README.md`)
- Host plugin → LLM transcription: generates transcript (evidence: `README.md`)
- LLM transcription → Configured LLM: calls (evidence: `README.md`)
- Host plugin → Transcript cache: caches transcripts (evidence: `packages/voice-for-dsh/lib/index.js`)
- Host plugin → Speech cleanup: cleans text (evidence: `packages/voice-for-dsh/lib/index.js`)
- Host plugin → Browser TTS: uses fallback (evidence: `README.md`)
- Host plugin → Volcengine TTS: streams speech (evidence: `packages/voice-for-dsh/lib/index.js`)
- Volcengine TTS → Volcengine service: sends audio requests (evidence: `README.md`)
- Host plugin → Kokoro runtime: synthesizes locally (evidence: `packages/voice-for-dsh/lib/index.js`)
- Host plugin → Voice compatibility: normalizes config (evidence: `packages/voice-for-dsh/lib/index.js`)
- Host plugin → Audio delivery: stores audio segments (evidence: `packages/voice-for-dsh/lib/index.js`)
- Audio delivery → Conversation client: serves audio (evidence: `README.md`)
- Conversation client → Browser TTS: plays speech (evidence: `README.md`)
- Host plugin → Local chimes: stores sound assets (evidence: `packages/voice-for-dsh/lib/index.js`)
- Host plugin → Runtime pool: acquires runtime (evidence: `packages/voice-for-dsh/lib/index.js`)
- Host plugin → Model installer: manages model (evidence: `packages/voice-for-dsh/lib/index.js`)
- Model installer → Model manifest: reads manifest (evidence: `packages/voice-for-dsh/lib/model-installer.js`)
- Model installer → Kokoro runtime: prepares model (evidence: `packages/voice-for-dsh/lib/model-installer.js`)
- Model installer → Model download source: downloads model (evidence: `README.md`)