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/CHANGELOG.md +143 -0
- package/README.md +402 -39
- package/dist/src/cli.js +137 -10
- package/dist/src/listener.js +532 -0
- package/dist/src/music.js +452 -0
- package/dist/src/outputs.js +29 -4
- package/dist/src/playback.js +170 -46
- package/dist/src/player.js +265 -0
- package/dist/src/project.js +50 -0
- package/dist/src/reading-lock.js +296 -68
- package/dist/src/settings.js +32 -3
- package/dist/src/speech-text.js +581 -64
- package/examples/reply-reader-desktop-audio.service +23 -10
- package/examples/reply-reader-vps-audio.service +57 -0
- package/extensions/reply-reader.ts +920 -106
- package/package.json +3 -2
- package/src/auto-queue.ts +123 -0
- package/src/cli.ts +131 -10
- package/src/listener.ts +522 -0
- package/src/music.ts +474 -0
- package/src/outputs.ts +37 -5
- package/src/pause-key.ts +105 -0
- package/src/playback.ts +179 -48
- package/src/player.ts +255 -0
- package/src/project.ts +46 -0
- package/src/prompts.ts +142 -0
- package/src/reading-lock.ts +364 -66
- package/src/settings.ts +34 -3
- package/src/speech-text.ts +692 -56
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-reply-reader",
|
|
3
|
-
"version": "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
|
-
"
|
|
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 {
|
|
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 {
|
|
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
|
|
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
|
|
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
|
-
//
|
|
184
|
-
const
|
|
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 =
|
|
260
|
+
const reading = startOutputReading({
|
|
187
261
|
voice,
|
|
188
262
|
speaker,
|
|
189
|
-
|
|
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);
|