pi-reply-reader 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +143 -0
- package/README.md +402 -39
- package/dist/src/cli.js +137 -10
- package/dist/src/listener.js +532 -0
- package/dist/src/music.js +452 -0
- package/dist/src/outputs.js +29 -4
- package/dist/src/playback.js +170 -46
- package/dist/src/player.js +265 -0
- package/dist/src/project.js +50 -0
- package/dist/src/reading-lock.js +296 -68
- package/dist/src/settings.js +32 -3
- package/dist/src/speech-text.js +581 -64
- package/examples/reply-reader-desktop-audio.service +23 -10
- package/examples/reply-reader-vps-audio.service +57 -0
- package/extensions/reply-reader.ts +920 -106
- package/package.json +3 -2
- package/src/auto-queue.ts +123 -0
- package/src/cli.ts +131 -10
- package/src/listener.ts +522 -0
- package/src/music.ts +474 -0
- package/src/outputs.ts +37 -5
- package/src/pause-key.ts +105 -0
- package/src/playback.ts +179 -48
- package/src/player.ts +255 -0
- package/src/project.ts +46 -0
- package/src/prompts.ts +142 -0
- package/src/reading-lock.ts +364 -66
- package/src/settings.ts +34 -3
- package/src/speech-text.ts +692 -56
package/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
|
|
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` |
|
|
58
|
-
| `/read-
|
|
59
|
-
| `/read-
|
|
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
|
-
|
|
64
|
-
`Reading
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
-
|
|
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`**
|
|
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
|
|
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.
|
|
76
|
-
|
|
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,
|
|
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
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
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),
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
287
|
-
|
|
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": "
|
|
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=
|
|
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.
|
|
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
|