pi-reply-reader 0.0.0-stage → 0.1.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 ADDED
@@ -0,0 +1,57 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 — 2026-11-17
4
+
5
+ First release.
6
+
7
+ - Event contract v1 for other extensions over `pi.events`, for `pi-reply-thread`'s Alt+R `s` key:
8
+ `reply-reader:ping` `{ v: 1 }` is answered at once with `reply-reader:ready` `{ v: 1 }` (also sent at every
9
+ session start), and `reply-reader:read` `{ v: 1, id, text }` reads `text` aloud like `/read`, naming `id`
10
+ in the footer. Invalid payloads are ignored.
11
+ - `/read-auto on|questions|off` (bare toggles): read each new reply, or only its "Needs your decision"
12
+ section, when the agent's turn ends; off at every session start.
13
+ - `/read <file|ID|empty>#<section>`: read only that section; add `rest` to read on to the end.
14
+ - `reply-reader <file.md>` command: reads a Markdown file (or `-` for standard input) aloud outside Pi, with
15
+ `--output`, `--speed` (this run only), `--voice` and `--help`. Exit codes 0/1/2, and 129/130/143 when a
16
+ signal stops it. It shares the one-reading-per-machine rule with `/read`. `npm i -g pi-reply-reader`
17
+ installs it as compiled JavaScript, without installing Pi.
18
+ - English replies and files are read with English connecting words ("the command", "Code block.", "1 point 1",
19
+ units and marks), detected from the text itself; Spanish text reads as before.
20
+ - `/read` reads a reply aloud on request only: the latest reply of the branch, or one by ID with
21
+ `/read P12.R1` (any case, a `.Q<n>` suffix accepted, numbered like `pi-reply-thread`'s `/replies`) or by
22
+ its entry ID. Nothing plays by itself. A new reading stops the one playing, and Esc stops it; the footer
23
+ shows `Reading P12.R1 on local · Esc stops` meanwhile.
24
+ - `/read-stop` stops the reading playing and says "Reading stopped."; with nothing playing it says
25
+ "Nothing is being read." and changes nothing.
26
+ - One reading per machine: a new `/read` in any Pi session or process of your user stops a reading playing in
27
+ another, and `/read-stop` stops it too; the session whose reading was stopped clears its footer with no
28
+ error. Coordinated through `$XDG_RUNTIME_DIR/pi-reply-reader/reading.json`; an entry whose process is gone
29
+ is ignored, only a player started by the reader is ever signalled, and without a usable `XDG_RUNTIME_DIR`
30
+ each session stops only its own readings, as before.
31
+ - `/read <file.md>` reads a Markdown file aloud (`.md` or `.markdown`, any case), resolved against the
32
+ session's working directory (absolute and `~/` paths work too), with the same cleanup, voice, output,
33
+ Esc and footer as a reply. A missing or unreadable file gets one warning naming it, and nothing plays.
34
+ - Local Spanish voice, Supertonic 3 through sherpa-onnx-node 2.0.1, on the CPU with no API key. The first
35
+ `/read` asks before downloading it once (129 MB, pinned size and sha256) into
36
+ `$XDG_DATA_HOME/pi-reply-reader/voices`; a failed download keeps nothing. Text is synthesized sentence by
37
+ sentence, so audio starts after the first sentence, and the next sentence is synthesized while one plays;
38
+ both voices are brought to the same loudness.
39
+ - `/read-voice [male|female]` picks the voice for the next readings: male (default) or female.
40
+ - Configurable voice speed, 1.1 by default. `/read-speed <n>` sets any speed from 0.5 to 2.0 (`1,15` works
41
+ too, and so does `.9` without the leading zero); `/read-speed` alone offers 0.8 to 1.5. It is saved in `$XDG_CONFIG_HOME/pi-reply-reader/settings.json`
42
+ as `{ "speed": … }`, keeping other keys, for every later reading and session; a reading already playing
43
+ keeps its speed, and the pauses do not change. An invalid file or speed warns once per session and uses
44
+ 1.1; if saving fails, the speed applies to the session with a warning.
45
+ - Replies are cleaned for listening: Markdown syntax is removed, table rows become sentences, code blocks
46
+ are announced as "Bloque de código.", URLs are read as their host, reply IDs as "P 11, R 1, Q 1",
47
+ symbols such as `→` and `≈` as words, and emoji are dropped. Technical names are read by kind: a path as
48
+ its file or folder plus where it is, a branch, a command, a file name, a commit hash, a pair of words.
49
+ Approximations and units are spelled out, numbered items read "1:" instead of stopping after the number,
50
+ and bold-only lines and headings are read as titles. Numbers with dots read "punto" (`1.1` "1 punto 1",
51
+ `## 5.2. Título` "5 punto 2: Título"), while Spanish thousands such as `2.750` and IP addresses stay.
52
+ - Named outputs: `local` (this machine's default sink) plus the names in
53
+ `$XDG_CONFIG_HOME/pi-reply-reader/outputs.json`, each mapped to a `PULSE_SERVER`. The first `/read` of a
54
+ session asks which one when there is more than `local`; `/read-output [name]` switches. Bad entries are
55
+ skipped with a warning.
56
+ - `examples/reply-reader-desktop-audio.service`: a systemd user unit that tunnels the audio over SSH to the
57
+ machine you sit at, which needs only PipeWire or PulseAudio, with no port opened on it.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Daniel Li
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,348 @@
1
- # Temporary Holding Version
1
+ # pi-reply-reader
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Read a [Pi](https://github.com/earendil-works/pi) or Gentle Shell reply aloud, only when you ask.
4
+
5
+ `/read` takes the latest reply (or one by ID), cleans its Markdown so it sounds like prose instead of
6
+ "asterisco asterisco", and speaks it with a local Spanish voice. The output can be this machine's speakers or
7
+ another machine you reach over SSH. `/read notes.md` reads a Markdown file the same way.
8
+
9
+ - **Nothing plays by itself.** A reading starts only with `/read`. A new reading stops the one playing, even
10
+ in another Pi session on the same machine, so two never overlap, and `/read-stop` or Esc stops it.
11
+ - **Local and offline after setup.** Speech is synthesized on the machine that runs Pi, on the CPU, with no
12
+ API key. Your replies never leave the machine (except as audio to an output you configured).
13
+ - **Nothing enters the model context.**
14
+
15
+ ## Install
16
+
17
+ ```sh
18
+ pi install npm:pi-reply-reader
19
+ ```
20
+
21
+ Or try it for one session from a clone:
22
+
23
+ ```sh
24
+ pnpm install
25
+ pi -e ./extensions/reply-reader.ts
26
+ gsh -- -e ./extensions/reply-reader.ts # Gentle Shell
27
+ ```
28
+
29
+ ## First reading: the voice download
30
+
31
+ The voice is not bundled. The first `/read` asks before downloading it:
32
+
33
+ ```
34
+ Reply reader voice
35
+ Download the Spanish voice Supertonic 3 (129 MB) from github.com into /home/you/.local/share/pi-reply-reader/voices?
36
+ ```
37
+
38
+ - It is sherpa-onnx's `sherpa-onnx-supertonic-3-tts-int8-2026-05-11` bundle, pinned by size
39
+ (128,774,318 bytes) and sha256 (`82fa96f9…c427`). Both are checked before anything is extracted.
40
+ - It goes to `$XDG_DATA_HOME/pi-reply-reader/voices` (`~/.local/share/pi-reply-reader/voices` when
41
+ `XDG_DATA_HOME` is unset), once per machine.
42
+ - A failed download keeps nothing; the next `/read` asks again. Declining cancels the reading:
43
+ `Reading cancelled: the voice was not downloaded.`
44
+ - Outside the interactive TUI (print or RPC mode) there is nobody to confirm, so nothing is downloaded.
45
+
46
+ Loading the model takes about a second, once per Pi process. After that, a reading starts after its first
47
+ sentence is synthesized, about 1-2 s.
48
+
49
+ ## Use
50
+
51
+ | Command | Description in Pi | What it does |
52
+ |---|---|---|
53
+ | `/read` | Read a reply aloud: the latest, or one by ID (P12.R1); or a Markdown file (notes.md) | Reads the latest reply of the current branch. |
54
+ | `/read <id>` | | Reads one reply by ID (see below). |
55
+ | `/read <file.md>` | | Reads a Markdown file (see below). |
56
+ | `/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). |
60
+ | `/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
+ | `/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
69
+ `Nothing is being read.` and changes nothing.
70
+ - **A new `/read`** stops the reading that is playing and starts the new one.
71
+ - **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
74
+ 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.
77
+ - The output and the voice last for the session. A new session starts with the male voice and asks for the
78
+ output again on its first reading (only when there is more than `local` to choose from).
79
+
80
+ ### Reply IDs
81
+
82
+ `/read` numbers replies like [`pi-reply-thread`](https://github.com/daniel2010001/pi-reply-thread)'s
83
+ `/replies`, without needing that package. It accepts:
84
+
85
+ | Form | Example | Reads |
86
+ |---|---|---|
87
+ | Ordered ID, any case | `/read P12.R1`, `/read p12.r1` | The first reply to the twelfth prompt on the branch. |
88
+ | Ordered ID of a question | `/read P12.R1.Q2` | The reply that asks it (`P12.R1`). |
89
+ | Entry ID, exact | `/read a1b2c3d4` | The reply with that Pi session entry ID. |
90
+
91
+ Only final replies count (not tool calls or errors). Gentle Agents wake messages are not prompts, so replies
92
+ they trigger stay under the prompt that started them; replies before any prompt are `P0`. An ID that matches
93
+ nothing says `No reply matches "<id>".`
94
+
95
+ ### Markdown files
96
+
97
+ An argument ending in `.md` or `.markdown` (any case) is a file, not a reply ID: `/read notes.md`,
98
+ `/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
100
+ footer as a reply.
101
+
102
+ - A missing or unreadable file gets one warning naming the path as you typed it, such as
103
+ `Cannot read "notes.md": file not found.`, and nothing plays (and no voice download is offered).
104
+ - A file with nothing to read says `notes.md has nothing to read.`
105
+
106
+ ### Reading one section
107
+
108
+ Add `#section` to read only one section: `/read README.md#install`, `/read P3.R1#usage`, or `/read #usage`
109
+ for the latest reply. It reads from the first matching heading up to the next heading of the same or a
110
+ higher level, subsections included. Add `rest` to keep reading to the end: `/read README.md#install rest`.
111
+ Matching ignores case, accents, punctuation and leading numbers like `2.`, and you can write spaces as `-`
112
+ (`#one-reading-per-machine`). An exact heading wins over one that only starts with your text, which counts
113
+ only if exactly one heading starts with it. If no heading matches you get `No section "<section>" in <name>.`
114
+ and nothing plays. Only `#` headings count.
115
+
116
+ ### Auto-read
117
+
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.
123
+
124
+ ### pi-reply-thread
125
+
126
+ Once [`pi-reply-thread`](https://github.com/daniel2010001/pi-reply-thread) supports it, `s` in its Alt+R view
127
+ reads the selected reply (Replies tab and the reply viewer) or only the selected question (Pending and
128
+ Answered tabs). The key and its hint appear only when this reader is loaded. A reading started there is the
129
+ 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.
131
+
132
+ #### Event contract for other extensions
133
+
134
+ Any extension can use the reader over Pi's shared event bus (`pi.events`). Contract v1:
135
+
136
+ | Channel | Payload | Meaning |
137
+ |---|---|---|
138
+ | `reply-reader:ping` | `{ v: 1 }` | Is a reader there? Answered with `reply-reader:ready` synchronously, before your `emit` returns. |
139
+ | `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.` |
141
+
142
+ ```ts
143
+ let readerReady = false;
144
+ pi.events.on("reply-reader:ready", () => (readerReady = true));
145
+ pi.events.emit("reply-reader:ping", { v: 1 }); // readerReady is already set here when the reader is loaded
146
+ if (readerReady) pi.events.emit("reply-reader:read", { v: 1, id: "P12.R1", text: "## Hello\n\nRead **this**." });
147
+ ```
148
+
149
+ A payload that is not an object with `v: 1` and non-empty string `id` and `text` is ignored silently. There
150
+ is no reply to a read request: messages such as a cancelled download are shown by the reader, in the session.
151
+ The reader listens only while a session is running; after the session ends it ignores both requests.
152
+
153
+ ### Standalone command
154
+
155
+ `reply-reader <file.md>` reads a Markdown file aloud from a terminal, without Pi, with the same cleanup,
156
+ voice, saved speed, outputs and one-reading-per-machine rule as `/read`. `-` reads standard input
157
+ (`cat notes.md | reply-reader -`).
158
+
159
+ | Option | Effect |
160
+ |---|---|
161
+ | `--output <name>` | where it sounds: `local` (default) or a name from `outputs.json` |
162
+ | `--speed <n>` | voice speed from 0.5 to 2.0 for this run only; settings.json is not changed |
163
+ | `--voice male\|female` | the voice (default male) |
164
+ | `-h`, `--help` | usage |
165
+
166
+ If the voice is missing, the command asks `[y/N]` before downloading it. Without a terminal, or when reading
167
+ standard input, it exits with an error instead of downloading. Ctrl+C, `kill` or closing the terminal stops
168
+ the reading. A new `/read` or `/read-stop` in any Pi session stops a command reading, and the command stops a
169
+ Pi reading.
170
+
171
+ Exit codes: 0 read (or nothing to read, or stopped by another reading), 1 cannot read, download or play,
172
+ 2 bad arguments, 129/130/143 stopped by SIGHUP, Ctrl+C or SIGTERM.
173
+
174
+ `pi install` does not put the command on your `PATH`. Install it with npm:
175
+
176
+ ```sh
177
+ npm i -g pi-reply-reader
178
+ ```
179
+
180
+ The installed command is compiled JavaScript (Node does not run TypeScript inside `node_modules`), and it does
181
+ not install Pi. From a checkout, build it and link it instead:
182
+
183
+ ```sh
184
+ pnpm install && pnpm build && pnpm link --global # or npm link instead of pnpm link --global
185
+ ```
186
+
187
+ or link `bin/reply-reader.ts` into a folder on your `PATH`; Node runs that file directly, without a build.
188
+
189
+ ### Speed
190
+
191
+ The voice reads at speed 1.1 by default (1.0 is Supertonic's own pace). `/read-speed 1.15` sets any speed
192
+ from 0.5 to 2.0, and a comma decimal or no leading zero works too (`/read-speed 1,15`, `/read-speed .9`); it
193
+ confirms with `Readings will use speed 1.15.` `/read-speed` alone offers 0.8, 0.9, 1.0, 1.1, 1.2, 1.3 and 1.5. Anything
194
+ else says `Speed must be a number from 0.5 to 2.0.` and changes nothing.
195
+
196
+ - The choice is saved in `$XDG_CONFIG_HOME/pi-reply-reader/settings.json` (`~/.config/…` when
197
+ `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.
199
+ - Only the voice speed changes; the pauses between sentences, lines and sections stay the same.
200
+ - No file means 1.1. An invalid file, or a speed outside 0.5 to 2.0, is ignored with one warning per
201
+ session, and readings use 1.1. `/read-speed` does not overwrite a file that is not valid JSON.
202
+ - If the file cannot be saved, the speed still applies to this session and a warning says it was not saved.
203
+
204
+ ## How replies are cleaned for listening
205
+
206
+ The cleanup is deterministic and needs no model, so the same reply always sounds the same.
207
+
208
+ The reader detects whether a reply or file is English or Spanish from its own words (no model; Spanish
209
+ wins ties), and every word the cleanup adds follows it. `/reload` reads as "the command reload" in English
210
+ text and "el comando reload" in Spanish; likewise "Code block." / "Bloque de código.", "AGENTS dot md, in
211
+ agent", "the branch origin main", "a commit", ", line 42", "1 point 1", "approximately", "seconds",
212
+ "percent", and marks by name ("period", "comma", "tilde"…). A token followed by its own noun is not doubled
213
+ ("the `/read` command" reads "the read command"). The voice itself still speaks with Spanish pronunciation.
214
+
215
+ - **Markdown**: emphasis, headings, bullets, numbered items, blockquotes, links and rules lose their syntax
216
+ and keep their words. Headings and list items end as sentences. Inline code is read without backticks.
217
+ A heading or a line that is all bold is read like a title, followed by a longer pause. A numbered item or
218
+ heading reads its number as "1:" so the voice does not stop after it, and the closing
219
+ "Needs your decision" heading is read as "Decisiones pendientes".
220
+ - **Tables**: each row is read as one sentence, cells separated by commas.
221
+ - **Code blocks** are announced, not read: `Bloque de código.`
222
+ - **URLs** are read as their host name (`github.com`).
223
+ - **Reply IDs**: `P11.R1.Q1` is read as "P 11, R 1, Q 1".
224
+ - **Symbols** become words: `→` "a", `←` "desde", `≈` "aproximadamente", `≠` "distinto de", `≥` "mayor o igual
225
+ a", `≤` "menor o igual a", `±` "más o menos", `&` "y", and `×` between numbers "por". Emoji are dropped.
226
+ - **Numbers**: `~` before a number reads "aproximadamente", and units after a number are spelled out (`1,2 s`
227
+ "1,2 segundos", `ms`, `min`, `KB`/`MB`/`GB`, `%` "por ciento", `dB`/`dBFS` "decibeles"), singular after 1.
228
+ Inline code holding a single punctuation mark reads its name: `` `.` `` "punto", `` `;` `` "punto y coma".
229
+ Numbers with dots read "punto": `1.1` is "1 punto 1", `0.8.0` "0 punto 8 punto 0", and a numbered heading
230
+ `## 5.2. Título` reads "5 punto 2: Título". Spanish thousands (`2.750`, `1.500.000`), IP addresses, reply
231
+ IDs, URLs, file names and paths keep their own reading, and a number ending a sentence keeps its period.
232
+ - **Technical names** are read by kind (`snake_case` loses its `_` everywhere):
233
+ - 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";
235
+ - a path with a line: `src/speech-text.ts:42` becomes "speech text punto ts, en src, línea 42";
236
+ - a file name: `README.md` becomes "README punto md";
237
+ - a branch: `origin/main` becomes "la rama origin main" (after "rama", only the name);
238
+ - a command: `/reload` becomes "el comando reload" ("del `/reload`" becomes "del comando reload"), while
239
+ system folders such as `/tmp` read as "la carpeta tmp";
240
+ - 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.
244
+
245
+ ### Known limits
246
+
247
+ - Kinds are guessed from the text alone, so some names are misread: two-word paths such as `odd/tasks`
248
+ 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
250
+ read as file names (`org.bluez` becomes "org punto bluez").
251
+ - The voice speaks with Spanish pronunciation, also for English text (only the words the cleanup adds
252
+ switch to English there).
253
+
254
+ ## Outputs
255
+
256
+ An output is where a reading sounds. `local` is always there: this machine's default sink. You add others
257
+ in `$XDG_CONFIG_HOME/pi-reply-reader/outputs.json` (`~/.config/pi-reply-reader/outputs.json` when
258
+ `XDG_CONFIG_HOME` is unset), an object that maps each name to a `PULSE_SERVER` value:
259
+
260
+ ```json
261
+ { "desktop": "tcp:127.0.0.1:4714" }
262
+ ```
263
+
264
+ - Names use letters, digits and `-`, and `local` is built in, so it cannot be redefined.
265
+ - Each value must be a non-empty string.
266
+ - The first `/read` of a session asks `Where should readings sound?` when there is more than one output;
267
+ `/read-output` switches later, and completes the names.
268
+ - An entry that breaks a rule is skipped with a warning such as
269
+ `Ignored output "my out" in …/outputs.json: names use letters, digits and "-".` A file that is not valid
270
+ JSON is ignored as a whole (`Ignored …/outputs.json: not valid JSON (…)`). The warning shows on the first
271
+ `/read` of a session and on every `/read-output`, so a typo never sends a reading somewhere else
272
+ silently.
273
+
274
+ Outside the interactive TUI nothing can be asked: with more than one output, pick one first with
275
+ `/read-output <name>`, or the reading is cancelled (`Reading cancelled: no output chosen.`).
276
+
277
+ ## Hear it on another machine over SSH
278
+
279
+ A common setup: Pi runs on a server, and you sit at a desktop connected to it over SSH. The reading is
280
+ synthesized on the server, so its audio has to reach the desktop's speakers.
281
+
282
+ **Why not open a PulseAudio TCP port on the desktop?** pipewire-pulse has no IP allow-list. A LAN port would
283
+ let anyone on the network play sound on the desktop or record its microphone, unless a firewall closes it.
284
+
285
+ **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).
289
+
290
+ 1. On the server, edit the copy for your desktop: `AUDIO_HOST` (the desktop's address), `AUDIO_UID` (your
291
+ user ID on the desktop, `id -u`) and the user in `you@${AUDIO_HOST}`. The server must reach the
292
+ desktop with `ssh` and a key, without a password prompt (`BatchMode=yes`).
293
+ 2. Install it (on the machine that runs Pi):
294
+
295
+ ```sh
296
+ cp examples/reply-reader-desktop-audio.service ~/.config/systemd/user/
297
+ systemctl --user daemon-reload && systemctl --user enable --now reply-reader-desktop-audio.service
298
+ ```
299
+
300
+ 3. Name the output in `~/.config/pi-reply-reader/outputs.json`:
301
+
302
+ ```json
303
+ { "desktop": "tcp:127.0.0.1:4714" }
304
+ ```
305
+
306
+ 4. Verify (prints the desktop's host name; plays nothing):
307
+
308
+ ```sh
309
+ PULSE_SERVER=tcp:127.0.0.1:4714 pactl info | grep 'Host Name'
310
+ ```
311
+
312
+ 5. In Pi, `/read-output desktop`, then `/read`.
313
+
314
+ 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
316
+ server, enable lingering for your user there (`loginctl enable-linger`).
317
+
318
+ The desktop needs only PipeWire (with pipewire-pulse) or PulseAudio and an SSH server. It needs no TTS, no
319
+ Pi and no change to its configuration. A new client is one more unit and one more entry in `outputs.json`.
320
+
321
+ ## Requirements
322
+
323
+ - **`paplay`**, on the machine that runs Pi. It comes with `libpulse` on Arch and `pulseaudio-utils` on
324
+ Debian and Ubuntu. Without it, `/read` says `Cannot play: paplay was not found on PATH …`.
325
+ - **`tar` with bzip2 support**, for the one-time voice download.
326
+ - **Node.js >= 22.19.**
327
+ - **A CPU is enough.** No GPU is used. The engine is
328
+ [sherpa-onnx-node](https://github.com/k2-fsa/sherpa-onnx) 2.0.1 (installed with the package).
329
+
330
+ ## Develop
331
+
332
+ ```sh
333
+ pnpm install
334
+ pnpm test
335
+ pnpm typecheck
336
+ pnpm build # compiles the reply-reader command into dist/ (also run by npm pack)
337
+ ```
338
+
339
+ ## License
340
+
341
+ MIT for this package.
342
+
343
+ The voice is downloaded separately and has its own licenses:
344
+
345
+ - Supertonic 3 weights: OpenRAIL-M, see
346
+ [Supertone/supertonic-3](https://huggingface.co/Supertone/supertonic-3/blob/main/LICENSE).
347
+ - Supertonic code: MIT, see [supertone-inc/supertonic](https://github.com/supertone-inc/supertonic).
348
+ - sherpa-onnx, which runs it: [Apache-2.0](https://github.com/k2-fsa/sherpa-onnx/blob/master/LICENSE).
@@ -0,0 +1,49 @@
1
+ #!/usr/bin/env node
2
+ // `reply-reader <file.md>`: reads a Markdown file aloud from a terminal, without Pi (S6). The installed
3
+ // command runs the compiled dist/bin/reply-reader.js (`npm run build`, run before packing), since Node does not strip
4
+ // types under node_modules; from a checkout this file also runs directly with Node's type stripping.
5
+ import { createInterface } from "node:readline";
6
+ import { main } from "../src/cli.js";
7
+ const interrupt = new AbortController();
8
+ // Ctrl+C, kill or a closed terminal stops the reading (or the download) instead of leaving the player playing;
9
+ // the exit code is 128 plus the signal number, as a shell reports it.
10
+ const SIGNAL_CODES = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };
11
+ let caught;
12
+ for (const signal of Object.keys(SIGNAL_CODES)) {
13
+ process.on(signal, () => {
14
+ caught ??= signal;
15
+ interrupt.abort();
16
+ });
17
+ }
18
+ /** The y/N download question on the terminal; anything but y or yes is no, and Ctrl+C at the prompt interrupts. */
19
+ function confirm(message) {
20
+ return new Promise((done) => {
21
+ const prompt = createInterface({ input: process.stdin, output: process.stderr });
22
+ let answered = false;
23
+ const finish = (yes) => {
24
+ if (answered)
25
+ return;
26
+ answered = true;
27
+ prompt.close();
28
+ done(yes);
29
+ };
30
+ prompt.on("SIGINT", () => {
31
+ interrupt.abort();
32
+ finish(false);
33
+ });
34
+ prompt.on("close", () => finish(false));
35
+ prompt.question(`${message} [y/N] `, (answer) => finish(/^y(es)?$/i.test(answer.trim())));
36
+ });
37
+ }
38
+ const code = await main(process.argv.slice(2), {
39
+ env: process.env,
40
+ stdin: process.stdin,
41
+ stdout: process.stdout,
42
+ stderr: process.stderr,
43
+ isTTY: Boolean(process.stdin.isTTY && process.stderr.isTTY),
44
+ confirm,
45
+ signal: interrupt.signal,
46
+ });
47
+ process.exitCode = caught && code === SIGNAL_CODES.SIGINT ? SIGNAL_CODES[caught] : code;
48
+ // Nothing else is left to do; a native engine thread must not keep the command alive after the reading.
49
+ process.exit();