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

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