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 +57 -0
- package/LICENSE +21 -0
- package/README.md +347 -2
- package/dist/bin/reply-reader.js +49 -0
- package/dist/src/cli.js +202 -0
- package/dist/src/outputs.js +61 -0
- package/dist/src/playback.js +245 -0
- package/dist/src/reading-lock.js +143 -0
- package/dist/src/settings.js +97 -0
- package/dist/src/speech-text.js +511 -0
- package/dist/src/voice.js +173 -0
- package/examples/reply-reader-desktop-audio.service +44 -0
- package/extensions/reply-reader.ts +464 -0
- package/package.json +70 -4
- package/src/cli.ts +225 -0
- package/src/outputs.ts +73 -0
- package/src/playback.ts +292 -0
- package/src/questions.ts +19 -0
- package/src/reader-events.ts +44 -0
- package/src/reading-lock.ts +167 -0
- package/src/replies.ts +64 -0
- package/src/sections.ts +47 -0
- package/src/settings.ts +94 -0
- package/src/sherpa-onnx-node.d.ts +29 -0
- package/src/speech-text.ts +579 -0
- package/src/voice.ts +195 -0
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
|
-
#
|
|
1
|
+
# pi-reply-reader
|
|
2
2
|
|
|
3
|
-
|
|
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();
|