Read Aloud

Listen to your Obsidian notes, sentence by sentence.
A natural Piper voice that runs on your own computer, with a soft highlight on the sentence being read. For Windows, macOS and Linux.

Read Aloud reads the current note aloud with a Piper voice, sentence by sentence, and highlights the sentence being read, in the editor and in reading view. Nothing leaves the computer while reading. The speaking is done by the Piper built into calibre (8.8 or newer), which installs the same way on every system; voices in 58 languages are downloaded from the plugin's settings.

Setting it up, step by step for each system, and using it: see HELP.md. The same guide opens inside Obsidian with the Help command and from the settings page.

Good to know

Read Aloud needs a few things outside the vault, as Obsidian asks plugins to disclose:

• An external program: calibre (free, open source) must be installed. Read Aloud starts calibre's calibre-debug in the background to run the speech engine, and stops it after 10 idle minutes.
• Network use: only when you click Download in the settings, to fetch the chosen voice from huggingface.co/rhasspy/piper-voices (the address comes from calibre's own list). Reading itself works offline; your notes are never sent anywhere. No telemetry.
• Files outside the vault: voices are read from and downloaded into calibre's voices folder (or the folder set in the settings). With calibre from Flathub, a small helper script is written into calibre's own folder under ~/.var/app; otherwise it lives in the plugin's folder.
• Desktop only, as it runs a program; it does not work on phones or tablets.

How it works

• The note is cut into sentences, each knowing its block (paragraph, heading, list item, table row); a sentence longer than 300 characters (adjustable) is cut at commas. Front matter, code blocks, math, comments, embeds and link targets are skipped; Markdown syntax is not spoken.
• calibre-debug is found in its usual place on each system (src/calibre.ts), including calibre from Flathub.
• A small speech server (src/piper_server.py) runs inside calibre's Python and keeps the voice loaded, so only the first start takes a few seconds. Reading starts about half a second after a sentence is sent, and the next sentence is prepared while the current one is read, so there is no gap between them. After 10 minutes with nothing to read, the server stops and frees its memory.
• The sentence being read gets a light accent-colored background, in the editor and (as a CSS custom highlight over the rendered text) in reading view too, and is scrolled into view. You can keep editing the note while it is read: the highlight and the reading position move along with your edits.

Use

• Ribbon icon (speaker): starts reading from the cursor; while reading, it pauses and resumes.
• Right-click in the editor → Read aloud from here.
• Commands (to bind hotkeys to): Read from the cursor, Read note from the start, Pause / resume, Stop reading, Next / Previous sentence, Next / Previous paragraph, Help.
• The status bar shows previous sentence, pause/resume, next sentence and stop buttons while reading.

In reading view, reading starts at the top of the screen.

Settings: calibre's status, voice (with a sample), voice downloads by language, speed, maximum piece length, pause between paragraphs, whether to scroll along, and, optionally, where calibre and the voices are.

Build and install

The plugin, its tests and the install script are written in TypeScript, bundled by esbuild into main.js. Node 22.18 or newer runs the tests and the install script as they are, without compiling them. build.js stays JavaScript, so that Obsidian's review, which rebuilds main.js to compare it with the release, can run it with any Node version.

npm install
npm test                          # type check, Obsidian's lint rules (eslint-plugin-obsidianmd), then the tests
npm run lint                      # only the lint
npm run install-plugin            # build, and copy into every vault open in Obsidian
npm run install-plugin -- ~/path/to/vault

The server tests run the real calibre when it is installed, and are skipped otherwise.

main.js is committed, so the plugin can be installed on any computer by copying main.js, manifest.json and styles.css into <vault>/.obsidian/plugins/read-aloud/, without building it.

Releasing

Bump the version in manifest.json, package.json and versions.json, build, commit, then push a tag named exactly as the version:

git tag -a 1.0.1 -m "What changed"
git push origin 1.0.1

The release workflow builds main.js from the tagged source, checks that it is the committed one, runs the checks, attests where the files came from (GitHub artifact attestations, which anyone can verify with gh attestation verify main.js -R laszlorepassy/obsidian-read-aloud), and publishes the release with main.js, manifest.json and styles.css.

Support

If Read Aloud reads you something worth hearing, you can buy me a coffee:

Bug reports and pull requests are welcome.

License

MIT