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/README.md CHANGED
@@ -7,7 +7,8 @@ Read a [Pi](https://github.com/earendil-works/pi) or Gentle Shell reply aloud, o
7
7
  another machine you reach over SSH. `/read notes.md` reads a Markdown file the same way.
8
8
 
9
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, and `/read-stop` or Esc stops it.
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.
11
12
  - **Local and offline after setup.** Speech is synthesized on the machine that runs Pi, on the CPU, with no
12
13
  API key. Your replies never leave the machine (except as audio to an output you configured).
13
14
  - **Nothing enters the model context.**
@@ -54,28 +55,121 @@ sentence is synthesized, about 1-2 s.
54
55
  | `/read <id>` | | Reads one reply by ID (see below). |
55
56
  | `/read <file.md>` | | Reads a Markdown file (see below). |
56
57
  | `/read <target>#<section> [rest]` | | Reads one section of a file or reply (see [Reading one section](#reading-one-section)). |
57
- | `/read-stop` | Stop the reading playing, in this or another Pi session (Esc or a new /read stop it too) | Stops the reading playing, in any Pi session of yours on this machine, and says `Reading stopped.`; with nothing playing anywhere, says `Nothing is being read.` |
58
- | `/read-auto [on\|questions\|off]` | Read each new reply aloud when the agent finishes, in this session: on (in full), questions (only "Needs your decision"), off; no argument toggles | See [Auto-read](#auto-read). |
59
- | `/read-output [name]` | Choose where readings sound: local or an output from outputs.json | With a name, switches to that output; without one, asks. See [Outputs](#outputs). |
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). |
60
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. |
61
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). |
62
-
63
- While a reading plays, the footer shows `Reading P12.R1 on local · Esc stops` (or the file name, as in
64
- `Reading notes.md on local · Esc stops`).
65
-
66
- - **Esc** stops the reading. While a reading plays, Esc is taken by the reader, so it does not also
67
- interrupt a running agent turn at that moment; press it again for that.
68
- - **`/read-stop`** stops the reading and says `Reading stopped.`; with nothing playing it says
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
69
84
  `Nothing is being read.` and changes nothing.
70
- - **A new `/read`** stops the reading that is playing and starts the new one.
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.
71
90
  - **One reading per machine.** The last reading wins across every Pi or Gentle Shell session of your user on
72
- the machine: a new `/read` in one session stops a reading playing in another, and `/read-stop` stops it
73
- too. The session whose reading was stopped just clears its footer, with no error. Sessions find each other
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
74
93
  through a small file in `$XDG_RUNTIME_DIR/pi-reply-reader/` (an entry left by a session that is gone is
75
- ignored). Without a usable `XDG_RUNTIME_DIR`, each session only stops its own readings. Esc only stops the
76
- reading of the session you press it in.
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.
77
96
  - The output and the voice last for the session. A new session starts with the male voice and asks for the
78
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.`.
79
173
 
80
174
  ### Reply IDs
81
175
 
@@ -96,7 +190,7 @@ nothing says `No reply matches "<id>".`
96
190
 
97
191
  An argument ending in `.md` or `.markdown` (any case) is a file, not a reply ID: `/read notes.md`,
98
192
  `/read docs/guide.markdown`, `/read /tmp/plan.md` or `/read ~/notes/today.md`. A relative path is resolved
99
- against the session's working directory. The file goes through the same cleanup, voice, output, Esc and
193
+ against the session's working directory. The file goes through the same cleanup, voice, output, pause key and
100
194
  footer as a reply.
101
195
 
102
196
  - A missing or unreadable file gets one warning naming the path as you typed it, such as
@@ -115,11 +209,66 @@ and nothing plays. Only `#` headings count.
115
209
 
116
210
  ### Auto-read
117
211
 
118
- `/read-auto on` reads each new reply aloud when the agent finishes its turn; `/read-auto questions` reads only
119
- the reply's closing **Needs your decision** section (nothing when a reply has none); `/read-auto off` stops.
120
- `/read-auto` alone toggles (off → on in full, on → off). It is per session and starts off in every new
121
- session. Replies from before you turned it on are never read. Auto-readings use the same output, voice,
122
- speed, footer and stop keys (Esc, `/read-stop`) as `/read`, and still follow one reading per machine.
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.
123
272
 
124
273
  ### pi-reply-thread
125
274
 
@@ -127,7 +276,9 @@ Once [`pi-reply-thread`](https://github.com/daniel2010001/pi-reply-thread) suppo
127
276
  reads the selected reply (Replies tab and the reply viewer) or only the selected question (Pending and
128
277
  Answered tabs). The key and its hint appear only when this reader is loaded. A reading started there is the
129
278
  same as `/read`: same cleanup, language, output question on first use, voice, speed, footer (naming the
130
- reply or question ID), Esc, `/read-stop` and one reading per machine. Neither package depends on the other.
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.
131
282
 
132
283
  #### Event contract for other extensions
133
284
 
@@ -137,7 +288,7 @@ Any extension can use the reader over Pi's shared event bus (`pi.events`). Contr
137
288
  |---|---|---|
138
289
  | `reply-reader:ping` | `{ v: 1 }` | Is a reader there? Answered with `reply-reader:ready` synchronously, before your `emit` returns. |
139
290
  | `reply-reader:ready` | `{ v: 1 }` | The reader is there. Also sent at every session start. |
140
- | `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.` |
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. |
141
292
 
142
293
  ```ts
143
294
  let readerReady = false;
@@ -161,12 +312,16 @@ voice, saved speed, outputs and one-reading-per-machine rule as `/read`. `-` rea
161
312
  | `--output <name>` | where it sounds: `local` (default) or a name from `outputs.json` |
162
313
  | `--speed <n>` | voice speed from 0.5 to 2.0 for this run only; settings.json is not changed |
163
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)) |
164
317
  | `-h`, `--help` | usage |
165
318
 
166
319
  If the voice is missing, the command asks `[y/N]` before downloading it. Without a terminal, or when reading
167
320
  standard input, it exits with an error instead of downloading. Ctrl+C, `kill` or closing the terminal stops
168
321
  the reading. A new `/read` or `/read-stop` in any Pi session stops a command reading, and the command stops a
169
- Pi reading.
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)).
170
325
 
171
326
  Exit codes: 0 read (or nothing to read, or stopped by another reading), 1 cannot read, download or play,
172
327
  2 bad arguments, 129/130/143 stopped by SIGHUP, Ctrl+C or SIGTERM.
@@ -195,12 +350,74 @@ else says `Speed must be a number from 0.5 to 2.0.` and changes nothing.
195
350
 
196
351
  - The choice is saved in `$XDG_CONFIG_HOME/pi-reply-reader/settings.json` (`~/.config/…` when
197
352
  `XDG_CONFIG_HOME` is unset) as `{ "speed": 1.15 }`, keeping any other keys, and every later session and
198
- reading uses it. A reading already playing keeps its speed.
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)).
199
356
  - Only the voice speed changes; the pauses between sentences, lines and sections stay the same.
200
357
  - No file means 1.1. An invalid file, or a speed outside 0.5 to 2.0, is ignored with one warning per
201
358
  session, and readings use 1.1. `/read-speed` does not overwrite a file that is not valid JSON.
202
359
  - If the file cannot be saved, the speed still applies to this session and a warning says it was not saved.
203
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
+
204
421
  ## How replies are cleaned for listening
205
422
 
206
423
  The cleanup is deterministic and needs no model, so the same reply always sounds the same.
@@ -231,23 +448,62 @@ agent", "the branch origin main", "a commit", ", line 42", "1 point 1", "approxi
231
448
  IDs, URLs, file names and paths keep their own reading, and a number ending a sentence keeps its period.
232
449
  - **Technical names** are read by kind (`snake_case` loses its `_` everywhere):
233
450
  - a path, as its file or folder plus where it is: `~/.gentle-shell/agent/AGENTS.md` becomes "AGENTS punto md,
234
- en agent", `/tmp/x/wav/hs/` becomes "la carpeta hs, en wav";
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");
235
454
  - a path with a line: `src/speech-text.ts:42` becomes "speech text punto ts, en src, línea 42";
236
455
  - a file name: `README.md` becomes "README punto md";
237
456
  - a branch: `origin/main` becomes "la rama origin main" (after "rama", only the name);
238
457
  - a command: `/reload` becomes "el comando reload" ("del `/reload`" becomes "del comando reload"), while
239
458
  system folders such as `/tmp` read as "la carpeta tmp";
240
459
  - a commit hash is dropped after "commit" and read as "un commit" elsewhere;
241
- - a pair of words: `light/dark` becomes "light o dark".
242
-
243
- Fractions like `1/2`, versions, dates and short pairs like `y/o` stay as they are.
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.
244
488
 
245
489
  ### Known limits
246
490
 
247
491
  - Kinds are guessed from the text alone, so some names are misread: two-word paths such as `odd/tasks`
248
492
  or MIME types such as `application/json` read as alternatives ("odd o tasks"), web routes such as
249
- `/users` read as commands, files without an extension read as folders, and some hosts or code names
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
250
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.
251
507
  - The voice speaks with Spanish pronunciation, also for English text (only the words the cleanup adds
252
508
  switch to English there).
253
509
 
@@ -262,9 +518,14 @@ in `$XDG_CONFIG_HOME/pi-reply-reader/outputs.json` (`~/.config/pi-reply-reader/o
262
518
  ```
263
519
 
264
520
  - Names use letters, digits and `-`, and `local` is built in, so it cannot be redefined.
265
- - Each value must be a non-empty string.
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)).
266
523
  - The first `/read` of a session asks `Where should readings sound?` when there is more than one output;
267
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.
268
529
  - An entry that breaks a rule is skipped with a warning such as
269
530
  `Ignored output "my out" in …/outputs.json: names use letters, digits and "-".` A file that is not valid
270
531
  JSON is ignored as a whole (`Ignored …/outputs.json: not valid JSON (…)`). The warning shows on the first
@@ -283,9 +544,19 @@ synthesized on the server, so its audio has to reach the desktop's speakers.
283
544
  let anyone on the network play sound on the desktop or record its microphone, unless a firewall closes it.
284
545
 
285
546
  **Use an SSH tunnel instead.** It opens nothing on the desktop: a systemd user unit on the server forwards a
286
- loopback port (`127.0.0.1:4714`) to the desktop's own Pulse socket, with SSH doing authentication and
287
- encryption. The unit is in [`examples/reply-reader-desktop-audio.service`](examples/reply-reader-desktop-audio.service)
288
- (it ships with the package, under `node_modules/pi-reply-reader/examples/` once installed).
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).
289
560
 
290
561
  1. On the server, edit the copy for your desktop: `AUDIO_HOST` (the desktop's address), `AUDIO_UID` (your
291
562
  user ID on the desktop, `id -u`) and the user in `you@${AUDIO_HOST}`. The server must reach the
@@ -297,27 +568,119 @@ encryption. The unit is in [`examples/reply-reader-desktop-audio.service`](examp
297
568
  systemctl --user daemon-reload && systemctl --user enable --now reply-reader-desktop-audio.service
298
569
  ```
299
570
 
300
- 3. Name the output in `~/.config/pi-reply-reader/outputs.json`:
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`:
301
573
 
302
574
  ```json
303
- { "desktop": "tcp:127.0.0.1:4714" }
575
+ { "desktop": "unix:/run/user/1000/reply-reader-pulse.sock" }
304
576
  ```
305
577
 
306
578
  4. Verify (prints the desktop's host name; plays nothing):
307
579
 
308
580
  ```sh
309
- PULSE_SERVER=tcp:127.0.0.1:4714 pactl info | grep 'Host Name'
581
+ PULSE_SERVER=unix:$XDG_RUNTIME_DIR/reply-reader-pulse.sock pactl info | grep 'Host Name'
310
582
  ```
311
583
 
312
584
  5. In Pi, `/read-output desktop`, then `/read`.
313
585
 
314
586
  The tunnel is down while the desktop is off; the unit retries every 15 s, and a reading on `desktop` fails
315
- with `Playback on "desktop" failed: …` in the meantime. To keep the tunnel running after you log out of the
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
316
590
  server, enable lingering for your user there (`loginctl enable-linger`).
317
591
 
318
592
  The desktop needs only PipeWire (with pipewire-pulse) or PulseAudio and an SSH server. It needs no TTS, no
319
593
  Pi and no change to its configuration. A new client is one more unit and one more entry in `outputs.json`.
320
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
+
321
684
  ## Requirements
322
685
 
323
686
  - **`paplay`**, on the machine that runs Pi. It comes with `libpulse` on Arch and `pulseaudio-utils` on