dsh-tts-chat-answer 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vladimir Cores
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,283 @@
1
- # Temporary Holding Version
1
+ # TTS Chat Answer
2
2
 
3
- 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.
3
+ `dsh-tts-chat-answer` narrates every completed assistant answer from DeepSeek
4
+ Harness and saves the audio locally for later playback and play from web UI.
5
+
6
+ ## Storage
7
+
8
+ The plugin stores audio files in `~/.local/share/dsh-tts-chat-answer/`, grouped
9
+ by workspace and date. Each turn becomes:
10
+
11
+ ```
12
+ ~/.local/share/dsh-tts-chat-answer/
13
+ ├── .ready # written when the plugin mounts
14
+ ├── index.jsonl # global one-line-per-job index (includes workspace)
15
+ └── HPDC-7c1e9a02/ # workspace basename + short cwd hash
16
+ └── 2026-11-19/
17
+ ├── 2026-11-19_14-05-33_<session>_t3.mp3
18
+ ├── 2026-11-19_14-05-33_<session>_t3.txt # transcript of the answer
19
+ └── 2026-11-19_14-05-33_<session>_t3.json # metadata
20
+ ```
21
+
22
+ Each workspace gets its own folder, derived from the session's recorded
23
+ `cwd` (`basename` plus an 8-character SHA-1 prefix of the absolute path). Two
24
+ different projects named `HPDC` therefore do not collide. Sessions without a
25
+ recorded workspace land in `_unknown-workspace/`. Set
26
+ `groupByWorkspace: false` to write a flat `<date>/` tree instead.
27
+
28
+ The MP3 contains the final text-only assistant message of the turn. Markdown,
29
+ tables, links and code fences are converted to spoken prose; code blocks are
30
+ replaced with “Code block omitted” rather than read aloud. Intermediate
31
+ tool-call preambles are skipped.
32
+
33
+ ## Playback
34
+
35
+ Each completed turn gets a small control in the completed-turn footer, next to
36
+ the message actions. It checks the authenticated readiness route:
37
+
38
+ ```text
39
+ GET /dsh-tts-chat-answer/status?session=<session-id>&turn=<turn>
40
+ ```
41
+
42
+ While the MP3 is being generated it shows `Generating…`; once ready it shows
43
+ `Play`. The host reports `playMode` in the same response.
44
+
45
+ `playMode: "inline"` (the default) plays in the Web UI through one shared
46
+ `HTMLAudioElement`. The control becomes `Pause` while playing and `Resume`
47
+ while paused; a `Stop` button resets it. Pressing Play on another answer stops
48
+ the current one, so only one answer ever plays. No external application is
49
+ opened.
50
+
51
+ `playMode: "native"` asks the Host to hand the MP3 to the platform's default
52
+ audio application (`xdg-open` on Linux, `open` on macOS, `start` on Windows)
53
+ and reports state through MPRIS:
54
+
55
+ ```text
56
+ POST /dsh-tts-chat-answer/open
57
+ {"session":"<session-id>","turn":<turn>}
58
+
59
+ POST /dsh-tts-chat-answer/playback
60
+ {"session":"<session-id>","turn":<turn>,"action":"play|pause|stop"}
61
+ ```
62
+
63
+ On Linux the Host matches the player by `xesam:title` / `xesam:url`, then uses
64
+ the standard MPRIS `Play`, `Pause`, `Stop`, and `Quit` methods. The UI follows
65
+ `PlaybackStatus`; pressing `Stop`, reaching the end, or starting another answer
66
+ stops and closes the player. Only one native player opened by this plugin is
67
+ tracked at a time. If no controllable MPRIS player appears, the client falls
68
+ back to the in-page player for that turn.
69
+
70
+ MPRIS control is Linux-only. On macOS and Windows native mode still opens the
71
+ default app, but cannot reflect or close it from the chat; choose `inline`
72
+ there. Both playback modes use the same browser auth as the rest of the Web app;
73
+ the audio files are not public static directories. Set `openCommand` if the
74
+ platform opener is not on `PATH` or needs a custom command.
75
+
76
+ This package has a Web client half (`lib/client.js`, declared under
77
+ `dsh.client`). Restart DSH after installing or updating it so the client
78
+ boot manifest includes the bundle; client-plugin HMR only applies while
79
+ `pnpm run dev:web` is running.
80
+
81
+ ## Voice choices
82
+
83
+ The interactive setup shows a numbered voice menu. The built-in choices are:
84
+
85
+ | Voice | Accent / tone |
86
+ |---|---|
87
+ | `en-US-AriaNeural` | US English, female, warm (default) |
88
+ | `en-US-JennyNeural` | US English, female, friendly |
89
+ | `en-US-GuyNeural` | US English, male, calm |
90
+ | `en-US-DavisNeural` | US English, male, deep |
91
+ | `en-GB-SoniaNeural` | British English, female |
92
+ | `en-GB-RyanNeural` | British English, male |
93
+ | `en-AU-NatashaNeural` | Australian English, female |
94
+ | `en-CA-ClaraNeural` | Canadian English, female |
95
+ | `en-IN-NeerjaNeural` | Indian English, female |
96
+ | `de-DE-KatjaNeural` | German, female |
97
+ | `fr-FR-DeniseNeural` | French, female |
98
+ | `es-ES-ElviraNeural` | Spanish, female |
99
+
100
+ Choose the last menu row to enter any other Edge voice id. The setup derives
101
+ `fallbackVoice` from the primary voice (Aria and Guy swap); the advanced
102
+ section lets you override it. The fallback is only used when Edge returns no
103
+ audio for the primary voice.
104
+
105
+ ## Install into a profile
106
+
107
+ The package is a profile **bundle**. Install it from the checkout:
108
+
109
+ ```bash
110
+ cd /absolute/path/to/plugins/dsh-tts-chat-answer
111
+ npm install
112
+ dsh plugin --profile web add .
113
+ ```
114
+
115
+ `dsh plugin add` installs the dependency and normally selects the bundle in
116
+ `~/.dsh/profiles/web/package.json`. If it is installed but not selected, add it
117
+ to `dsh.profile.bundles`:
118
+
119
+ ```json
120
+ {
121
+ "dsh": {
122
+ "profile": {
123
+ "bundles": [
124
+ "@deepseek-ai/dsh-base",
125
+ "dsh-tts-chat-answer"
126
+ ]
127
+ }
128
+ }
129
+ }
130
+ ```
131
+
132
+ Alternatively, insert it directly in `~/.dsh/profiles/web/cordis.patch.yml`:
133
+
134
+ ```yaml
135
+ - insert:
136
+ - id: tts-chat-answer
137
+ name: 'dsh-tts-chat-answer'
138
+ config:
139
+ enabled: true
140
+ outputDir: '~/.local/share/dsh-tts-chat-answer'
141
+ engine: 'edge'
142
+ playMode: 'inline'
143
+ voice: 'en-US-AriaNeural'
144
+ rate: '+10%'
145
+ ```
146
+
147
+ Restart the DSH Host once after the first installation. A running profile does
148
+ not always hot-add a new module row; restarting is deterministic. After restart,
149
+ this file proves the plugin mounted:
150
+
151
+ ```bash
152
+ cat ~/.local/share/dsh-tts-chat-answer/.ready
153
+ ```
154
+
155
+ Remove the bundle from `dsh.profile.bundles` (or set `enabled: false`) to
156
+ disable it.
157
+
158
+ ## Interactive setup
159
+
160
+ `setup.mjs` prompts for the narration settings and writes a managed
161
+ `tts-chat-answer` override into a profile's `cordis.patch.yml`. The voice
162
+ prompt is a numbered selector; pick a listed voice or choose the custom row
163
+ to type any Edge voice id. The playback prompt offers `inline` (in-page audio)
164
+ or `native` (system app with in-page fallback):
165
+
166
+ ```bash
167
+ node setup.mjs # prompt, profile defaults to web
168
+ node setup.mjs --profile web # skip the profile prompt
169
+ node setup.mjs --profile web --yes
170
+ node setup.mjs --dry-run # print the generated YAML, write nothing
171
+ ```
172
+
173
+ The block is delimited by `# >>> dsh-tts-chat-answer setup >>>` /
174
+ `# <<< dsh-tts-chat-answer setup <<<`, so re-running the script updates it in
175
+ place instead of appending duplicates. A timestamped backup of the previous
176
+ patch file is created before each write. The script does not install the
177
+ package; install it first with `dsh plugin add`, then run setup and restart the
178
+ Host.
179
+
180
+ ## Plugin market
181
+
182
+ The package declares `dsh.bundle`, an `engines.dsh` range, an icon, an English
183
+ locale, and its repository/author metadata, so it can be listed by a DSH plugin
184
+ index. A ready index lives at `site/index.json`; regenerate it after a release
185
+ with the reference generator:
186
+
187
+ ```bash
188
+ pnpm --filter @deepseek-ai/dsh-plugin-market-generator start \
189
+ --input plugins.txt --output site/index.json --title "TTS Chat Answer"
190
+ ```
191
+
192
+ `plugins.txt` holds one line per source: the Git URL gives a commit-pinned
193
+ entry, while `dsh-tts-chat-answer` gives an npm entry after the package is
194
+ published. Serve the `site/` directory over HTTPS and add its `index.json` URL
195
+ under **Plugins → Discover**. See the
196
+ [plugin index guide](https://deepseek-harness.github.io/deepseek-harness/en/guide/plugin-market).
197
+
198
+ ## Publish a release
199
+
200
+ The bundle ships plain JavaScript, so the tarball needs no build step and a Git
201
+ install works from the committed `lib/` tree. Check the package first:
202
+
203
+ ```bash
204
+ npm test # 15 tests
205
+ npm run pack:check # inspect the exact tarball contents
206
+ npm publish --dry-run # validates metadata; uploads nothing
207
+ ```
208
+
209
+ `files` must keep every runtime module, the patch, the locale, the icon, and
210
+ `setup.mjs`. A file added to `lib/` but missing from `files` loads from the
211
+ checkout and fails after `dsh plugin add`. The setup command is declared in
212
+ `bin` without a `./` prefix because npm rejects and silently drops a prefixed
213
+ path at publish time.
214
+
215
+ Then publish and tag:
216
+
217
+ ```bash
218
+ npm publish # needs npm auth and the dsh-tts-chat-answer name
219
+ git push origin main --tags
220
+ ```
221
+
222
+ After the registry accepts the version, switch the market entry from the
223
+ commit-pinned Git source to npm: set the version's `source` to
224
+ `{"type": "npm"}` and `publishTimestamp` to the registry time, or replace the
225
+ Git URL in `plugins.txt` with `dsh-tts-chat-answer` and regenerate the index.
226
+
227
+ ## Requirements
228
+
229
+ - `edge-tts` for the default engine. It is installed at
230
+ `~/.local/bin/edge-tts` on this machine; the plugin also tries `edge-tts`
231
+ from `PATH`.
232
+ - `ffmpeg` when an answer is split into more than one chunk. Without it the
233
+ plugin falls back to a single request.
234
+ - `espeak-ng` + `ffmpeg` for the fully local engine.
235
+ - `native` playback on Linux needs `busctl` and an MPRIS-capable audio player
236
+ (GNOME Decibels, VLC, etc.). Without MPRIS the client falls back to the
237
+ in-page player.
238
+
239
+ ## Configuration
240
+
241
+ | key | default | meaning |
242
+ |---|---|---|
243
+ | `enabled` | `false` | Master switch. The shipped bundle defaults to off; enable it explicitly. |
244
+ | `outputDir` | `~/.local/share/dsh-tts-chat-answer` | Root for audio, transcripts, metadata, index. |
245
+ | `groupByWorkspace` | `true` | Put each workspace in `<basename>-<cwd-hash>/`; `false` writes `<date>/` directly. |
246
+ | `engine` | `edge` | `edge` (neural, online) or `espeak` (robotic, local). |
247
+ | `playMode` | `inline` | `inline` (in-page audio, default) or `native` (system app with MPRIS control and in-page fallback). |
248
+ | `voice` | `en-US-AriaNeural` | Edge voice; setup offers a numbered menu. |
249
+ | `fallbackVoice` | `en-US-GuyNeural` | Retry voice when Edge returns no audio for the primary voice. |
250
+ | `rate` / `volume` / `pitch` | `+10%` / `+0%` / `+0Hz` | Edge prosody. |
251
+ | `minChars` | `40` | Skip turns with almost no speakable text. |
252
+ | `maxChars` | `12000` | Truncate longer answers at a sentence boundary. |
253
+ | `chunkChars` | `1200` | Per-request chunk budget; smaller chunks synthesize faster in parallel. |
254
+ | `concurrency` | `2` | Parallel Edge TTS requests. |
255
+ | `timeoutMs` | `600000` | Per-process deadline. |
256
+ | `maxQueue` | `20` | Backpressure guard. |
257
+ | `includeSubagents` | `false` | Narrate subagent sessions too. |
258
+ | `includeIncomplete` | `false` | Narrate `max-tokens` turns as well as completed turns. |
259
+ | `keepTranscript` | `true` | Write the raw answer text next to the audio. |
260
+ | `redactSecrets` | `true` | Best-effort removal of API keys, private keys, JWTs, etc. |
261
+ | `edgeTtsCommand` | `edge-tts` | Override the executable. |
262
+ | `ffmpegCommand` | `ffmpeg` | Override ffmpeg. |
263
+ | `openCommand` | auto | Override the system opener used by `POST /dsh-tts-chat-answer/open`; the path is appended as its only argument. |
264
+ | `espeakCommand` / `espeakVoice` / `espeakRate` | `espeak-ng` / `en-us` / `165` | Local engine settings. |
265
+
266
+ ## Privacy
267
+
268
+ The bundle ships disabled so installing it does not immediately send chat
269
+ answers anywhere. Enable it explicitly (the setup prompt asks) before use.
270
+
271
+ `engine: "edge"` sends the **speech script of every assistant answer** to
272
+ Microsoft's Edge TTS service. `redactSecrets` and code-block omission reduce
273
+ exposure but are not a guarantee. If responses may contain confidential data,
274
+ use `engine: "espeak"` (fully local) or disable the plugin.
275
+
276
+ ## Test
277
+
278
+ ```bash
279
+ npm install
280
+ npm test
281
+ ```
282
+
283
+ The integration test performs a real Edge TTS synthesis (about 20 seconds).
@@ -0,0 +1,26 @@
1
+ # Profile bundle layer: insert this plugin into whatever profile selects the bundle.
2
+ # Selecting the bundle is the opt-in act; the row is active once selected.
3
+ - insert:
4
+ - id: tts-chat-answer
5
+ name: 'dsh-tts-chat-answer'
6
+ disabled: false
7
+ config:
8
+ enabled: false
9
+ outputDir: '~/.local/share/dsh-tts-chat-answer'
10
+ groupByWorkspace: true
11
+ engine: 'edge'
12
+ playMode: 'inline'
13
+ voice: 'en-US-AriaNeural'
14
+ fallbackVoice: 'en-US-GuyNeural'
15
+ rate: '+10%'
16
+ volume: '+0%'
17
+ pitch: '+0Hz'
18
+ minChars: 40
19
+ maxChars: 12000
20
+ chunkChars: 1200
21
+ concurrency: 2
22
+ timeoutMs: 600000
23
+ includeSubagents: false
24
+ includeIncomplete: false
25
+ keepTranscript: true
26
+ redactSecrets: true