Zotero-OpenReader

Text-to-speech for Zotero 10: more voices, word-and-sentence highlighting in your colors, keyboard shortcuts.

English · 简体中文

If you like Zotero-OpenReader, give it a ⭐ on GitHub — it helps others find it.

What it adds

Zotero-OpenReader adds voices and a player to Zotero 10: each provider is an entry of the player's first dropdown, and Zotero's own Standard and Premium are two more, each behind a switch of its own. It is built for the way its author reads — why, and where it is going.

• 🗣️ More voices in the Read Aloud player, one entry per provider — Fish Audio (free, and the one to start with), Azure Speech, Cloudflare Workers AI, Speechify, a Kokoro-FastAPI or a Fish Speech server on your machine, OpenAI, Xiaomi MiMo or any OpenAI-compatible server — with Zotero's own Standard and Premium beside them, each behind a switch. → Providers
• 🎛️ A player in three layouts — a bottom bar, a top bar below the toolbar, or a floating panel. Change layout without interrupting playback. → Player
• 🔖 Resume where you stopped — close a document, open it again later, press Shift+Space, and Read Aloud starts at the sentence you left off on. → Resume where you stopped
• 📄 The whole sentence on screen — while a PDF is read, a sentence that runs past the bottom of the window, onto the next page or into the next column is scrolled into view instead of left cut, and Shift+Enter brings it back the same way. → Reading
• 📃 No line lost at a page turn — when a sentence runs onto the next page and Zotero would skip that page's first line, the line is read and highlighted like any other. → Reading
• 🧵 No sentence cut in two — when Zotero breaks a paragraph in the middle of a sentence, the halves are read and highlighted as one sentence. → Reading
• 🎧 A voice browser in the settings: every voice by provider and language, a play button for a short sample, hearts for favorites, and a switch to offer only the favorites. → Voice browser
• ✨ Word and sentence highlighting, each behind a switch of its own, in your own colors and opacities — for Zotero's voices too. → Highlight
• ⌨️ Keyboard shortcuts for speed, volume, skipping by sentence or paragraph, reading from the selection, the player's options panel, auto-scroll mode, the word highlight on or off, highlighting or underlining the sentence being read, and stopping Read Aloud in every tab at once. All rebindable. → Shortcuts
• 📌 One voice and speed everywhere — every document and every open tab, instead of Zotero's choice per language. → Reading
• ⏱️ The pauses are yours — how long every voice waits between sentences and before a paragraph, shorter as you read faster. → Reading
• 💾 Backup and sync — settings and reading positions as files, or through your own WebDAV folder, so your settings and bookmarks follow you between computers. → Backup and sync
• 🔄 Sync with OpenReader — your reading position moves between Zotero on your computer and the OpenReader app on your iPhone, through your own WebDAV folder. → Backup and sync
• 🖥️ Windows and macOS voices, spoken by the plugin — the ones Read Aloud already lists, but with samples, favorites, the cache and, on Windows, word-by-word highlighting. → Providers

Install

1. Download the .xpi file from the latest release — in Firefox, right-click → Save Link As…
2. Tools → Plugins → ⚙ → Install Plugin From File…, then restart Zotero. Inside Zotero the plugin is named OpenReader.
3. Enable a provider in Edit → Settings → OpenReader — Fish Audio first, if you are not sure (why) — then pick it in the player's first dropdown and one of its voices.

Providers

Start with Fish Audio. Of everything below, it is the one to try first:

• Free. Its free model reads as much as you like, with nothing to pay and no balance to keep on the account.
• A key without a credit card. Sign up at fish.audio, create the key, paste it in — no card, no billing details.
• 83 languages, with word-by-word highlighting.
• The best-sounding voices here — Fish Audio's own, the ones its users published, and any you clone from a recording of your own.

→ Setting it up

The player's first dropdown lists every enabled provider that has voices right now, and Zotero's own Zotero Standard and Zotero Premium while their switches are on, sorted by name.

• The entries are Azure, Cloudflare, Fish Audio, Fish Speech, Kokoro, OpenAI, OpenAI Compatible, Speechify, System, Xiaomi MiMo, Zotero Premium and Zotero Standard; the voices under them carry their own names.
• Each entry remembers its own last voice per language: Kokoro → Fish → Kokoro brings the Kokoro voice back.
• A provider with nothing to offer — switched off, its server down, no favorite of its own while only favorites are offered — is not listed until it has voices again.
• Without a Zotero account every other provider still works; only Zotero Standard and Zotero Premium are left out, as in Zotero itself.
• When the entry you are on stops offering voices, the player moves to the provider of the remembered voice, else of the default voice, else to the first entry.
• Switching provider or language while paused takes effect at once; press play and the sentence starts over in the new voice. A voice picked while paused waits for play and carries on from the paused word.
• Zotero's own first-run window and its Manage voices window keep filing every plugin voice under Local.
• Enable, at the end of every provider section, runs the connection check first: a provider that does not answer never switches on.
• Zotero's own Standard and Premium have a switch each in the Zotero Read Aloud section, both on to begin with. Switch one off and that tier leaves the player's first dropdown, the voice browser and the language list; nothing Zotero remembers is lost, and switching it back on brings its last voice back. They need a Zotero account: signed out, their Enable is greyed, with the reason and a Log in link beside it; signed in, Enable checks that Zotero lists voices in that tier, and Test connection reports the voices.
• Remaining time: under each tier's name, how long your Zotero account's credits for it will read, as zotero.org counts it. Premium voices cost 10 or 30 credits a minute, so Premium shows a range: Remaining time: 9min – 26min, depending on voice. 0min is red. An Add more time link to zotero.org appears once the dearest voice has under 3 minutes.
• Enable keeps a tier off while its time is 0: add more time first.
• Test connection probes without switching anything on.
• While a provider is on its fields are locked — Disable to edit them.
• Keys, gateway headers and the WebDAV password are covered by dots. The eye beside a field uncovers it, so the value can be read, selected and copied; a provider that is on keeps its own covered.
• Where they are kept: like every plugin setting, in Zotero's preferences in plain text, and in the settings backup file.

Resume where you stopped

Close a document in the middle of listening, quit Zotero, come back days later, press Shift+Space — Read Aloud goes on from the sentence you stopped at. Zotero on its own does not keep that place; the plugin keeps it for every document you have listened to.

• Reading resumes at the start of that sentence, never half way into it.
• Nothing is drawn in the document and nothing is added to your annotations.
• A document you have never listened to starts from the page you are looking at.
• Positions stay on this computer until you switch on Sync reading positions between computers (Backup and sync); then they follow you: stop on one, press Shift+Space on another, and reading continues at that sentence.

Settings

Player

• The player is the plugin's in every document; Zotero's original player no longer appears. Click the red headphones icon in the reader to open it and start reading; click again to stop and close it. Where the player cannot load, a message says so and nothing is read: turn OpenReader off under Tools → Plugins to read with Zotero's own player meanwhile.
• Bottom bar, Top bar, Floating panel are available in Settings and from the player's layout button. A bar lies over the top or bottom edge of the document, so opening, closing or switching the player never resizes or blurs the page; following keeps the sentence being read out from under it, and Zotero's find bar opens below the top bar. The strip under a bar stays covered at the very start or end of a document. The floating panel can be dragged. The top bar is the default when no layout has been saved; existing choices are kept.
• Provider, language, voice, speed and volume use the same choices as the voice browser and keyboard shortcuts. Hearts on the left mark the same favorites as Settings.
• Floating controls include four sentence/paragraph skip buttons around Play/Pause. Options at the upper left, or Shift+O, hides or shows the provider, language and voice rows; Layout is at the upper right. Each opening follows Open the player expanded in Reading settings.
• Floating menus open below their button when they fit, above otherwise. If neither side fits, the larger side gets a shorter, scrollable menu. Language and voice search boxes stay visible while choices scroll in all three layouts.
• Estimated remaining reading time appears in every layout, enabled by default under Reading settings. One compact line shows the document and the time to the next contents heading, including nested headings. It sits above the speed controls in Floating and after volume in Top and Bottom. Starting at selected text still counts to the end of the document. Times wait for enough ordinary reading audio before appearing. During normal reading they hold or decrease gradually; manual pauses and network waits do not count down. Changing voice, speed or reading position starts a new estimate. Sections without reliable boundaries are omitted.
• Speed controls in the player, Settings and keyboard shortcuts change by 0.05×, within the existing 0.5×–3× range.
• A / M controls following in this document. A follows the narration; M leaves scrolling to you. Scrolling by hand or clicking A enters M. Later sentences, pause/resume and stopping/restarting do not restore A.
• Click M or press Shift+M to return to the spoken sentence and follow again. Shift+M switches both ways, like the player control. Shift+Enter returns and switches to A; Shift+R returns once without changing A/M. Skipping in M changes what is read without moving the page. These controls do not start paused audio. Each open document keeps its choice; closing and reopening uses the default from settings.
• Theme and controls follow the reader's appearance. Loading and playback errors appear in the player; an error can be opened for details and a retry.
• A Zotero voice's remaining time sits at the right of the voice button, and beside each Zotero voice in the voice list; it turns red under 3 minutes.
• When a Zotero tier's time runs out, or it reaches Zotero's daily limit, the tier is switched off: every player reading with it closes, in every tab, and a reminder over the document says so — with an Add more time link when time ran out. Enable it again in the settings once you have more time, or the next day. If Zotero refuses a dear voice while some time is left, nothing is switched off: the reminder suggests a cheaper voice.

Everything is under Edit → Settings → OpenReader.

Highlight

• Sentence and Word are two switches, both on to begin with: the word being spoken in its color, its sentence in the sentence color under it. One off leaves only the other; the last one on cannot be turned off.
• A color and an opacity for each — for Zotero's own voices too. The default is a blue word on a yellow sentence, both at 70 %; Restore default colors brings it all back, the switches included.
• The preview is painted in your reader's theme.
• Zotero's own Highlight current setting (Settings → General → Read Aloud) follows this choice and is greyed out while Zotero-OpenReader is installed; there is no paragraph level.
• A voice without word timing highlights the sentence whatever the switches say.
• The word lights up when it is heard: on wireless headphones it waits for the sound, and it stays where it is while the sound stalls.

Keyboard shortcuts

Shift+Space is the only key you need — one key, whatever the reader is doing:

• Text selected: reading starts there.

• Nothing selected, a document you have listened to before: reading picks up at the sentence you stopped on.

• Nothing selected, a document you have never listened to: reading starts from the page you are looking at.

• Read Aloud already playing: it pauses; pressed again it goes on from the same sentence — or from the selection, if you made one while it was paused.

• Waiting for playback shows “Preparing…” until audio starts, including when resuming or moving to another sentence. Fast starts and configured sentence pauses do not flash a notice. A voice-switching notice takes priority while a new voice is being prepared.

• Player layout — Shift+P cycles Top bar → Bottom bar → Floating panel while the player is open, playing or paused. All players share the layout, and it is remembered after restart. Holding the key switches only once; typing in a text field leaves the layout alone.

• Faster / slower — Shift+C / Shift+X support holding the key to repeat at your system's keyboard rate, in 0.05× steps within 0.5×–3×.

• Return and follow — Shift+Enter goes to the reading position and switches to auto-scroll. Return once — Shift+R goes there without changing A/M. Both work while reading or paused.

• Switch A/M — Shift+M switches the current document's following while the player is open. Switching to A also locates the current sentence; paused audio stays paused. Scroll style — Shift+A cycles through scrolling at every line, at every sentence and when outside the view, without changing A/M.

• Custom keys — record another binding, clear it, or restore defaults in Keyboard shortcuts. Held speed changes also work with custom keys.

Shift+S stops Read Aloud everywhere — every tab's player closes at once, a short message says how many, and each tab keeps its place for the next time. While no player is open the key keeps its usual meaning.

Shift+W turns the word highlight on and off without leaving the document — the Word switch of the Highlight section. It takes effect on the sentence being spoken, in every tab, and stays until you change it again; a short message says what is highlighted now. Turning it off never leaves the page bare: the sentence comes on. A voice without word timing keeps highlighting the sentence either way, and the message says so.

Shift+H / Shift+U highlight or underline the sentence being read, playing or paused, as an annotation of the document, with its popup open for a comment. Early in a sentence, the one just finished is annotated instead. With no reading open the keys keep their usual meaning.

• Previous / next voice — Shift+, / Shift+. cycle through the player's current voice list, wrapping at either end. Choosing a voice, language or voice mode in the player uses the same switching behavior.
• While playing, the old voice reads on only with the audio it already has, and asks your provider for nothing more. The new voice takes over at a word boundary or between sentences once it is ready; where the old voice runs out first, the reading waits for the new one. A short message names the voice.
• While paused, the new voice prepares silently. Press Play to continue with it after the paused word if it is ready; otherwise the old voice resumes until the new one is ready. Without reliable word alignment, the old voice finishes the sentence before switching.
• Skipping, or starting somewhere else (Shift+Space on a selection), keeps the switch. The sentence you land on is read in the new voice if its audio is ready, in the old voice if it already has that sentence, and otherwise after a short wait for the new voice.
• While a voice is preparing, another selection cancels the previous request and only the latest choice takes effect. A failed preparation keeps the original voice, which reads on, and shows a message. Changing speed or closing the player cancels the pending switch. Preparation may use your provider's quota even if you change your mind.

Voice browser

Every voice Read Aloud can use, in the player's own three steps — provider (or Zotero's Standard / Premium), language, voice.

• ▶ plays a short sample, ♥ marks a favorite.
• A click on a row sets the global default voice. Each document copies it on first open, then keeps its own voice. Changing the voice in the player affects only that document.
• Speed is the player's own slider (0.5×–3×); Volume is how loud Read Aloud plays, 100% being Zotero's own level.

Reading

Scrolling

Backup and sync

WebDAV — one folder of your own, used by the sync and by the server backup below.

• Enter the folder's address, your user name and password, and press Enable: it checks the connection first, and the sync and the server backup use the folder only while it is on.
• While the folder is on its fields are locked — Disable to edit them. While it is off, the sync and the server backup below are greyed and do nothing; their switches keep their ticks for when it is back on.
• Test connection probes without switching anything on.
• An http:// address is not encrypted: the password and the settings sent there, API keys included, can be read on the way. Enable and Test connection say so every time, and the folder still works.

Sync — what follows you between computers on its own, both ways.

• Sync reading positions between computers: stop listening on one computer, press Shift+Space on another, and reading goes on from that sentence. Every computer sharing the folder and the same library stays in step, and turning it on loses no bookmark, whichever computer it came from. On by default.
• The OpenReader app on your iPhone: with the app set to the same WebDAV folder, OpenReader shares the same reading positions, both ways, while Sync reading positions between computers is on.
• Sync settings between computers: a change on one computer reaches the others within seconds, and theirs reach it, with nothing to restore. Off by default.
• What stays on each computer: a voice server at a local or home-network address, the System voices switch, and the WebDAV folder itself, whether it is on included.
• Two computers change the same setting: the later change wins.
• A provider the sync brings a change to, but that cannot work on that computer, stays off there and says why.

Backup — one-way copies, restored by hand.

• Backup settings… and Restore settings… keep every setting as one file; Export reading positions… and Import reading positions… carry the bookmarks as another. Restoring settings replaces them all; importing positions only takes the newer ones.
• Keep a backup of this computer's settings on the server refreshes this computer's own copy in the WebDAV folder a few seconds after any change; Back up to the server now writes it by hand, and Restore settings from server… brings any computer's copy back. A backup, not the sync: nothing changes anywhere until you restore it.
• A provider, or the WebDAV folder, that cannot work on the computer you restore to stays off and says why.
• Restoring a backup counts as changing every setting in it, so with the sync on it reaches your other computers too.

Troubleshooting

Compatibility

• Zotero 10 on the desktop, any 10.x build, source builds included. In use on Windows and macOS; Linux should be the same, but is untested.

Development

npm install
npm test          # vitest, also builds build/Zotero-OpenReader.xpi
npm run typecheck
npm run build

notes/NOTES.md records the Zotero internals the plugin relies on and every incident so far.

Acknowledgments

• Developed with the help of introfini/mcp-server-zotero-dev, the MCP bridge that drives Zotero from the outside.

License

AGPL-3.0, the same license as Zotero itself. Not affiliated with Zotero.

Contributions are accepted on the terms in CONTRIBUTING.md, which also let the author ship them in his OpenReader app for phones and tablets.

Buy me a coffee