pi-reply-reader 0.0.0-stage → 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/README.md CHANGED
@@ -1,3 +1,711 @@
1
- # Temporary Holding Version
1
+ # pi-reply-reader
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
+ Read a [Pi](https://github.com/earendil-works/pi) or Gentle Shell reply aloud, only when you ask.
4
+
5
+ `/read` takes the latest reply (or one by ID), cleans its Markdown so it sounds like prose instead of
6
+ "asterisco asterisco", and speaks it with a local Spanish voice. The output can be this machine's speakers or
7
+ another machine you reach over SSH. `/read notes.md` reads a Markdown file the same way.
8
+
9
+ - **Nothing plays by itself.** A reading starts only with `/read`. A new reading stops the one playing, even
10
+ in another Pi session on the same machine, so two never overlap. Alt+M or `/read-pause` pauses it and
11
+ resumes it; `/read-stop` ends it. Esc stays Pi's: the reader never takes it.
12
+ - **Local and offline after setup.** Speech is synthesized on the machine that runs Pi, on the CPU, with no
13
+ API key. Your replies never leave the machine (except as audio to an output you configured).
14
+ - **Nothing enters the model context.**
15
+
16
+ ## Install
17
+
18
+ ```sh
19
+ pi install npm:pi-reply-reader
20
+ ```
21
+
22
+ Or try it for one session from a clone:
23
+
24
+ ```sh
25
+ pnpm install
26
+ pi -e ./extensions/reply-reader.ts
27
+ gsh -- -e ./extensions/reply-reader.ts # Gentle Shell
28
+ ```
29
+
30
+ ## First reading: the voice download
31
+
32
+ The voice is not bundled. The first `/read` asks before downloading it:
33
+
34
+ ```
35
+ Reply reader voice
36
+ Download the Spanish voice Supertonic 3 (129 MB) from github.com into /home/you/.local/share/pi-reply-reader/voices?
37
+ ```
38
+
39
+ - It is sherpa-onnx's `sherpa-onnx-supertonic-3-tts-int8-2026-05-11` bundle, pinned by size
40
+ (128,774,318 bytes) and sha256 (`82fa96f9…c427`). Both are checked before anything is extracted.
41
+ - It goes to `$XDG_DATA_HOME/pi-reply-reader/voices` (`~/.local/share/pi-reply-reader/voices` when
42
+ `XDG_DATA_HOME` is unset), once per machine.
43
+ - A failed download keeps nothing; the next `/read` asks again. Declining cancels the reading:
44
+ `Reading cancelled: the voice was not downloaded.`
45
+ - Outside the interactive TUI (print or RPC mode) there is nobody to confirm, so nothing is downloaded.
46
+
47
+ Loading the model takes about a second, once per Pi process. After that, a reading starts after its first
48
+ sentence is synthesized, about 1-2 s.
49
+
50
+ ## Use
51
+
52
+ | Command | Description in Pi | What it does |
53
+ |---|---|---|
54
+ | `/read` | Read a reply aloud: the latest, or one by ID (P12.R1); or a Markdown file (notes.md) | Reads the latest reply of the current branch. |
55
+ | `/read <id>` | | Reads one reply by ID (see below). |
56
+ | `/read <file.md>` | | Reads a Markdown file (see below). |
57
+ | `/read <target>#<section> [rest]` | | Reads one section of a file or reply (see [Reading one section](#reading-one-section)). |
58
+ | `/read-stop` | End the reading, playing or paused, in this or another Pi session, and drop the ones waiting (a new /read ends it too) | Ends the reading playing or paused, in any Pi session of yours on this machine, drops every reading waiting on the machine, and says `Reading stopped.`; with nothing playing anywhere, says `Nothing is being read.` |
59
+ | `/read-pause` | Pause the reading playing, in this or another Pi session, or resume it from the sentence it was in (Alt+M too) | See [Pause and resume](#pause-and-resume). |
60
+ | `/read-queue` | List the readings waiting on this machine, in order, with their sessions | See [The line](#the-line). |
61
+ | `/read-next` | End the reading, playing or paused, in this or another Pi session, and go on with the next one waiting | See [The line](#the-line). |
62
+ | `/read-auto [on\|questions\|off]` | Read each new reply aloud as soon as it is written, and each prompt that waits for you: on (in full), questions (only "Needs your decision"), off; no argument toggles; saved for later sessions | See [Auto-read](#auto-read). |
63
+ | `/read-output [name]` | Choose where readings sound: local or an output from outputs.json; saved for later sessions | With a name, switches to that output; without one, asks. See [Outputs](#outputs). |
64
+ | `/read-voice [male\|female]` | Choose the voice for the next readings: male (default) or female | With a name, switches the voice; without one, asks. |
65
+ | `/read-speed [n]` | Choose the voice speed for the next readings, 0.5 to 2.0 (default 1.1); saved for later sessions | With a number, sets that speed; without one, offers 0.8 to 1.5. See [Speed](#speed). |
66
+ | `/read-music [off\|pause\|duck] [level]` | What music does while the reader speaks: off, pause, or duck [level] (lower gentle-stream to level %, default duck 20); no argument shows it; saved for later sessions | See [Music while reading](#music-while-reading). |
67
+
68
+ While a reading plays, the footer shows `Reading P12.R1 on local · Alt+M pauses` (or the file name, as in
69
+ `Reading notes.md on local · Alt+M pauses`); while it is paused, `Paused P12.R1 · Alt+M resumes · /read-stop ends`.
70
+ The footer names the pause key in use (see [Pause and resume](#pause-and-resume)).
71
+ While readings wait on the machine (auto-reads, **Read after it** and prompts, in any session, see
72
+ [Auto-read](#auto-read)), it adds how many: `Reading P12.R2 on local · 2 waiting · Alt+M pauses`.
73
+ While auto-read is on, the footer always says so, also with nothing playing: `Auto-read on · desktop` or
74
+ `Auto-read questions · desktop` (the output chosen, or just `Auto-read on` before one is), and before a
75
+ reading's status: `Auto-read on · Reading P12.R1 on desktop · Alt+M pauses`. With auto-read off it shows only
76
+ the reading, as above.
77
+
78
+ - **Alt+M** pauses the reading, and resumes it when paused, like `/read-pause` (see
79
+ [Pause and resume](#pause-and-resume)).
80
+ - **Esc is Pi's.** The reader never takes it, whether a reading plays, is paused or not: Esc interrupts the
81
+ agent, closes dialogs and screens (pi-reply-thread's Alt+R view, `ask_user_question`) and dismisses the
82
+ reader's own `Something is being read.` question, as usual.
83
+ - **`/read-stop`** ends the reading, playing or paused, and says `Reading stopped.`; with nothing playing it says
84
+ `Nothing is being read.` and changes nothing.
85
+ - **A new `/read`** while something is being read, here or in another session, first asks
86
+ `Something is being read.`: **Stop it and read now** stops the reading playing and starts the new one;
87
+ **Read after it** waits like an auto-read (see [Auto-read](#auto-read)) and plays once nothing does; Esc
88
+ dismisses the question and changes nothing. With nothing playing, or without a UI, `/read` reads at once.
89
+ `/read-stop`, `/read-pause`, `/read-next` and Alt+M never ask.
90
+ - **One reading per machine.** The last reading wins across every Pi or Gentle Shell session of your user on
91
+ the machine: a new `/read` in one session (answered **Stop it and read now**) stops a reading playing in
92
+ another, and `/read-stop` stops it too. The session whose reading was stopped just clears its footer, with no error. Sessions find each other
93
+ through a small file in `$XDG_RUNTIME_DIR/pi-reply-reader/` (an entry left by a session that is gone is
94
+ ignored). Without a usable `XDG_RUNTIME_DIR`, each session only stops its own readings. Alt+M and
95
+ `/read-pause` reach any session's reading.
96
+ - The output and the voice last for the session. A new session starts with the male voice and asks for the
97
+ output again on its first reading (only when there is more than `local` to choose from).
98
+ - **A player that hangs is ended.** When `paplay` takes no audio for 15 s while audio waits for it (say, its
99
+ Pulse server sits behind an SSH tunnel whose far side does not answer), or does not finish within the
100
+ audio's length plus 15 s once it has all of it, the reading stops with
101
+ `Playback on "<output>" failed: timed out`. Set `REPLY_READER_PLAYER_TIMEOUT` (seconds, whole or
102
+ fractional, from 5 to 86400, in the environment Pi or `reply-reader` runs in) to change the 15 s; any other
103
+ value warns `REPLY_READER_PLAYER_TIMEOUT must be a number of seconds from 5 to 86400; using 15.` once and
104
+ uses 15. A player that keeps taking audio, however slowly, is never cut. Every stop, a new reading, a failed
105
+ reading and a timeout send `paplay` SIGTERM, then SIGKILL 2 s later if it is still there; `reply-reader`
106
+ waits for that before it exits. A player is also killed when Pi or `reply-reader` exits (even when killed
107
+ outright, where `setpriv` is installed), and one left behind by a Pi that died is ended when a Pi session
108
+ starts or the next reading starts. Only players started by this package (marked with
109
+ `--client-name=pi-reply-reader` and the `PI_REPLY_READER_OWNER` variable naming a process that is gone, in
110
+ the same PID namespace) are touched.
111
+
112
+ ### Pause and resume
113
+
114
+ `/read-pause` pauses the reading playing, in this or any other Pi session of yours on the machine, and says
115
+ `Reading paused.`; run again, it resumes it and says `Reading resumed.`. With nothing playing or paused it
116
+ says `Nothing is being read.`. Alt+M does exactly the same, with the same messages.
117
+
118
+ The pause key is Alt+M unless `settings.json` (the file `/read-speed` saves to, see [Speed](#speed)) names
119
+ another as `"pauseKey"`, for example `{ "speed": 1.1, "pauseKey": "alt+o" }`. It is read when Pi loads the
120
+ extension, so a change applies the next time Pi starts. A key is `ctrl` or `alt`, maybe with `shift`, plus a
121
+ letter, digit or F1-F12 (`alt+o`, `alt+5`, `ctrl+shift+e`, `ctrl+f5`). `ctrl` with a digit and any `super` key are
122
+ refused: terminals without the Kitty keyboard protocol never send them, so they would never fire. A key that is
123
+ not like that, or that Pi (on any platform), gentle-pi, pi-reply-thread (Alt+R) or the terminal (as `ctrl+s`) already
124
+ uses, gets one warning when the session starts, such as
125
+ `Ignored pauseKey "alt+r" in …/settings.json: pi-reply-thread already uses it. Alt+M pauses and resumes readings.`,
126
+ and Alt+M is used. Alt+M is the default because it is free in all of them, and terminals send it reliably.
127
+ Esc is never the pause key: it is Pi's.
128
+
129
+ Pausing ends the player (`paplay` cannot be paused cleanly), so the timeout above never fires on a paused
130
+ reading. The reading keeps its turn on the machine: nothing waiting starts while it is paused. Resuming
131
+ synthesizes again from the start of the sentence, list item or table row that was being heard, with the same
132
+ voice, speed and output, so it repeats a few words rather than skipping any (the position is estimated from
133
+ the time each part was handed to the player, half a second early). `/read-stop` ends a paused reading as it
134
+ ends a playing one, and drops what waits.
135
+
136
+ A prompt's reading (see [Prompts that wait for you](#prompts-that-wait-for-you)) is not paused: `/read-pause`
137
+ or Alt+M ends it, says `Reading stopped: a prompt is not paused.`, and the next reading
138
+ waiting starts. A reading of the standalone `reply-reader` command (or of a Pi running an older version of
139
+ this package) cannot be paused from Pi: `/read-pause` says `The reading playing cannot be paused (it is not in
140
+ a Pi session); /read-stop ends it.`.
141
+
142
+ ### The line
143
+
144
+ `/read-queue` lists what waits on the machine, in the order each joined its line: the reply ID, file name or
145
+ prompt kind (`question`, `command confirmation`, `dialog`), and the session (its `/name`, else its working
146
+ folder; yours is marked). Two sessions with the same label are told apart by the last four characters of their
147
+ Pi session ID (`api #3f9c`, `api #a1d0`):
148
+
149
+ ```text
150
+ Waiting on this machine:
151
+ 1. P12.R2 · api (this session)
152
+ 2. notes.md · docs
153
+ 3. question · api (this session)
154
+ ```
155
+
156
+ With nothing waiting it says `Nothing waits to be read.`. Each session publishes its line next to the
157
+ reading entry in `$XDG_RUNTIME_DIR/pi-reply-reader/` (`line-<id>.json`, removed when the line empties or the
158
+ session ends, `/reload` included; a dead session's is ignored and removed). Readings play in the listed order:
159
+ while a session has readings waiting it republishes its line every 250 ms (a heartbeat), and a session whose
160
+ next reading has an earlier one of another session before it lets that one go first for as long as that
161
+ session's heartbeat is under 2 seconds old, for at most 10 seconds per reading. Those 10 seconds count only
162
+ time the machine is free and the session waits for that one: time another reading plays is not counted. A
163
+ reading being started keeps its place until it plays, except while its session waits for you (the output
164
+ question, the voice download confirm): the line file says so, and the other sessions do not wait for it. A
165
+ session that ends, or drops its line, stops beating at once, even if a reading was being started. A frozen, hung or dead session stops beating, so it holds the others about 2 seconds at
166
+ most; then the next reading plays. Without a usable `XDG_RUNTIME_DIR` no session can see
167
+ another's line, so `/read-queue` lists this session's only and says so (`Waiting in this session (other
168
+ sessions are not visible without XDG_RUNTIME_DIR):`), and the footer counts this session's.
169
+
170
+ `/read-next` ends the reading, playing or paused, in this or another session, without dropping the line: the
171
+ next reading waiting starts after the usual 1.5 s of silence, saying which it is. It says `Skipped to the next
172
+ reading.`, or `Reading stopped; nothing else waits.` when nothing waits, or `Nothing is being read.`.
173
+
174
+ ### Reply IDs
175
+
176
+ `/read` numbers replies like [`pi-reply-thread`](https://github.com/daniel2010001/pi-reply-thread)'s
177
+ `/replies`, without needing that package. It accepts:
178
+
179
+ | Form | Example | Reads |
180
+ |---|---|---|
181
+ | Ordered ID, any case | `/read P12.R1`, `/read p12.r1` | The first reply to the twelfth prompt on the branch. |
182
+ | Ordered ID of a question | `/read P12.R1.Q2` | The reply that asks it (`P12.R1`). |
183
+ | Entry ID, exact | `/read a1b2c3d4` | The reply with that Pi session entry ID. |
184
+
185
+ Only final replies count (not tool calls or errors). Gentle Agents wake messages are not prompts, so replies
186
+ they trigger stay under the prompt that started them; replies before any prompt are `P0`. An ID that matches
187
+ nothing says `No reply matches "<id>".`
188
+
189
+ ### Markdown files
190
+
191
+ An argument ending in `.md` or `.markdown` (any case) is a file, not a reply ID: `/read notes.md`,
192
+ `/read docs/guide.markdown`, `/read /tmp/plan.md` or `/read ~/notes/today.md`. A relative path is resolved
193
+ against the session's working directory. The file goes through the same cleanup, voice, output, pause key and
194
+ footer as a reply.
195
+
196
+ - A missing or unreadable file gets one warning naming the path as you typed it, such as
197
+ `Cannot read "notes.md": file not found.`, and nothing plays (and no voice download is offered).
198
+ - A file with nothing to read says `notes.md has nothing to read.`
199
+
200
+ ### Reading one section
201
+
202
+ Add `#section` to read only one section: `/read README.md#install`, `/read P3.R1#usage`, or `/read #usage`
203
+ for the latest reply. It reads from the first matching heading up to the next heading of the same or a
204
+ higher level, subsections included. Add `rest` to keep reading to the end: `/read README.md#install rest`.
205
+ Matching ignores case, accents, punctuation and leading numbers like `2.`, and you can write spaces as `-`
206
+ (`#one-reading-per-machine`). An exact heading wins over one that only starts with your text, which counts
207
+ only if exactly one heading starts with it. If no heading matches you get `No section "<section>" in <name>.`
208
+ and nothing plays. Only `#` headings count.
209
+
210
+ ### Auto-read
211
+
212
+ `/read-auto on` reads each new reply aloud as soon as it is written, even while the agent keeps working (a
213
+ reply followed by a background-job or subagent notice that starts another turn is read too); every reply is
214
+ read once, in order. `/read-auto questions` reads only each reply's closing **Needs your decision** section
215
+ (nothing when a reply has none); `/read-auto off` stops.
216
+ `/read-auto` alone toggles (off → on in full, on → off). Each choice, the toggle included, is saved in
217
+ `settings.json` (see [Speed](#speed)) as `"autoRead": "on"`, `"questions"` or `"off"`, keeping the other keys, and
218
+ every new Pi session on this machine starts with it; with nothing saved, auto-read starts off. While it is on the
219
+ footer says so (`Auto-read on · desktop`, see [Use](#use)). Replies from before you turned it on, or already in a
220
+ session when it starts, are never read. If `settings.json` cannot be saved, the choice applies to this session
221
+ and a warning says it was not saved. Auto-readings use the same output, voice,
222
+ speed, footer and keys (Alt+M pauses, `/read-stop` ends) as `/read`, and still follow one reading per machine.
223
+
224
+ Auto-read never interrupts. A reply that is due while a reading plays, in this session or in any other Pi or
225
+ Gentle Shell session or `reply-reader` command on the machine, waits and is read once nothing plays; one
226
+ session's replies are read in order. While readings wait, the footer of the session reading counts every one
227
+ waiting on the machine (`· 2 waiting ·`), and `/read-queue` lists them (see [The line](#the-line)). When a reading ends and
228
+ another waits, there is about 1.5 s of silence, then the next one starts by saying which it is, in its own
229
+ language: `Respuesta P12.R2.` / `Reply P12.R2.` for a reply, `Archivo notas.md.` / `File notes.md.` for a
230
+ file. A reading with nothing before it starts at once, with no announcement. Explicit actions still win: a manual
231
+ `/read` (or a read from pi-reply-thread's Alt+R view) answered **Stop it and read now** and `/read-stop`
232
+ end the reading playing, as always, and also drop every auto-read waiting on the machine at that moment; replies due after that are read
233
+ as usual. The standalone `reply-reader` command drops them too when it starts reading. `/read-auto off` and the
234
+ end of the session drop that session's waiting replies. Without a usable `XDG_RUNTIME_DIR`, a reply only waits
235
+ for its own session's readings. Alt+M and `/read-pause` drop nothing: a paused reading keeps the machine, so what
236
+ waits keeps waiting; `/read-next` skips to it.
237
+
238
+ A manual `/read` (or a read from Alt+R) that you answer **Read after it** joins the same line: it is read after
239
+ the replies already waiting in its session, once nothing plays, and `/read-stop` or another manual reading
240
+ drops it, here or in any session. It is not an auto-read, so `/read-auto off` keeps it; the end of the session
241
+ drops it.
242
+
243
+ #### Prompts that wait for you
244
+
245
+ With auto-read on (in full or `questions`; prompts are questions too), when the agent stops to ask you
246
+ something, that prompt is read through the same line, in the conversation's language:
247
+
248
+ | Prompt | What is read |
249
+ |---|---|
250
+ | `ask_user_question` / `ask_user_choice` | With auto-read `on`, the text written before the question (in the same message, cleaned like a reply on its own, so none of its Markdown runs into the questions; its language decides the reading's when it tells), then each question with its option labels, never descriptions or values: "Pregunta 1 de 2: ¿Cómo suena? Opciones: uno, Bien; dos, Mal." ("Pregunta: …" for a single question; "Question 1 of 2: … Options: one, …" in English). With `questions`, only the questions are read. Text written before other tool calls, command confirmations included, is not read |
251
+ | A command confirmation (a confirm while a `bash` call waits to run) | "Confirmación de comando: git." / "Command confirmation: git.": the program only, never its arguments (they may hold private values); `NAME=value` assignments, a leading `sudo` or `env` and the program's folder are left out |
252
+ | Any other dialog (RDD consent, other confirms and selects) | Its title only; nothing when it has none (Pi does not give extensions a dialog's text or options) |
253
+
254
+ Once you answer (the dialog closes, or the tool finishes), its reading, the text before the question included,
255
+ is dropped if it still waits, or stopped if it plays; other waiting readings stay. A prompt that waited starts after the usual 1.5 s of
256
+ silence, without an announcement (it says what it is). The reader's own questions (output, voice, speed,
257
+ download, **Something is being read.**) are never read. With auto-read off, nothing of this plays.
258
+
259
+ #### Which project
260
+
261
+ A reading's project is the folder name of the Git root its session's working folder is in (the folder holding
262
+ `.git`; outside a repository, the working folder's own name). Two sessions of the same repository are the same
263
+ project, and so is a linked worktree of it (named by the main repository's folder); a submodule is a project of
264
+ its own, named by its own folder. The machine
265
+ remembers the project of the last reading that started, in any Pi session or `reply-reader` command (in
266
+ `$XDG_RUNTIME_DIR/pi-reply-reader/`). A reading of another project, or the first one when none is remembered,
267
+ starts by saying the project's name, read like any text in the reading's language, then its announcement if it
268
+ waited: `pi-reply-reader. Respuesta P tres, R dos.`. A reading of the same project says no project, so with
269
+ one project you never hear it again. This applies to replies, files, prompts and command readings alike; a
270
+ resumed reading does not say it again. Without a usable `XDG_RUNTIME_DIR`, each Pi process (and each command
271
+ run) remembers only its own.
272
+
273
+ ### pi-reply-thread
274
+
275
+ Once [`pi-reply-thread`](https://github.com/daniel2010001/pi-reply-thread) supports it, `s` in its Alt+R view
276
+ reads the selected reply (Replies tab and the reply viewer) or only the selected question (Pending and
277
+ Answered tabs). The key and its hint appear only when this reader is loaded. A reading started there is the
278
+ same as `/read`: same cleanup, language, output question on first use, voice, speed, footer (naming the
279
+ reply or question ID), Alt+M, `/read-stop` and one reading per machine. Neither package depends on the other.
280
+ While something is being read, `s` asks the same `Something is being read.` question as `/read`. It opens
281
+ in a small box above the Alt+R view, and once it is answered or dismissed (Esc) the keys go back to the view.
282
+
283
+ #### Event contract for other extensions
284
+
285
+ Any extension can use the reader over Pi's shared event bus (`pi.events`). Contract v1:
286
+
287
+ | Channel | Payload | Meaning |
288
+ |---|---|---|
289
+ | `reply-reader:ping` | `{ v: 1 }` | Is a reader there? Answered with `reply-reader:ready` synchronously, before your `emit` returns. |
290
+ | `reply-reader:ready` | `{ v: 1 }` | The reader is there. Also sent at every session start. |
291
+ | `reply-reader:read` | `{ v: 1, id: string, text: string }` | Read `text` (Markdown) aloud like `/read`, naming `id` in the footer and in `<id> has nothing to read.`; while something is being read the reader asks first, as `/read` does. |
292
+
293
+ ```ts
294
+ let readerReady = false;
295
+ pi.events.on("reply-reader:ready", () => (readerReady = true));
296
+ pi.events.emit("reply-reader:ping", { v: 1 }); // readerReady is already set here when the reader is loaded
297
+ if (readerReady) pi.events.emit("reply-reader:read", { v: 1, id: "P12.R1", text: "## Hello\n\nRead **this**." });
298
+ ```
299
+
300
+ A payload that is not an object with `v: 1` and non-empty string `id` and `text` is ignored silently. There
301
+ is no reply to a read request: messages such as a cancelled download are shown by the reader, in the session.
302
+ The reader listens only while a session is running; after the session ends it ignores both requests.
303
+
304
+ ### Standalone command
305
+
306
+ `reply-reader <file.md>` reads a Markdown file aloud from a terminal, without Pi, with the same cleanup,
307
+ voice, saved speed, outputs and one-reading-per-machine rule as `/read`. `-` reads standard input
308
+ (`cat notes.md | reply-reader -`).
309
+
310
+ | Option | Effect |
311
+ |---|---|
312
+ | `--output <name>` | where it sounds: `local` (default) or a name from `outputs.json` |
313
+ | `--speed <n>` | voice speed from 0.5 to 2.0 for this run only; settings.json is not changed |
314
+ | `--voice male\|female` | the voice (default male) |
315
+ | `--download-voice` | download the voice and exit; asks `[y/N]` first, so it needs a terminal |
316
+ | `--serve` | act as a listener: play what an agent host sends over SSH (see [Synthesize on the listener](#synthesize-on-the-listener)) |
317
+ | `-h`, `--help` | usage |
318
+
319
+ If the voice is missing, the command asks `[y/N]` before downloading it. Without a terminal, or when reading
320
+ standard input, it exits with an error instead of downloading. Ctrl+C, `kill` or closing the terminal stops
321
+ the reading. A new `/read` or `/read-stop` in any Pi session stops a command reading, and the command stops a
322
+ Pi reading without asking, dropping the auto-reads waiting in Pi sessions as a manual `/read` does. Ctrl+C
323
+ stops it; it has no pause, and `/read-pause` in Pi cannot pause it. Its project is that of the folder it runs
324
+ in, said first when it differs from the last reading's (see [Which project](#which-project)).
325
+
326
+ Exit codes: 0 read (or nothing to read, or stopped by another reading), 1 cannot read, download or play,
327
+ 2 bad arguments, 129/130/143 stopped by SIGHUP, Ctrl+C or SIGTERM.
328
+
329
+ `pi install` does not put the command on your `PATH`. Install it with npm:
330
+
331
+ ```sh
332
+ npm i -g pi-reply-reader
333
+ ```
334
+
335
+ The installed command is compiled JavaScript (Node does not run TypeScript inside `node_modules`), and it does
336
+ not install Pi. From a checkout, build it and link it instead:
337
+
338
+ ```sh
339
+ pnpm install && pnpm build && pnpm link --global # or npm link instead of pnpm link --global
340
+ ```
341
+
342
+ or link `bin/reply-reader.ts` into a folder on your `PATH`; Node runs that file directly, without a build.
343
+
344
+ ### Speed
345
+
346
+ The voice reads at speed 1.1 by default (1.0 is Supertonic's own pace). `/read-speed 1.15` sets any speed
347
+ from 0.5 to 2.0, and a comma decimal or no leading zero works too (`/read-speed 1,15`, `/read-speed .9`); it
348
+ confirms with `Readings will use speed 1.15.` `/read-speed` alone offers 0.8, 0.9, 1.0, 1.1, 1.2, 1.3 and 1.5. Anything
349
+ else says `Speed must be a number from 0.5 to 2.0.` and changes nothing.
350
+
351
+ - The choice is saved in `$XDG_CONFIG_HOME/pi-reply-reader/settings.json` (`~/.config/…` when
352
+ `XDG_CONFIG_HOME` is unset) as `{ "speed": 1.15 }`, keeping any other keys, and every later session and
353
+ reading uses it. A reading already playing keeps its speed. The same file keeps `pauseKey`, the last
354
+ `/read-auto` and output choices (`autoRead`, `output`; see [Auto-read](#auto-read) and [Outputs](#outputs)),
355
+ and `music` (see [Music while reading](#music-while-reading)).
356
+ - Only the voice speed changes; the pauses between sentences, lines and sections stay the same.
357
+ - No file means 1.1. An invalid file, or a speed outside 0.5 to 2.0, is ignored with one warning per
358
+ session, and readings use 1.1. `/read-speed` does not overwrite a file that is not valid JSON.
359
+ - If the file cannot be saved, the speed still applies to this session and a warning says it was not saved.
360
+
361
+ ### Music while reading
362
+
363
+ While the reader speaks, music steps aside, and comes back when it is done. With nothing set, music played by
364
+ gentle-stream goes down to volume 20, on gentle-stream's own 0-100 volume scale (not 20 % of the volume it had).
365
+ `/read-music` chooses what happens:
366
+
367
+ - `/read-music duck 35` (or `/read-music 35`): sets the volume to 35 (0 to 100), and puts back the volume it
368
+ had. A volume already at or below the level is never raised. `/read-music duck` keeps the saved level.
369
+ - `/read-music pause`: pauses the music, and plays it again after, only if it was playing before.
370
+ - `/read-music off`: leaves the music as it is.
371
+ - `/read-music` alone shows the setting (`Music goes down to 20 % while reading.`). Anything else says
372
+ `Use /read-music off, pause, or duck with a level from 0 to 100.` or `Level must be a whole number from 0 to 100.`
373
+ and changes nothing.
374
+
375
+ The choice is saved in `settings.json` as `"music": { "mode": "duck", "level": 35 }`, keeping the other keys
376
+ (the hooks too), and every later session and reading uses it. An invalid `music` value is ignored with one
377
+ warning per session, and the default is used.
378
+
379
+ **When.** Once per machine, by whoever holds the reading turn (a Pi session, the `reply-reader` command, or
380
+ `--serve` on a listener): the music steps aside when the machine goes from nothing read to a reading, and comes
381
+ back when the reading ends with nothing waiting. Between readings that wait in the line it stays aside, so it does
382
+ not go up and down. Pausing a reading (Alt+M, `/read-pause`) brings the music back; resuming steps it aside again.
383
+ The state before the step aside is kept in `$XDG_RUNTIME_DIR/pi-reply-reader/music.json`, so if a reader dies
384
+ while the music is aside, the next Pi session start (or the next reading's end) puts it back. A replacing reading
385
+ (a new `/read` or `/read-next` while one plays) keeps it aside. A `music.json` that is broken, empty or holds values
386
+ gentle-stream would not take (a volume that is not a whole number from 0 to 100) counts as no state: it is never
387
+ used, it is replaced at the next step aside and removed when the music comes back.
388
+
389
+ **What a restore never does.** It never starts music that was not playing: music already paused or stopped
390
+ when the reading started is not touched at all. If you changed the volume during the reading (it is no longer the
391
+ level the reader set), your volume stays. In pause mode, the music plays again only if it is still paused at the
392
+ volume it had; if you changed it, or played it yourself, it is left as it is.
393
+
394
+ **gentle-stream** is driven through `gentle-stream ctl status --json`, `ctl volume N`, `ctl pause` and `ctl play`.
395
+ Without `gentle-stream` on `PATH`, or with nothing playing (its `ctl` exits 1), nothing happens and nothing is
396
+ said.
397
+
398
+ **Hooks**, for any other player: settings.json `"music": { "before": "<command>", "after": "<command>" }` run
399
+ at the same moments (before: when the music steps aside; after: when it comes back), whatever the mode
400
+ (`"mode": "off"` with hooks uses only the hooks). For example:
401
+
402
+ ```json
403
+ { "music": { "mode": "off", "before": "playerctl pause", "after": "playerctl play" } }
404
+ ```
405
+
406
+ Each hook runs through `/bin/sh -c`, as you, with your environment: it comes from your own settings file and
407
+ nothing from a reply is ever put in it, so treat it like a line of your shell profile.
408
+
409
+ **Never in the way of speech.** Every command (gentle-stream's or a hook) runs in the background, in its own
410
+ process group, and is ended after 3 s; speech never waits for it. A command that fails or hangs is said once per
411
+ session, for example `Music hook "before" timed out after 3 s; it was ended.` The limit ends the hook's process
412
+ group only: a hook that starts a child in the background (`cmd &`, `setsid`, a daemon) returns at once, and that
413
+ child keeps running past the 3 s.
414
+
415
+ **Where it runs.** Where the music plays: on the agent host for `local` and `PULSE_SERVER` outputs (and for a
416
+ listener output that reads through its fallback); on the listener for a listener output, where
417
+ `reply-reader --serve` steps the listener's music aside with the listener's own settings, and the agent host does
418
+ not touch its own. After a listener reading ends, `--serve` keeps the music aside for 4 s more, so the agent host's
419
+ next reading in its line finds it still aside; a stopped or paused reading brings it back at once.
420
+
421
+ ## How replies are cleaned for listening
422
+
423
+ The cleanup is deterministic and needs no model, so the same reply always sounds the same.
424
+
425
+ The reader detects whether a reply or file is English or Spanish from its own words (no model; Spanish
426
+ wins ties), and every word the cleanup adds follows it. `/reload` reads as "the command reload" in English
427
+ text and "el comando reload" in Spanish; likewise "Code block." / "Bloque de código.", "AGENTS dot md, in
428
+ agent", "the branch origin main", "a commit", ", line 42", "1 point 1", "approximately", "seconds",
429
+ "percent", and marks by name ("period", "comma", "tilde"…). A token followed by its own noun is not doubled
430
+ ("the `/read` command" reads "the read command"). The voice itself still speaks with Spanish pronunciation.
431
+
432
+ - **Markdown**: emphasis, headings, bullets, numbered items, blockquotes, links and rules lose their syntax
433
+ and keep their words. Headings and list items end as sentences. Inline code is read without backticks.
434
+ A heading or a line that is all bold is read like a title, followed by a longer pause. A numbered item or
435
+ heading reads its number as "1:" so the voice does not stop after it, and the closing
436
+ "Needs your decision" heading is read as "Decisiones pendientes".
437
+ - **Tables**: each row is read as one sentence, cells separated by commas.
438
+ - **Code blocks** are announced, not read: `Bloque de código.`
439
+ - **URLs** are read as their host name (`github.com`).
440
+ - **Reply IDs**: `P11.R1.Q1` is read as "P 11, R 1, Q 1".
441
+ - **Symbols** become words: `→` "a", `←` "desde", `≈` "aproximadamente", `≠` "distinto de", `≥` "mayor o igual
442
+ a", `≤` "menor o igual a", `±` "más o menos", `&` "y", and `×` between numbers "por". Emoji are dropped.
443
+ - **Numbers**: `~` before a number reads "aproximadamente", and units after a number are spelled out (`1,2 s`
444
+ "1,2 segundos", `ms`, `min`, `KB`/`MB`/`GB`, `%` "por ciento", `dB`/`dBFS` "decibeles"), singular after 1.
445
+ Inline code holding a single punctuation mark reads its name: `` `.` `` "punto", `` `;` `` "punto y coma".
446
+ Numbers with dots read "punto": `1.1` is "1 punto 1", `0.8.0` "0 punto 8 punto 0", and a numbered heading
447
+ `## 5.2. Título` reads "5 punto 2: Título". Spanish thousands (`2.750`, `1.500.000`), IP addresses, reply
448
+ IDs, URLs, file names and paths keep their own reading, and a number ending a sentence keeps its period.
449
+ - **Technical names** are read by kind (`snake_case` loses its `_` everywhere):
450
+ - a path, as its file or folder plus where it is: `~/.gentle-shell/agent/AGENTS.md` becomes "AGENTS punto md,
451
+ en agent", `/tmp/x/wav/hs/` becomes "la carpeta hs, en wav", a bare `src/` becomes "la carpeta src", and a
452
+ last part starting with a dot reads like any other (`ckan-docker/.prettierrc.json` becomes "prettierrc punto
453
+ json, en ckan docker");
454
+ - a path with a line: `src/speech-text.ts:42` becomes "speech text punto ts, en src, línea 42";
455
+ - a file name: `README.md` becomes "README punto md";
456
+ - a branch: `origin/main` becomes "la rama origin main" (after "rama", only the name);
457
+ - a command: `/reload` becomes "el comando reload" ("del `/reload`" becomes "del comando reload"), while
458
+ system folders such as `/tmp` read as "la carpeta tmp";
459
+ - a commit hash is dropped after "commit" and read as "un commit" elsewhere;
460
+ - a pair of words: `light/dark` becomes "light o dark";
461
+ - an issue or PR number: `el PR #43` becomes "el PR número 43" ("number 43" in English);
462
+ - a key combination: `Ctrl+Shift+P` becomes "Control más Shift más P" ("plus" in English), `Alt+R` "Alt más R";
463
+ - a minimum version: `v1+` becomes "v1 o superior" ("or later" in English), `v2.0+` "v2 punto 0 o superior",
464
+ `1.4+` "1 punto 4 o superior";
465
+ - a count: `100+` becomes "100 o más" ("100 or more" in English), `300+ líneas` "300 o más líneas";
466
+ - a time: `21:02` becomes "veintiuno cero dos", `07:30` "siete treinta" ("seven thirty"), `21:02:15`
467
+ "veintiuno cero dos quince" and `07:00` "siete en punto" ("seven o'clock"); hours 0-23 and minutes 00-59 only;
468
+ - a date with a year, `2026-10-27` or day first `27/10/2026`: "veintisiete de octubre de dos mil veintiséis"
469
+ ("October twenty seven, two thousand twenty six"); `17/10` and `1/2` stay as they are;
470
+ - a glob: `*.hs.lan` becomes "cualquier hs punto lan" ("any"), `bin/*` "todo lo de bin" ("everything in"),
471
+ `lab-*` "lab algo" ("something");
472
+ - tags, HTML or not (a name of letters, digits and `-`): a pair reads the name, a colon and the content, the
473
+ closing tag silent (`<command>ls -la</command>` becomes "command: ls -la", `<thinking>dudo</thinking>`
474
+ "thinking: dudo"); a lone `<name>` reads only the name (`reply-reader <archivo>` becomes "reply-reader
475
+ archivo", "un `<iframe>`" "un iframe"); a lone closing `</a>` or a self-closing `<br/>` becomes "la etiqueta
476
+ a" ("the a tag"; after "etiqueta" or "tag", only the name);
477
+ - `<< text >>` reads like quotes: the marks are silent and the text gets a short pause around it (`<< esto no
478
+ es un tag >>` becomes "esto no es un tag"); a shift such as `a << b`, with no closing `>>` or no words
479
+ inside, stays as written;
480
+ - numbers, last, in the text's language: `51` becomes "cincuenta y uno" ("fifty one"), `11.457` "once mil
481
+ cuatrocientos cincuenta y siete", `1,2` "uno coma dos", `1.4` "uno punto cuatro", `-16` "menos dieciséis".
482
+ In Spanish the number agrees with the next word: `1 segundo` "un segundo", `21 líneas` "veintiuna líneas",
483
+ `de 1 a 5` "de uno a cinco", and hundreds too: `400 líneas` "cuatrocientas líneas", `200.000 líneas`
484
+ "doscientas mil líneas". Numbers of more than 9 digits, or starting with 0, are read digit by digit
485
+ (`007` "cero cero siete"). Digits in URLs, hosts and unrecognized technical tokens stay as written.
486
+
487
+ Fractions like `1/2` keep their slash ("uno/dos") and short pairs like `y/o` stay as they are.
488
+
489
+ ### Known limits
490
+
491
+ - Kinds are guessed from the text alone, so some names are misread: two-word paths such as `odd/tasks`
492
+ or MIME types such as `application/json` read as alternatives ("odd o tasks"), web routes such as
493
+ `/users` read as commands, files without an extension read as folders (`ckan-docker/Makefile` becomes
494
+ "la carpeta Makefile, en ckan docker"; a dot file such as `ckan-docker/.gitignore` reads as a file,
495
+ "gitignore, en ckan docker", but a lone `~/.gitignore` reads as a folder, like `~/.ssh`), dot folders
496
+ written without a final `/` inside a longer path read as files (`/home/.snapshots` becomes "snapshots, en
497
+ home"), browser versions written without `v` read as counts ("Chrome 123 o más"), and some hosts or code names
498
+ read as file names (`org.bluez` becomes "org punto bluez").
499
+ - Numbers: the feminine list is short (an unlisted feminine noun gets "un" and masculine hundreds), a count
500
+ with `+` keeps the masculine ("trescientos o más líneas"), a date without a year or written month first
501
+ keeps its slashes ("diecisiete/diez"), eight-digit stamps such as `20261026` are read as one number, and an
502
+ English thousands comma in Spanish text (`1,044`) reads as a decimal.
503
+ - Times, globs and tags are guessed from their shape: a ratio such as `1:30` reads as a time; a token of only
504
+ letters wrapped in `*` or `**` is taken for Markdown written as code and reads only its letters
505
+ (`**negrita**` becomes "negrita"), not a glob; inline HTML pairs read like any other pair (`<em>todas</em>` becomes
506
+ "em: todas"); and a tag glued to a word (`a<b>c`, `List<String>`) stays as written.
507
+ - The voice speaks with Spanish pronunciation, also for English text (only the words the cleanup adds
508
+ switch to English there).
509
+
510
+ ## Outputs
511
+
512
+ An output is where a reading sounds. `local` is always there: this machine's default sink. You add others
513
+ in `$XDG_CONFIG_HOME/pi-reply-reader/outputs.json` (`~/.config/pi-reply-reader/outputs.json` when
514
+ `XDG_CONFIG_HOME` is unset), an object that maps each name to a `PULSE_SERVER` value:
515
+
516
+ ```json
517
+ { "desktop": "tcp:127.0.0.1:4714" }
518
+ ```
519
+
520
+ - Names use letters, digits and `-`, and `local` is built in, so it cannot be redefined.
521
+ - Each value must be a non-empty string, or an object `{ "ssh": "you@host", "fallback": "<PULSE_SERVER>" }`
522
+ for a listener that synthesizes the reading itself (see [Synthesize on the listener](#synthesize-on-the-listener)).
523
+ - The first `/read` of a session asks `Where should readings sound?` when there is more than one output;
524
+ `/read-output` switches later, and completes the names.
525
+ - The output picked (at that question or with `/read-output`) is saved in `settings.json` as
526
+ `"output": "desktop"`, keeping the other keys, and every new Pi session on this machine uses it without
527
+ asking. A saved output no longer in `outputs.json` is not used: the session warns
528
+ `Saved output "desktop" is not in …/outputs.json; choose one.` and the first reading asks as usual.
529
+ - An entry that breaks a rule is skipped with a warning such as
530
+ `Ignored output "my out" in …/outputs.json: names use letters, digits and "-".` A file that is not valid
531
+ JSON is ignored as a whole (`Ignored …/outputs.json: not valid JSON (…)`). The warning shows on the first
532
+ `/read` of a session and on every `/read-output`, so a typo never sends a reading somewhere else
533
+ silently.
534
+
535
+ Outside the interactive TUI nothing can be asked: with more than one output, pick one first with
536
+ `/read-output <name>`, or the reading is cancelled (`Reading cancelled: no output chosen.`).
537
+
538
+ ## Hear it on another machine over SSH
539
+
540
+ A common setup: Pi runs on a server, and you sit at a desktop connected to it over SSH. The reading is
541
+ synthesized on the server, so its audio has to reach the desktop's speakers.
542
+
543
+ **Why not open a PulseAudio TCP port on the desktop?** pipewire-pulse has no IP allow-list. A LAN port would
544
+ let anyone on the network play sound on the desktop or record its microphone, unless a firewall closes it.
545
+
546
+ **Use an SSH tunnel instead.** It opens nothing on the desktop: a systemd user unit on the server forwards a
547
+ socket on the server to the desktop's own Pulse socket, with SSH doing authentication and encryption. The
548
+ unit is in [`examples/reply-reader-desktop-audio.service`](examples/reply-reader-desktop-audio.service)
549
+ (it ships with the package, under `node_modules/pi-reply-reader/examples/` once installed). Only audio
550
+ travels: the text is synthesized on the server and never leaves it.
551
+
552
+ **Why a Unix socket and not a loopback port such as `127.0.0.1:4714`?** The forwarded Pulse socket gives the
553
+ desktop's whole audio, microphone included. A loopback port is open to every process on the server, other
554
+ users and containers with host networking. The unit creates `reply-reader-pulse.sock` with mode 0600 inside
555
+ your 0700 runtime dir (`/run/user/<uid>`), so only your user can open it. Whoever can act as your user on the
556
+ server (root included) can still use the desktop's audio while the tunnel is up.
557
+
558
+ This unit needs the server to reach the desktop (same LAN, Tailscale). For a cloud VPS that cannot reach
559
+ the desktop, see [From a cloud VPS](#from-a-cloud-vps).
560
+
561
+ 1. On the server, edit the copy for your desktop: `AUDIO_HOST` (the desktop's address), `AUDIO_UID` (your
562
+ user ID on the desktop, `id -u`) and the user in `you@${AUDIO_HOST}`. The server must reach the
563
+ desktop with `ssh` and a key, without a password prompt (`BatchMode=yes`).
564
+ 2. Install it (on the machine that runs Pi):
565
+
566
+ ```sh
567
+ cp examples/reply-reader-desktop-audio.service ~/.config/systemd/user/
568
+ systemctl --user daemon-reload && systemctl --user enable --now reply-reader-desktop-audio.service
569
+ ```
570
+
571
+ 3. Name the output in `~/.config/pi-reply-reader/outputs.json`, with your user ID on the server (`id -u`)
572
+ in place of `1000`:
573
+
574
+ ```json
575
+ { "desktop": "unix:/run/user/1000/reply-reader-pulse.sock" }
576
+ ```
577
+
578
+ 4. Verify (prints the desktop's host name; plays nothing):
579
+
580
+ ```sh
581
+ PULSE_SERVER=unix:$XDG_RUNTIME_DIR/reply-reader-pulse.sock pactl info | grep 'Host Name'
582
+ ```
583
+
584
+ 5. In Pi, `/read-output desktop`, then `/read`.
585
+
586
+ The tunnel is down while the desktop is off; the unit retries every 15 s, and a reading on `desktop` fails
587
+ with `Playback on "desktop" failed: …` in the meantime. When the tunnel is up but the desktop does not
588
+ answer, `paplay` would wait forever; the reading fails with `Playback on "desktop" failed: timed out`
589
+ after 15 s instead (`REPLY_READER_PLAYER_TIMEOUT`, 5 to 86400 seconds, changes it). To keep the tunnel running after you log out of the
590
+ server, enable lingering for your user there (`loginctl enable-linger`).
591
+
592
+ The desktop needs only PipeWire (with pipewire-pulse) or PulseAudio and an SSH server. It needs no TTS, no
593
+ Pi and no change to its configuration. A new client is one more unit and one more entry in `outputs.json`.
594
+
595
+ An older setup with `tcp:127.0.0.1:4714` keeps working; moving to the socket is the unit above plus the new
596
+ `outputs.json` value. Readings sound the same either way (ten `pactl info` calls took 79 ms over the port
597
+ and 76 ms over the socket).
598
+
599
+ ### From a cloud VPS
600
+
601
+ A VPS usually cannot reach a desktop behind NAT, so the desktop connects out and asks the VPS to forward a
602
+ socket back (`ssh -R`). The unit is
603
+ [`examples/reply-reader-vps-audio.service`](examples/reply-reader-vps-audio.service), installed **on the
604
+ desktop**:
605
+
606
+ 1. On the VPS, once: `loginctl enable-linger`, so `/run/user/<uid>` exists without a login session.
607
+ 2. On the desktop, edit the copy: `VPS_HOST`, `VPS_UID` (your user ID on the VPS) and the user in
608
+ `you@${VPS_HOST}`. The desktop must reach the VPS with `ssh` and a key, without a password prompt.
609
+ 3. Install it on the desktop:
610
+
611
+ ```sh
612
+ cp examples/reply-reader-vps-audio.service ~/.config/systemd/user/
613
+ systemctl --user daemon-reload && systemctl --user enable --now reply-reader-vps-audio.service
614
+ ```
615
+
616
+ 4. On the VPS, name the output (`VPS_UID` in place of `1000`) and verify as in steps 3 and 4 above:
617
+ `{ "desktop": "unix:/run/user/1000/reply-reader-pulse.sock" }`.
618
+
619
+ The VPS's sshd creates the socket with mode 0600. It keeps it after a dropped connection and then refuses the
620
+ next forward (`remote port forwarding failed for listen path …`), so the unit removes it before connecting;
621
+ `StreamLocalBindUnlink yes` in the VPS's `sshd_config` makes that step unnecessary. Root on the VPS, and so
622
+ your cloud provider, can use the desktop's audio while the tunnel is up: keep the unit stopped when you do
623
+ not need readings there.
624
+
625
+ ## Synthesize on the listener
626
+
627
+ In the setup above, the machine that runs Pi (the **agent host**) synthesizes every reading and only the audio
628
+ travels. When the agent host is slow (a small VPS, a loaded server), readings start late and stutter. A
629
+ **listener** output moves the synthesis to the machine where you listen: the agent host sends each reading's
630
+ cleaned text, voice, speed and pauses over SSH to `reply-reader --serve` on the listener, which synthesizes
631
+ and plays it there. Example: Pi on a home server, a desktop as the listener.
632
+
633
+ On the listener:
634
+
635
+ 1. Install the command and its voice (Node 22.19 or newer, PipeWire with pipewire-pulse or PulseAudio, `paplay`):
636
+
637
+ ```sh
638
+ npm i -g pi-reply-reader
639
+ reply-reader --download-voice
640
+ ```
641
+
642
+ 2. Make sure `reply-reader` is on the `PATH` of a non-interactive SSH command: from the agent host,
643
+ `ssh you@listener reply-reader --help` must print the usage.
644
+
645
+ On the agent host:
646
+
647
+ 3. The agent host must reach the listener with `ssh` and a key, without a password prompt (it runs
648
+ `ssh -o BatchMode=yes … you@listener reply-reader --serve --client-name=pi-reply-reader`).
649
+ 4. Name the output in `~/.config/pi-reply-reader/outputs.json`, with a fallback (optional, recommended):
650
+
651
+ ```json
652
+ { "desktop": { "ssh": "you@listener", "fallback": "unix:/run/user/1000/reply-reader-pulse.sock" } }
653
+ ```
654
+
655
+ `ssh` is what you would type after `ssh` (a host, `user@host`, or a `Host` alias of your SSH client
656
+ configuration); it cannot start with `-` or hold spaces or control characters. `fallback` is a `PULSE_SERVER` value, such as the
657
+ tunnel above. Any other key is reported and the entry skipped.
658
+ 5. In Pi, `/read-output desktop`, then `/read` (or `reply-reader --output desktop notes.md`).
659
+
660
+ Everything else works as for any output: the line and its order, the announcements, prompts read aloud,
661
+ pause and resume (from the sentence being heard on the listener), `/read-stop` and a new reading from any
662
+ session (they end the `ssh` child, which ends the reading on the listener), and the player timeout. The
663
+ listener respects its own turn: while it reads something of its own, the agent host's reading waits. A
664
+ reading of its own started on the listener ends the one it serves, and a `/read-stop` (or a `/read`) there
665
+ while the agent host's reading still waits drops it; either way the agent host's reading ends quietly, with
666
+ no fallback. Long readings are sent in several messages, so they stay on the listener; only a single
667
+ sentence over 1 MiB goes to the fallback (`a sentence is too long to send to the listener (over 1048576 bytes)`).
668
+
669
+ **The fallback.** When the listener does not answer (no route, a refused key, `ssh` not installed, nothing
670
+ heard within the player timeout), lacks `reply-reader`, its voice or `paplay`, runs an incompatible version,
671
+ or fails while reading, the reading goes on from the sentence last heard: synthesized on the agent host and
672
+ played through `fallback`, with one warning per session such as
673
+ `Output "desktop": the listener did not answer; reading here through its fallback.` or, without the voice,
674
+ `Output "desktop": the listener has no voice (install it there with "reply-reader --download-voice"); reading here through its fallback.`
675
+ Without a fallback the reading fails with `Playback on "desktop" failed: <reason>`. The agent host still
676
+ needs its own voice for the fallback. Text from the listener or `ssh` shown in these messages has its control
677
+ characters removed, and a line from the listener over 64 KiB ends the reading there
678
+ (`the listener sent a line longer than 65536 bytes`).
679
+
680
+ `reply-reader --serve` never downloads and writes no file besides the reading lock (and, when the music steps
681
+ aside, `music.json`) under `$XDG_RUNTIME_DIR/pi-reply-reader/`. It only plays what it is sent; whoever can run `ssh` as you to the
682
+ listener can make it speak.
683
+
684
+ ## Requirements
685
+
686
+ - **`paplay`**, on the machine that runs Pi. It comes with `libpulse` on Arch and `pulseaudio-utils` on
687
+ Debian and Ubuntu. Without it, `/read` says `Cannot play: paplay was not found on PATH …`.
688
+ - **`tar` with bzip2 support**, for the one-time voice download.
689
+ - **Node.js >= 22.19.**
690
+ - **A CPU is enough.** No GPU is used. The engine is
691
+ [sherpa-onnx-node](https://github.com/k2-fsa/sherpa-onnx) 2.0.1 (installed with the package).
692
+
693
+ ## Develop
694
+
695
+ ```sh
696
+ pnpm install
697
+ pnpm test
698
+ pnpm typecheck
699
+ pnpm build # compiles the reply-reader command into dist/ (also run by npm pack)
700
+ ```
701
+
702
+ ## License
703
+
704
+ MIT for this package.
705
+
706
+ The voice is downloaded separately and has its own licenses:
707
+
708
+ - Supertonic 3 weights: OpenRAIL-M, see
709
+ [Supertone/supertonic-3](https://huggingface.co/Supertone/supertonic-3/blob/main/LICENSE).
710
+ - Supertonic code: MIT, see [supertone-inc/supertonic](https://github.com/supertone-inc/supertonic).
711
+ - sherpa-onnx, which runs it: [Apache-2.0](https://github.com/k2-fsa/sherpa-onnx/blob/master/LICENSE).