Univocal Read Aloud

Read notes aloud with Univocal and highlight each word as it's spoken, in reading view and in Live Preview or source mode.

Public beta · macOS desktop only. Requires a Connect-capable build of the Univocal app. The plugin is free; continued use of Univocal after its trial requires a paid Univocal licence. No plugin account is required.

The plugin is available in Obsidian Community plugins.

Install

Community plugins (recommended):

1. Open the Univocal Read Aloud listing and choose Add to Obsidian.
2. Install and enable Univocal Read Aloud in the vault you want to use.
3. In Univocal, open Settings → Connections → Obsidian → Set up and click Connect. You're connected, with no approval card. If you start with Read aloud in Obsidian instead, Univocal shows one approval card the first time.

Manual installation: download main.js, manifest.json and styles.css from the latest release, copy them into <your vault>/.obsidian/plugins/univocal-read-aloud/, reload the Community plugins list, and enable the plugin.

Usage

• Connect without starting a reading: install and enable the plugin in your vault. In Univocal, open Settings → Connections → Obsidian → Set up and click Connect. You're connected, with no approval card.
• After revoking access: reconnect from Univocal's Settings → Connections → Obsidian by clicking Connect. If the plugin shows Not allowed in the status bar, click it to open Univocal.
• Read aloud: use the command palette (Univocal Read Aloud: Read aloud) or the ribbon icon. Reading starts at the selection, or at the first visible paragraph. If you haven't connected through Univocal's Settings, Univocal shows one approval card the first time. The command has no default hotkey; set your own under Settings → Hotkeys.
• While reading, Univocal's floating pill is the control: pause and resume, skip sentences, change speed or voice, and stop there. Univocal's ⌥⇧R also toggles pause/resume. Read aloud and the ribbon icon do nothing while a reading is under way, and the status bar just shows Reading aloud… or Reading paused.
• The spoken word and sentence are highlighted. Switching notes stops reading. Editing the note restarts reading at the sentence you were on (if you edit while paused, the restart happens when you resume in Univocal).
• The status bar also says when Univocal is missing (Get Univocal), not running (Univocal off, click to start it), waiting for your approval, or not allowed.

Univocal's read hotkey

Univocal has its own global hotkey (⌥⇧R by default). With this plugin enabled, pressing it while Obsidian is in front reads the focused note in Obsidian, with highlighting, instead of reading the selection in Univocal's panel. Pressing it again toggles pause/resume.

• This works once you've allowed Obsidian in Univocal (reading aloud once is enough). After that the plugin connects quietly whenever Obsidian and Univocal are both running. It never launches Univocal or prompts you on its own.
• With two vaults open, the vault whose window has focus answers.
• To keep Univocal's own behaviour, turn off Answer Univocal's read hotkey in the plugin settings.

Privacy

• Note text goes only to Univocal on this Mac, over a local Unix socket. Nothing is sent over the network by this plugin.
• From plugin version 0.1.3, Univocal's grant for Obsidian (a token) is stored at ~/Library/Application Support/obsidian-univocal/tokens.json, outside your vault. Only your macOS user can read the file (0600, in a 0700 folder). It is not synced with your notes. The plugin no longer uses the macOS Keychain. Settings → Forget authorization removes the stored token.
• The plugin reads Univocal's local connection-discovery files outside the vault to find its Unix socket. It uses Launch Services to locate or start Univocal when you ask it to read, or to open Univocal when you click Not allowed in the status bar after a Revoke. It does not install or update the Univocal app.
• No telemetry or analytics are collected. The plugin makes no remote network requests; opening an installation/help link uses your browser.
• The plugin's data.json only holds preferences (highlight style, hotkey routing, developer options).

Settings

Obsidian reads use Univocal's speed and voice, which you can change from Univocal's pill or panel.

Updating and removing

Use Obsidian’s Settings → Community plugins → Check for updates control. For a manual installation, replace the three plugin files with those from a newer GitHub release and reload Obsidian. Preferences remain in data.json. The plugin never installs or updates itself.

To disconnect, use Revoke beside Obsidian in Univocal. To remove the saved credential too, use the plugin’s Forget authorization before uninstalling it through Obsidian’s Community plugins settings.

Development

pnpm install
pnpm dev        # watch build → main.js
pnpm build      # typecheck + production build
pnpm typecheck
pnpm test       # vitest
pnpm lint       # official Obsidian ESLint rules

Testing in a throwaway vault

UNIVOCAL_CONNECT_DIR=/tmp/uco-dev DEVELOPER=1 scripts/dev-install.sh ~/tmp/TestVault

dev-install.sh builds, copies main.js, manifest.json and styles.css into <vault>/.obsidian/plugins/univocal-read-aloud/, adds the id to community-plugins.json, and writes connectDir / developer into the plugin's data.json from the optional env. It refuses any path containing ObsidianSecondBrain or Mobile Documents, so it can never touch a real iCloud vault.

To test against the mock server, point Univocal's connect dir at a short path, because Unix socket paths are limited to 103 bytes:

univocal-mock serve --dir /tmp/uco-dev --consent allow

Developer URL handler

With Developer mode on:

obsidian://univocal-dev?cmd=read[&prefer=selection|document]
obsidian://univocal-dev?cmd=pause        # pause / resume (dev-only, for QA)
obsidian://univocal-dev?cmd=stop         # dev-only, for QA
obsidian://univocal-dev?cmd=status[&tag=…]

pause and stop exist only for automated QA. The plugin has no user-facing pause or stop; users control a reading in Univocal's pill.

status writes univocal-dev-status.json into the connect dir. It holds the state, session id, last word and sentence ranges, painted-range counts (painted.word must never exceed the ranges of one word), the current mode (reading / live-preview / source), the note path and the connection state. It never contains note text. Example: open -g "obsidian://univocal-dev?cmd=status&tag=1".

Layout

• src/connect/: the Univocal Connect protocol client. It's self-contained, with no Obsidian imports.
• src/textmap/, src/highlight/: text extraction and offset mapping, and the word and sentence highlighters.
• src/controller.ts: the read-aloud state machine. It's Obsidian-free and tested with fakes in test/controller/.
• src/main.ts, src/settings.ts, src/statusBar.ts, src/devProtocol.ts: the plugin shell.

Review and security

See SECURITY.md for native capability scope and the remaining generic CSS compatibility notices. See CONTRIBUTING.md for verification and release requirements.

License

MIT © 2026 NarNar Labs