dsh-tts-chat-answer 0.4.1 → 0.5.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/README.md CHANGED
@@ -3,12 +3,59 @@
3
3
  `dsh-tts-chat-answer` narrates every completed assistant answer from DeepSeek
4
4
  Harness and saves the audio locally for later playback and play from web UI.
5
5
 
6
- ## Setup
6
+ ## Install
7
+
8
+ The package is a profile **bundle**: installing it also selects it as a layer.
9
+ Pick one source.
10
+
11
+ From the plugin market, add the index source under **Plugins → Discover → Add
12
+ index source**:
13
+
14
+ ```text
15
+ https://vladimircores.github.io/dsh-tts-chat-answer/index.json
16
+ ```
7
17
 
8
- Install the bundle into a profile and run the interactive setup:
18
+ From npm, which serves the same tarball the market installs:
9
19
 
10
20
  ```bash
11
21
  dsh plugin --profile web add dsh-tts-chat-answer
22
+ ```
23
+
24
+ From GitHub, which needs no build step because the JavaScript is committed:
25
+
26
+ ```bash
27
+ dsh plugin --profile web add github:VladimirCores/dsh-tts-chat-answer
28
+ ```
29
+
30
+ From a checkout, install the plugin's own dependencies and link it:
31
+
32
+ ```bash
33
+ cd /absolute/path/to/dsh-tts-chat-answer
34
+ npm install
35
+ dsh plugin --profile web add .
36
+ ```
37
+
38
+ `dsh plugin add` installs the dependency and selects the bundle in
39
+ `~/.dsh/profiles/web/package.json`. If a package ends up installed but not
40
+ selected, add `dsh-tts-chat-answer` to `dsh.profile.bundles`. A running profile
41
+ does not always hot-add a new row, so restart the Host; afterwards
42
+ `~/.local/share/dsh-tts-chat-answer/.ready` proves the plugin mounted. Disable
43
+ it with `dsh plugin --profile web remove dsh-tts-chat-answer`, or set
44
+ `enabled: false` in the profile patch.
45
+
46
+ pnpm 11 applies a **24-hour `minimumReleaseAge` cooldown** by default. A version
47
+ published in the last day is listed in the index but still fails to install with
48
+ `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`, and even removing it fails while the
49
+ lockfile holds that version. Wait until the release is a day old, or set
50
+ `minimumReleaseAge: 0` in the profile's `pnpm-workspace.yaml` (for example
51
+ `~/.dsh/profiles/web/pnpm-workspace.yaml`) to install immediately. Restore the
52
+ setting afterwards so later installs keep the cooldown.
53
+
54
+ ## Setup
55
+
56
+ After installing, run the interactive setup:
57
+
58
+ ```bash
12
59
  npx -p dsh-tts-chat-answer dsh-tts-chat-answer-setup
13
60
  ```
14
61
 
@@ -64,6 +111,18 @@ GET /dsh-tts-chat-answer/status?session=<session-id>&turn=<turn>
64
111
  While the MP3 is being generated it shows `Generating…`; once ready it shows
65
112
  `Play`. The host reports `playMode` in the same response.
66
113
 
114
+ Messages that existed before the plugin was installed have no MP3, so their
115
+ control shows `Generate` instead of `Play`. Clicking it narrates that existing
116
+ answer and then polls until the audio is ready:
117
+
118
+ ```text
119
+ POST /dsh-tts-chat-answer/generate
120
+ {"session":"<session-id>","turn":<turn>}
121
+ ```
122
+
123
+ A turn whose last attempt failed shows `Retry`. Generation uses the same queue,
124
+ voice, and output layout as automatic narration.
125
+
67
126
  `playMode: "inline"` (the default) plays in the Web UI through one shared
68
127
  `HTMLAudioElement`. The control becomes `Pause` while playing and `Resume`
69
128
  while paused; a `Stop` button resets it. Pressing Play on another answer stops
@@ -124,59 +183,6 @@ Choose the last menu row to enter any other Edge voice id. The setup derives
124
183
  section lets you override it. The fallback is only used when Edge returns no
125
184
  audio for the primary voice.
126
185
 
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
186
  ## Plugin market
181
187
 
182
188
  The package is published on npm as `dsh-tts-chat-answer` and declares
@@ -184,9 +190,7 @@ The package is published on npm as `dsh-tts-chat-answer` and declares
184
190
  repository/author metadata, so a DSH plugin index can list it.
185
191
 
186
192
  `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**.
193
+ <https://vladimircores.github.io/dsh-tts-chat-answer/>.
190
194
 
191
195
  Regenerate the entry with the reference generator after a release:
192
196
 
@@ -224,10 +228,15 @@ npm publish
224
228
  git push --follow-tags
225
229
  ```
226
230
 
227
- After the registry accepts the version, update `site/index.json`: set
231
+ After the registry accepts the version, prepend it to `site/index.json`: set
228
232
  `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.
233
+ dsh-tts-chat-answer time --json`), and keep `source` as `{"type": "npm"}`. Keep
234
+ earlier versions in the array so the page can install them. The Pages workflow
235
+ republishes `site/` on the next push.
236
+
237
+ Expect a one-day gap before the new entry is installable: pnpm's default
238
+ 24-hour release-age cooldown rejects any version younger than that. The
239
+ [Install](#install) note explains the workaround and when to restore the setting.
231
240
 
232
241
  ## Requirements
233
242
 
package/lib/client.js CHANGED
@@ -191,9 +191,10 @@ window.__ModuleLoader__.load({
191
191
  * Poll the host for this turn's narration state.
192
192
  * @param {string} sessionId - slot-injected session id.
193
193
  * @param {number} turn - turn number.
194
+ * @param {number} revision - bump to restart polling after a generation request.
194
195
  * @returns {[object, Function]} state and setter.
195
196
  */
196
- function useAudioStatus(sessionId, turn) {
197
+ function useAudioStatus(sessionId, turn, revision) {
197
198
  const [status, setStatus] = React.useState({ state: "loading", error: null });
198
199
 
199
200
  React.useEffect(() => {
@@ -246,7 +247,7 @@ window.__ModuleLoader__.load({
246
247
  controller.abort();
247
248
  if (timer !== undefined) clearTimeout(timer);
248
249
  };
249
- }, [sessionId, turn]);
250
+ }, [sessionId, turn, revision]);
250
251
 
251
252
  return [status, setStatus];
252
253
  }
@@ -283,6 +284,30 @@ window.__ModuleLoader__.load({
283
284
  }, [enabled, sessionId, turn, setStatus]);
284
285
  }
285
286
 
287
+ /**
288
+ * Pick the footer button caption for the current narration state.
289
+ * A turn without audio offers Generate; a failed one offers Retry.
290
+ *
291
+ * @param {{state: string, error?: string|null}} status - host status.
292
+ * @param {{active: boolean, playing: boolean, inlineLoading: boolean,
293
+ * busyAction: boolean, generating: boolean, playbackError: string|null}} view
294
+ * - local control state.
295
+ * @returns {string} button caption.
296
+ */
297
+ function controlLabel(status, view) {
298
+ if (view.generating) return "Generating…";
299
+ if (view.busyAction) return "Opening…";
300
+ if (view.inlineLoading) return "Starting…";
301
+ if (view.active) return view.playing ? "Pause" : "Resume";
302
+ if (status.state === "missing") return "Generate";
303
+ if (status.state === "error") return "Retry";
304
+ if (status.state === "loading" || status.state === "queued" || status.state === "processing") {
305
+ return "Generating…";
306
+ }
307
+ if (view.playbackError !== null) return "Audio error";
308
+ return "Play";
309
+ }
310
+
286
311
  /**
287
312
  * Play/Pause and Stop controls rendered in the completed-turn footer.
288
313
  * @param {{turn: number|{turn: number}, sessionId: string}} props - slot props and injected session.
@@ -292,7 +317,9 @@ window.__ModuleLoader__.load({
292
317
  // The turnTail slot exposes the whole Turn owner object, while older
293
318
  // slots passed the bare number. Accept both and key everything by number.
294
319
  const turnNumber = typeof turn === "number" ? turn : turn?.turn;
295
- const [status, setStatus] = useAudioStatus(sessionId, turnNumber);
320
+ const [revision, setRevision] = React.useState(0);
321
+ const [generating, setGenerating] = React.useState(false);
322
+ const [status, setStatus] = useAudioStatus(sessionId, turnNumber, revision);
296
323
  const inlineState = useInlineState();
297
324
  const [fallbackInline, setFallbackInline] = React.useState(false);
298
325
  const [busyAction, setBusyAction] = React.useState(false);
@@ -302,6 +329,7 @@ window.__ModuleLoader__.load({
302
329
  const key = `${String(sessionId)}:${String(turnNumber)}`;
303
330
  const ready = status.state === "ready";
304
331
  const busy = status.state === "loading" || status.state === "queued" || status.state === "processing";
332
+ const canGenerate = status.state === "missing" || status.state === "error";
305
333
  const inlineActive = inlineState.key === key
306
334
  && (inlineState.state === "playing" || inlineState.state === "paused" || inlineState.state === "loading");
307
335
  const nativePlayback = usingInline ? undefined : status.playback;
@@ -406,32 +434,64 @@ window.__ModuleLoader__.load({
406
434
  nativePlaying, sessionId, turnNumber, key, audioUrl, status, setStatus,
407
435
  ]);
408
436
 
409
- const label = busyAction
410
- ? "Opening…"
411
- : inlineActive && inlineState.state === "loading"
412
- ? "Starting…"
413
- : active
414
- ? playing
415
- ? "Pause"
416
- : "Resume"
417
- : busy
418
- ? "Generating…"
419
- : playbackError !== null
420
- ? "Audio error"
421
- : status.state === "error"
422
- ? "Audio error"
423
- : "Play";
424
- const hint = status.state === "error"
425
- ? status.error
426
- : playbackError !== null
427
- ? playbackError
428
- : active
429
- ? `${playing ? "Playing" : "Paused"} ${formatTime(positionMs)}${durationMs > 0 ? ` / ${formatTime(durationMs)}` : ""}`
430
- : busy
431
- ? "Preparing audio…"
432
- : busyAction
433
- ? "Opening in the system player…"
434
- : null;
437
+ const onGenerate = React.useCallback(async () => {
438
+ if (!canGenerate || generating) return;
439
+ setGenerating(true);
440
+ try {
441
+ const response = await fetch("/dsh-tts-chat-answer/generate", {
442
+ method: "POST",
443
+ credentials: "same-origin",
444
+ headers: { "content-type": "application/json" },
445
+ body: JSON.stringify({ session: sessionId, turn: turnNumber }),
446
+ });
447
+ const body = await response.json().catch(() => ({}));
448
+ if (!response.ok) throw new Error(body.error ?? `HTTP ${response.status}`);
449
+ setStatus({
450
+ state: body.state === "ready" ? "ready" : "queued",
451
+ playMode: status.playMode,
452
+ error: null,
453
+ });
454
+ // Re-run the status hook so it polls until the queue produces audio.
455
+ setRevision((value) => value + 1);
456
+ } catch (error) {
457
+ setStatus({ state: "error", error: error?.message ?? "Could not generate audio" });
458
+ } finally {
459
+ setGenerating(false);
460
+ }
461
+ }, [canGenerate, generating, sessionId, turnNumber, status.playMode, setStatus]);
462
+
463
+ const label = controlLabel(status, {
464
+ active,
465
+ playing,
466
+ inlineLoading: inlineActive && inlineState.state === "loading",
467
+ busyAction,
468
+ generating,
469
+ playbackError,
470
+ });
471
+ const hint = generating
472
+ ? "Generating audio…"
473
+ : canGenerate
474
+ ? status.state === "error"
475
+ ? status.error
476
+ : "No audio for this message yet — generate it"
477
+ : status.state === "error"
478
+ ? status.error
479
+ : playbackError !== null
480
+ ? playbackError
481
+ : active
482
+ ? `${playing ? "Playing" : "Paused"} ${formatTime(positionMs)}${durationMs > 0 ? ` / ${formatTime(durationMs)}` : ""}`
483
+ : busy
484
+ ? "Preparing audio…"
485
+ : busyAction
486
+ ? "Opening in the system player…"
487
+ : null;
488
+ const actionTitle = canGenerate
489
+ ? status.state === "error"
490
+ ? "Retry narration"
491
+ : "Generate narration"
492
+ : active
493
+ ? playing ? "Pause narration" : "Resume narration"
494
+ : "Play narration";
435
495
 
436
496
  return React.createElement(
437
497
  "span",
@@ -440,18 +500,16 @@ window.__ModuleLoader__.load({
440
500
  "button",
441
501
  {
442
502
  type: "button",
443
- onClick: onPrimary,
444
- disabled: !ready || busyAction,
503
+ onClick: canGenerate ? onGenerate : onPrimary,
504
+ disabled: busyAction || generating || (!ready && !canGenerate),
445
505
  style: {
446
506
  ...BUTTON_STYLE,
447
- opacity: ready ? 1 : 0.55,
448
- cursor: ready ? "pointer" : "default",
507
+ opacity: ready || canGenerate ? 1 : 0.55,
508
+ cursor: ready || canGenerate ? "pointer" : "default",
449
509
  },
450
- title: active ? (playing ? "Pause narration" : "Resume narration") : "Play narration",
451
- "aria-label": active
452
- ? (playing ? "Pause narration" : "Resume narration")
453
- : "Play narration",
454
- "aria-busy": busy,
510
+ title: actionTitle,
511
+ "aria-label": actionTitle,
512
+ "aria-busy": busy || generating,
455
513
  "data-state": active ? (playing ? "playing" : "paused") : status.state,
456
514
  },
457
515
  label,
@@ -493,6 +551,7 @@ window.__ModuleLoader__.load({
493
551
  inlineStop,
494
552
  ensureInlineAudio,
495
553
  getInlineSnapshot,
554
+ controlLabel,
496
555
  };
497
556
  return module.exports;
498
557
  },
package/lib/index.js CHANGED
@@ -167,7 +167,7 @@ export function apply(ctx, rawConfig = {}) {
167
167
  // `inject` keeps non-web profiles working: without these services the
168
168
  // callback never runs, but generation and the ready marker still load.
169
169
  if (typeof ctx.inject === "function") {
170
- ctx.inject(["webServer", "connection"], (webCtx) => {
170
+ ctx.inject(["webServer", "connection", "sessions"], (webCtx) => {
171
171
  registerAudioRoute(webCtx);
172
172
  });
173
173
  }
@@ -441,6 +441,77 @@ export function apply(ctx, rawConfig = {}) {
441
441
  sendJson(res, 200, payload);
442
442
  },
443
443
  }),
444
+ webCtx.webServer.register({
445
+ kind: "exact",
446
+ path: "/dsh-tts-chat-answer/generate",
447
+ handler: async (req, res) => {
448
+ if (!authorize(req, res)) return;
449
+ if (req.method !== "POST") {
450
+ res.statusCode = 405;
451
+ res.setHeader("allow", "POST");
452
+ res.end();
453
+ return;
454
+ }
455
+ const contentType = String(req.headers["content-type"] ?? "").split(";", 1)[0].trim().toLowerCase();
456
+ if (contentType !== "application/json") {
457
+ sendJson(res, 415, { error: "content-type must be application/json" });
458
+ return;
459
+ }
460
+ let body;
461
+ try {
462
+ body = await readJsonBody(req, 4096);
463
+ } catch {
464
+ sendJson(res, 400, { error: "request body is not valid JSON" });
465
+ return;
466
+ }
467
+ const sessionId = typeof body?.session === "string" ? body.session : "";
468
+ const turn = Number(body?.turn);
469
+ if (sessionId.length === 0 || !Number.isInteger(turn) || turn < 0) {
470
+ sendJson(res, 400, { error: "session and non-negative integer turn are required" });
471
+ return;
472
+ }
473
+ const existing = await findAudio(cfg.outputDir, sessionId, turn);
474
+ if (existing !== undefined) {
475
+ sendJson(res, 200, { ok: true, state: "ready" });
476
+ return;
477
+ }
478
+ const running = state.jobs.get(`${sessionId}:${turn}`);
479
+ if (running !== undefined) {
480
+ sendJson(res, 200, {
481
+ ok: true,
482
+ state: running.status === "processing" ? "processing" : "queued",
483
+ });
484
+ return;
485
+ }
486
+ const sessions = Reflect.get(webCtx, "sessions");
487
+ const session = sessions?.get?.(sessionId);
488
+ if (session === undefined) {
489
+ sendJson(res, 404, { error: "session is not loaded; open the conversation first" });
490
+ return;
491
+ }
492
+ const picked = pickAssistantText(session, turn);
493
+ if (picked === undefined) {
494
+ sendJson(res, 422, { error: "no assistant answer for this turn" });
495
+ return;
496
+ }
497
+ const speech = prepareSpeech(picked.text, cfg);
498
+ if (speech.length < cfg.minChars) {
499
+ sendJson(res, 422, { error: "answer is too short to narrate" });
500
+ return;
501
+ }
502
+ if (state.queue.length >= cfg.maxQueue) {
503
+ sendJson(res, 429, { error: "narration queue is full" });
504
+ return;
505
+ }
506
+ const job = buildJob(session, turn, picked, speech, undefined);
507
+ state.seen.add(job.key);
508
+ state.jobs.set(job.key, { status: "queued", createdAt: job.createdAt });
509
+ state.queue.push(job);
510
+ log.info(`generate ${job.key} workspace=${job.workspaceKey} (${speech.length} speakable)`);
511
+ void drain();
512
+ sendJson(res, 200, { ok: true, state: "queued" });
513
+ },
514
+ }),
444
515
  webCtx.webServer.register({
445
516
  kind: "exact",
446
517
  path: "/dsh-tts-chat-answer/open",
@@ -598,16 +669,39 @@ export function apply(ctx, rawConfig = {}) {
598
669
  }
599
670
 
600
671
  state.seen.add(key);
672
+ const job = buildJob(session, turn, picked, speech, event?.seq);
673
+ state.jobs.set(job.key, { status: "queued", createdAt: job.createdAt });
674
+ state.queue.push(job);
675
+ log.info(
676
+ `queued ${job.key} workspace=${job.workspaceKey} ` +
677
+ `(${picked.text.length} chars, ${speech.length} speakable)`,
678
+ );
679
+ void drain();
680
+ }
681
+
682
+ /**
683
+ * Describe one synthesis job: output paths, text, and workspace.
684
+ * Automatic turn/end narration and on-demand generation share this shape.
685
+ *
686
+ * @param {object} session - Session that owns the turn.
687
+ * @param {number} turn - turn number.
688
+ * @param {{text: string}} picked - assistant answer chosen for narration.
689
+ * @param {string} speech - speech-ready text.
690
+ * @param {number|undefined} eventSeq - originating event sequence, when any.
691
+ * @returns {object} job.
692
+ */
693
+ function buildJob(session, turn, picked, speech, eventSeq) {
694
+ const sessionId = String(session?.id ?? session?.header?.id ?? "unknown");
601
695
  const workspace = workspaceInfo(session?.header?.cwd, cfg.groupByWorkspace);
602
696
  const dir = join(cfg.outputDir, ...workspace.dirParts, dayStamp());
603
697
  const base = baseName(sessionId, turn);
604
- const job = {
605
- key,
698
+ return {
699
+ key: `${sessionId}:${turn}`,
606
700
  sessionId,
607
701
  turn,
608
702
  workspaceKey: workspace.key,
609
703
  workspacePath: workspace.path,
610
- eventSeq: event?.seq,
704
+ eventSeq,
611
705
  createdAt: new Date().toISOString(),
612
706
  text: picked.text,
613
707
  speech,
@@ -618,13 +712,6 @@ export function apply(ctx, rawConfig = {}) {
618
712
  json: join(dir, `${base}.json`),
619
713
  },
620
714
  };
621
- state.jobs.set(key, { status: "queued", createdAt: job.createdAt });
622
- state.queue.push(job);
623
- log.info(
624
- `queued ${key} workspace=${workspace.key} ` +
625
- `(${picked.text.length} chars, ${speech.length} speakable)`,
626
- );
627
- void drain();
628
715
  }
629
716
 
630
717
  /** Process queued jobs one at a time. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-tts-chat-answer",
3
- "version": "0.4.1",
3
+ "version": "0.5.0",
4
4
  "description": "Narrate completed assistant answers with Edge TTS, save audio locally, and play it in-page or in a native MPRIS player.",
5
5
  "author": "Vladimir Cores",
6
6
  "license": "MIT",
@@ -25,7 +25,7 @@
25
25
  "type": "module",
26
26
  "main": "lib/index.js",
27
27
  "bin": {
28
- "dsh-tts-chat-answer-setup": "setup.mjs"
28
+ "setup": "setup.mjs"
29
29
  },
30
30
  "scripts": {
31
31
  "setup": "node setup.mjs",