pi-reply-reader 0.1.0 → 0.2.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-reply-reader",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Read a Pi or Gentle Shell reply aloud on request, with local text-to-speech and Markdown cleaned up for listening.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -41,7 +41,8 @@
41
41
  "node": ">=22.19.0"
42
42
  },
43
43
  "scripts": {
44
- "build": "tsc -p tsconfig.build.json",
44
+ "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
45
+ "build": "npm run clean && tsc -p tsconfig.build.json",
45
46
  "prepack": "npm run build",
46
47
  "test": "vitest --run",
47
48
  "typecheck": "tsc --noEmit"
@@ -0,0 +1,123 @@
1
+ /**
2
+ * One session's auto-read line (S8 Queue, T32): replies due for auto-read wait here, in order, while a reading plays
3
+ * in this session or anywhere on the machine, and start one at a time once it is free. Auto-read never interrupts.
4
+ */
5
+
6
+ /** "busy": the machine was taken before the reply could start, so it stays first in line; "done": it is used up. */
7
+ export type StartResult = "busy" | "done";
8
+
9
+ export interface AutoQueueOptions<T> {
10
+ /** Whether a reading plays (or is about to) in this session or on the machine. */
11
+ busy: () => boolean;
12
+ /**
13
+ * Starts `item`; resolves once its reading is under way, or was cancelled or dropped. `current()` turns false when
14
+ * the line is cleared meanwhile, so a reply still starting (an output question, a download confirm) must not play.
15
+ * `waited` is true when a reading played while it waited in the line (S14: it then starts after a gap, announced).
16
+ */
17
+ start: (item: T, current: () => boolean, waited: boolean) => Promise<StartResult>;
18
+ /** How often a waiting line checks again whether the machine is free. */
19
+ retryMs: number;
20
+ /** Called whenever the line changes (S16: the session publishes it for /read-queue and the footer). */
21
+ onChange?: () => void;
22
+ }
23
+
24
+ export interface AutoQueue<T> {
25
+ /** Adds a reply at the end of the line, starting it at once when nothing plays. */
26
+ push(item: T): void;
27
+ /**
28
+ * Drops every waiting reply and the one being started (the session's end, an explicit action). With `keep`, only
29
+ * those it rejects (/read-auto off keeps a manual request waiting after "Read after it", T33).
30
+ */
31
+ clear(keep?: (item: T) => boolean): void;
32
+ /** Checks the line again now, as when this session's reading ended. */
33
+ kick(): void;
34
+ /** How many replies wait. */
35
+ readonly size: number;
36
+ /** The replies waiting, in order (S16). */
37
+ readonly items: readonly T[];
38
+ /**
39
+ * The reply being started, until its start settles (S16: it keeps its place in the machine's list meanwhile); once
40
+ * clear() dropped it, undefined even while its start is still in flight (an output question left open, L138).
41
+ */
42
+ readonly starting: T | undefined;
43
+ }
44
+
45
+ export function createAutoQueue<T>(options: AutoQueueOptions<T>): AutoQueue<T> {
46
+ /** The line, in order; `waited` is set once a reading played while the item waited (S14). */
47
+ let items: { item: T; waited: boolean }[] = [];
48
+ /** Bumped by clear(); a start begun under an older generation is no longer current. */
49
+ let generation = 0;
50
+ /** The reply whose start is in flight, with the generation it started under; only one at a time. */
51
+ let starting: { item: T; generation: number } | undefined;
52
+ let timer: ReturnType<typeof setTimeout> | undefined;
53
+
54
+ const later = (): void => {
55
+ if (timer || items.length === 0) return;
56
+ timer = setTimeout(() => {
57
+ timer = undefined;
58
+ pump();
59
+ }, options.retryMs);
60
+ timer.unref?.();
61
+ };
62
+
63
+ const pump = (): void => {
64
+ if (starting || items.length === 0) return;
65
+ if (options.busy()) {
66
+ for (const entry of items) entry.waited = true;
67
+ return later();
68
+ }
69
+ const entry = items.shift() as { item: T; waited: boolean };
70
+ const { item } = entry;
71
+ const mine = generation;
72
+ const current = () => mine === generation;
73
+ starting = { item, generation: mine };
74
+ options.onChange?.();
75
+ const attempt = (async () => options.start(item, current, entry.waited))().catch((): StartResult => "done");
76
+ void attempt.then((result) => {
77
+ starting = undefined;
78
+ if (result === "busy" && current()) {
79
+ // Taken between the check and the claim: try again on the next check, not in a tight loop. It waits for
80
+ // that reading too.
81
+ items.unshift({ item, waited: true });
82
+ options.onChange?.();
83
+ return later();
84
+ }
85
+ options.onChange?.();
86
+ // The reading just started makes the machine busy, so the next reply waits for it; anything pushed while this
87
+ // start was in flight is looked at now.
88
+ pump();
89
+ });
90
+ };
91
+
92
+ return {
93
+ push(item) {
94
+ items.push({ item, waited: false });
95
+ options.onChange?.();
96
+ pump();
97
+ },
98
+ clear(keep) {
99
+ items = keep ? items.filter((entry) => keep(entry.item)) : [];
100
+ // Before onChange, so the line published then no longer lists a dropped reply still starting.
101
+ if (!keep || !starting || !keep(starting.item)) generation++;
102
+ options.onChange?.();
103
+ clearTimeout(timer);
104
+ timer = undefined;
105
+ // Kept replies still wait for the machine.
106
+ later();
107
+ },
108
+ kick() {
109
+ clearTimeout(timer);
110
+ timer = undefined;
111
+ pump();
112
+ },
113
+ get size() {
114
+ return items.length;
115
+ },
116
+ get items() {
117
+ return items.map((entry) => entry.item);
118
+ },
119
+ get starting() {
120
+ return starting && starting.generation === generation ? starting.item : undefined;
121
+ },
122
+ };
123
+ }
package/src/cli.ts CHANGED
@@ -1,15 +1,21 @@
1
1
  import { readFileSync } from "node:fs";
2
2
  import { hostname as osHostname } from "node:os";
3
- import { resolve } from "node:path";
3
+ import { dirname, resolve } from "node:path";
4
4
  import { loadOutputs } from "./outputs.ts";
5
- import { type SherpaTts, startReading } from "./playback.ts";
5
+ import { serve, startOutputReading } from "./listener.ts";
6
+ import { createMusic, loadMusic } from "./music.ts";
7
+ import type { SherpaTts } from "./playback.ts";
8
+ import { PLAYER_MARK, playerTimeoutMs, signalledPlayersEnded } from "./player.ts";
9
+ import { projectChanged, projectOf } from "./project.ts";
6
10
  import { openReadingLock } from "./reading-lock.ts";
7
11
  import { loadSpeed, parseSpeed, SPEED_HINT } from "./settings.ts";
8
- import { speechText } from "./speech-text.ts";
12
+ import { projectAnnouncement, speechNarration } from "./speech-text.ts";
9
13
  import { downloadVoice, findVoice, SPEAKERS, type SpeakerName, type Voice, VOICE_ARCHIVE, type VoiceArchive } from "./voice.ts";
10
14
 
11
15
  /** What `reply-reader --help` prints (S6). */
12
16
  export const USAGE = `Usage: reply-reader [options] <file.md | ->
17
+ reply-reader --download-voice
18
+ reply-reader --serve
13
19
 
14
20
  Reads a Markdown file aloud with local text-to-speech; "-" reads standard input.
15
21
 
@@ -17,6 +23,8 @@ Options:
17
23
  --output <name> where it sounds: local (default) or a name from outputs.json
18
24
  --speed <n> voice speed from 0.5 to 2.0 for this run (default: the saved speed, else 1.1)
19
25
  --voice male|female the voice (default: male)
26
+ --download-voice download the voice (asks first, so it needs a terminal) and exit
27
+ --serve act as a listener: play what an agent host sends over SSH (a listener output in outputs.json)
20
28
  -h, --help show this help
21
29
 
22
30
  Ctrl+C stops the reading.
@@ -96,12 +104,48 @@ function parse(argv: string[]): Options | "help" | { problem: string } {
96
104
  /**
97
105
  * `reply-reader <file.md>` (S6): reads a Markdown file, or standard input with "-", aloud from a terminal without Pi,
98
106
  * through the same cleanup (S2, S7), voice and download confirm, saved speed (S3), named outputs (S4) and one reading
99
- * per machine (S1) as `/read`. Resolves with the exit code; nothing throws.
107
+ * per machine (S1) as `/read`; starting to read drops the auto-reads waiting in Pi sessions (S8). Resolves with the
108
+ * exit code; nothing throws.
100
109
  */
101
110
  export async function main(argv: string[], deps: CliDeps): Promise<number> {
102
111
  const { env, stdout, stderr, signal } = deps;
103
112
  const say = (message: string): void => void stderr.write(`${message}\n`);
104
113
 
114
+ // A listener (S20): the agent host runs `reply-reader --serve --client-name=pi-reply-reader` over SSH.
115
+ if (argv[0] === "--serve") {
116
+ const extra = argv.slice(1).find((arg) => arg !== PLAYER_MARK);
117
+ if (extra !== undefined) {
118
+ stderr.write(`reply-reader: --serve takes no other arguments ("${extra}").\n\n${USAGE}`);
119
+ return USAGE_ERROR;
120
+ }
121
+ // The agent host gone (EPIPE on standard output, A5): the reading stops quietly, like standard input closing.
122
+ const gone = new AbortController();
123
+ const leave = (): void => gone.abort();
124
+ signal?.addEventListener("abort", leave, { once: true });
125
+ if (signal?.aborted) leave();
126
+ const out = stdout as CliDeps["stdout"] & { on?: (event: "error", listener: () => void) => unknown };
127
+ out.on?.("error", leave);
128
+ const write = (text: string): void => {
129
+ if (gone.signal.aborted) return;
130
+ try {
131
+ stdout.write(text);
132
+ } catch {
133
+ leave();
134
+ }
135
+ };
136
+ try {
137
+ return await serve({ env, stdin: deps.stdin, write, warn: say, loadSherpa: deps.loadSherpa, signal: gone.signal });
138
+ } finally {
139
+ signal?.removeEventListener("abort", leave);
140
+ await signalledPlayersEnded();
141
+ }
142
+ }
143
+ if (argv[0] === "--download-voice") {
144
+ if (argv.length === 1) return downloadOnly(deps);
145
+ stderr.write(`reply-reader: --download-voice takes no other arguments ("${argv[1]}").\n\n${USAGE}`);
146
+ return USAGE_ERROR;
147
+ }
148
+
105
149
  const parsed = parse(argv);
106
150
  if (parsed === "help") {
107
151
  stdout.write(USAGE);
@@ -140,8 +184,8 @@ export async function main(argv: string[], deps: CliDeps): Promise<number> {
140
184
  say(`Cannot read "${parsed.file}": ${readProblem(error as NodeJS.ErrnoException)}.`);
141
185
  return FAILED;
142
186
  }
143
- const text = speechText(markdown);
144
- if (!text) {
187
+ const narration = speechNarration(markdown);
188
+ if (!narration.text) {
145
189
  say(`${fromStdin ? "Standard input" : parsed.file} has nothing to read.`);
146
190
  return OK;
147
191
  }
@@ -180,21 +224,60 @@ export async function main(argv: string[], deps: CliDeps): Promise<number> {
180
224
  }
181
225
  if (signal?.aborted) return INTERRUPTED;
182
226
 
183
- // Without a usable XDG_RUNTIME_DIR there is no claim, and only Ctrl+C stops this reading.
184
- const claim = openReadingLock(env)?.claim();
227
+ // An invalid REPLY_READER_PLAYER_TIMEOUT is reported once and the default used (S13 f).
228
+ const timeoutMs = playerTimeoutMs(env, say);
229
+
230
+ // Without a usable XDG_RUNTIME_DIR there is no claim, and only Ctrl+C stops this reading. Like a manual /read it drops
231
+ // the auto-reads waiting in Pi sessions (S8, T33); it never asks.
232
+ const lock = openReadingLock(env);
233
+ const claim = lock?.claim({ dropWaiting: true });
234
+ // Music steps aside while it reads, here for a local or PULSE_SERVER output (a listener's steps aside there), and comes
235
+ // back once nothing reads or waits on the machine; the command waits for that before it exits (S22).
236
+ let musicWarned = false;
237
+ const music = createMusic({
238
+ env,
239
+ settings: () => loadMusic(env).music,
240
+ idle: () => (lock ? !lock.busy() && lock.waitingList().length === 0 : true),
241
+ warn: (message) => {
242
+ if (musicWarned) return;
243
+ musicWarned = true;
244
+ say(message);
245
+ },
246
+ });
247
+ const stepAside = (): void => {
248
+ const { problem } = loadMusic(env);
249
+ if (problem && !musicWarned) {
250
+ musicWarned = true;
251
+ say(problem);
252
+ }
253
+ music.stepAside();
254
+ };
255
+ // A project other than the last reading's on the machine is said first (S19); without XDG_RUNTIME_DIR this process
256
+ // remembers none, so it always is.
257
+ const project = projectOf(deps.cwd ?? process.cwd());
258
+ const said = projectChanged(env, project, {}) ? projectAnnouncement(project, narration.language) : [];
185
259
  let interrupted = false;
186
- const reading = startReading({
260
+ const reading = startOutputReading({
187
261
  voice,
188
262
  speaker,
189
- text,
263
+ fragments: [...said, ...narration.fragments],
190
264
  output,
191
265
  env,
192
266
  loadSherpa: deps.loadSherpa,
193
267
  speed,
268
+ timeoutMs,
194
269
  onPlayer: (pid) => {
195
270
  if (claim && !claim.setPlayer(pid)) reading.stop();
196
271
  },
272
+ // A listener that cannot read sends the reading through its fallback (S20); one reading, so said once. It sounds
273
+ // here then, so the music here steps aside (S22).
274
+ onFallback: (message) => {
275
+ say(message);
276
+ stepAside();
277
+ },
278
+ lost: () => claim?.lost() ?? false,
197
279
  });
280
+ if (!output.ssh) stepAside();
198
281
  const interrupt = (): void => {
199
282
  interrupted = true;
200
283
  reading.stop();
@@ -214,10 +297,48 @@ export async function main(argv: string[], deps: CliDeps): Promise<number> {
214
297
  clearInterval(watch || undefined);
215
298
  signal?.removeEventListener("abort", interrupt);
216
299
  claim?.release();
300
+ music.settle();
301
+ await music.idle();
302
+ // A player this command signalled (a reaped orphan, the reading it took over) gets its SIGKILL before the
303
+ // command exits (S13 e).
304
+ await signalledPlayersEnded();
217
305
  }
218
306
  return interrupted ? INTERRUPTED : OK;
219
307
  }
220
308
 
309
+ /**
310
+ * `reply-reader --download-voice` (S20: how a listener gets its voice, which `--serve` never downloads): asks y/N on a
311
+ * terminal, then downloads it. Exit 0 when it is installed, 1 otherwise.
312
+ */
313
+ async function downloadOnly(deps: CliDeps): Promise<number> {
314
+ const { env, signal } = deps;
315
+ const say = (message: string): void => void deps.stderr.write(`${message}\n`);
316
+ const existing = findVoice(env);
317
+ if (existing) {
318
+ say(`The voice is already installed in ${dirname(dirname(existing.supertonic.ttsJson))}.`);
319
+ return OK;
320
+ }
321
+ if (!deps.isTTY) {
322
+ const megabytes = Math.round((deps.archive ?? VOICE_ARCHIVE).bytes / 1_000_000);
323
+ say(`Downloading the voice (${megabytes} MB) needs a terminal to confirm it. Run reply-reader --download-voice from a terminal.`);
324
+ return FAILED;
325
+ }
326
+ try {
327
+ const voice = await downloadVoice({ env, confirm: deps.confirm, archive: deps.archive, signal });
328
+ if (signal?.aborted) return INTERRUPTED;
329
+ if (!voice) {
330
+ say("Download cancelled: the voice was not downloaded.");
331
+ return FAILED;
332
+ }
333
+ say(`Voice installed in ${dirname(dirname(voice.supertonic.ttsJson))}.`);
334
+ return OK;
335
+ } catch (error) {
336
+ if (signal?.aborted) return INTERRUPTED;
337
+ say((error as Error).message);
338
+ return FAILED;
339
+ }
340
+ }
341
+
221
342
  async function readAll(input: AsyncIterable<Buffer | string>): Promise<string> {
222
343
  const chunks: Buffer[] = [];
223
344
  for await (const chunk of input) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);