README file from
GithubOrbis Reader
An ebook reader for your Obsidian vault. Read your books, hear them read aloud and annotate them. Make your reading part of your knowledge base, on your terms.

Features
Collect: bring books into your vault
- Open the EPUB, MOBI, AZW3, FB2 and CBZ files you already have.
- Browse, search and download books from Project Gutenberg (built in), your own Calibre server and other OPDS-compatible sources.
- Turn any note, web clipping or folder of notes into a book you can read, annotate and listen to.
Learn more: Book Sources · Format Support · Read in Orbis Reader · Notes to EPUB
Organize: build a library from notes in your vault
- Turn on the library to get a title note in your vault for each book. Title notes show up in search, the graph and Bases, and printed books can have them too.
- Catalog every book in your vault in one pass, with covers.
- Track each book's reading status, your rating and when you finished it.
- Design dashboards that show your title notes as lists, covers or tables, using filters you create.
Learn more: Library Dashboards
Read: make the reader your own
- Combine fonts, reader themes (built-in, matched to Obsidian or your own), spacing and layout into display styles.
- Read in pages, as one scroll or in two columns.
- Hide everything but the book with Focus mode.
- Move around quickly: jump to a chapter, a location or a percentage, go back after a jump, preview footnotes and zoom into images.
- See your progress, the time left and your reading speed.
- Pick up right where you left off in every book.
Learn more: Reading a Book · Display Settings · Reading Progress
Explore: understand as you read
- Select any word or phrase to look it up in offline dictionaries, find it in your vault or search for it on the web.
- Search the book's text and your annotations.
Listen: hear any book read aloud with text-to-speech
- Listen to books with natural-sounding voices that run on your device and work offline, while the text is highlighted as it's read.
- Switch to the full-screen player, change the reading speed, and lock the controls with Pocket mode while your phone is in your pocket.
- Mark a passage, add a note or set a bookmark while you're listening.
- Record a book to MP3, on your device or with your own Kokoro server, for better sound and longer battery life.
- Combine recordings and live voices in a mix, so you can give different parts of a book their own voices.
- Teach voices how to pronounce names and terms.
Learn more: Listening
Annotate: capture what matters to you, and why
- Bookmark your place, mark passages and attach your own notes.
- Give each annotation a mark that says what it means to you, such as Key point, Question or Follow up. Each mark has its own highlighter color, underline or other treatment, and badge.
- Create presets of marks for different kinds of books, such as one for fiction and one for research, and choose which preset each book uses.
Learn more: Marks and Notes · Annotations and Presets
Connect: make your reading part of your knowledge base
- Turn on reading records to get a vault note for every annotation, kept up to date as you read, plus generated Obsidian Bases to sort and filter them.
- Generate vault notes with your annotations or a chapter outline whenever you want, and merge in later changes.
- Link to any passage from any note, and see every note that links to the book.
- Convert a book's text to Markdown that you can search and link to.
Learn more: Reading Records · Generate Notes · Deep Links · Save as Markdown
Share: take your books and annotations anywhere
- Save a book as a PDF with your marks and notes, or save a PDF digest with just your annotations.
- Save a book as Markdown or your notes as an EPUB, to read in other apps or send to others.
Learn more: Exporting and Converting · Save as PDF · Save Annotations as PDF · Save as Markdown · Notes to EPUB
Foundations: your choices, your devices, your data
- Your choices: Turn on only the features you want from the Setup page. Adjust detailed settings and bind any command to a hotkey.
- Every device: Use Orbis on your computer, tablet and phone. It's built for all three, not just the desktop.
- Your sync: Keep using the vault sync you already have, such as Obsidian Sync, to continue on another device where you left off, with your styles, presets, dashboards and pronunciations already there.
- Your data: Keep everything private: no telemetry, voices and dictionaries that work offline, book files that are never changed, and your data in plain files in your vault.
Learn more: Getting Started · Sync and Devices · The .orbis File · Settings Reference · Command Reference
Screenshots

Reading on a computer: passage selections in several marks, and the Navigator's Annotations tab.

The same page after Save as PDF, with your marks drawn where you made them and your notes as PDF comments.
User guide
The User Guide explains every feature step by step.
- New to Orbis? Start with Getting Started.
- Looking for a setting or a command? See the Settings Reference and the Command Reference.
- Something not working? See Troubleshooting.
Supported formats
| Format | Extension | Passage selections | Notes | Search | Listen | Export |
|---|---|---|---|---|---|---|
| EPUB | .epub |
✓ | ✓ | ✓ | ✓ | ✓ |
| Mobipocket | .mobi |
✓ | ✓ | ✓ | ✓ | ✓ |
| Kindle Format 8 | .azw3 |
✓ | ✓ | ✓ | ✓ | ✓ |
| FictionBook 2 | .fb2 |
✓ | ✓ | ✓ | ✓ | ✓ |
| Comic Book Archive | .cbz |
— | — | — | — | — |
EPUB has the broadest compatibility and the most consistent behavior across sources. File quality varies — if something behaves unexpectedly with a particular book, try sourcing it from a different provider.
Installation
Community plugins (recommended)
- In Obsidian: Settings → Community plugins → Browse
- Search for Orbis Reader
- Select Install, then Enable
Orbis Reader is in the Obsidian community plugin directory.
With BRAT, for betas
BRAT is a community plugin that installs plugins from GitHub and keeps them up to date. Install Orbis Reader with it to test betas before they are released.
- In Obsidian: Settings → Community plugins → Browse, search for BRAT, then select Install and Enable
- Go to Settings → BRAT and select the + next to Beta plugin list
- Enter
https://github.com/rastewart/obsidian-orbis-readeras the repository, select Latest version (not dictionaries, which is Look-up's dictionaries), keep Enable after installing the plugin selected, and select Add plugin
BRAT installs each new version when Obsidian starts, betas included. See Getting Started for how to stay on one version.
Manual install
- From the releases, download
main.js,manifest.json, andstyles.cssfrom the newest Orbis Reader release (the Dictionaries release contains Look-up's dictionaries, not the plugin) - Copy them to
<your-vault>/.obsidian/plugins/orbis-reader/ - In Obsidian: Settings → Community plugins — enable Orbis Reader
Getting started
- Place ebook files (
.epub,.mobi,.azw3,.fb2,.cbz) anywhere in your vault - Select any ebook file in the file explorer to open it in the reader
- Use the toolbar at the top of the reader to open the Navigator (contents, search, annotations, linked vault notes and stats), bookmark a page, listen, and change the display style
- To turn on optional features, such as book sources, look-up dictionaries, the library, reading records and listening voices, go to Settings → Orbis Reader → Setup. The Welcome to Orbis Reader dialog takes you there the first time Orbis runs on a device
See Getting Started for a full walkthrough.
Reading data
Orbis never changes your book files. It keeps each book's data in a !orbis-data/ folder beside the book:
- A
.orbisfile with your passage selections, notes, bookmarks, reading stats and the book's details - A reading-location file for each device, so each device keeps its own place
- Recordings, in an
audio/folder, if you record the book
The .orbis and location files are plain JSON that you can inspect, back up or sync. Selecting a .orbis file opens the book's reading data: its cover, reading activity on each device, contents, annotations and the notes that link to the book. See The .orbis File.
Network use
Orbis Reader has no accounts, ads or telemetry, and it never sends your books, notes or reading data anywhere, unless you set up a speech server to record with (below). It connects to the internet only for the features below, and nothing is downloaded until you ask for it. Dictionaries, voices and fonts are saved on your device, so those features work offline after their first download.
| Feature | Connects to | What for |
|---|---|---|
| Book sources | Project Gutenberg (gutenberg.org) and any OPDS catalog you add, such as your own Calibre server |
Browsing, searching and downloading books |
| Look-up dictionaries | GitHub, from this repository's releases | Downloading Webster's 1913 and Open English WordNet |
| Orbis voices | Hugging Face (huggingface.co), cdnjs.cloudflare.com and cdn.jsdelivr.net |
Downloading the speech engine and the voices you choose to your device |
| Recording with a speech server (off until you set it up) | The Kokoro or OpenAI-compatible server address you enter, such as one on your own computer | Sending the text being recorded, a sentence at a time, and getting the audio back. Recording on your device, the default, sends nothing |
| Expanded character set for PDFs | cdn.jsdelivr.net |
Downloading the DejaVu fonts |
| Download test fixtures (a developer command) | GitHub, from this repository's releases | Downloading the test books and notes for the test plans |
Web look-ups and links in books open in your web browser, but only when you select them. When you select a link in a book, you are prompted to confirm that you want to visit it before it opens. System voices come from your operating system, which may use online services of its own.
Files outside your vault
Orbis Reader reads and writes files in your vault only, with one exception that you choose each time. On a computer, Save as PDF, Save annotations as PDF, Save as Markdown, Generate notes and Notes to EPUB have an Export… button. It opens your system's save dialog, so that you can save the file wherever you pick: to send it to someone, or to open it in another app. Orbis Reader writes only that one file, and only after you select Save.
On a phone or tablet, the same dialogs have Share… instead. The file goes to your device's share sheet from Orbis Reader's plugin folder, and nothing is written outside the vault.
Accessibility
Orbis Reader implements ARIA roles, keyboard navigation, and semantic focus management for its interface components (menus, sidebars, toolbars).
Screen readers: Orbis Reader hasn't been tested with screen readers or other assistive technology, and some of them may have trouble reading a book's text. However, the plugin can read books aloud; see Listening.
Supported languages
Orbis Reader's interface is available in English only for now. However, its text isn't written into the code. Every menu item, setting, command, dialog and message lives in one locale file, so a translation can be added later without changing how the plugin works. Since English is the only language I speak, I haven't attempted any translations myself. How a translation would fit in is described in Localization.
How Orbis Reader is made
Orbis Reader is designed by Rob Stewart and coded by Claude Code, Anthropic's AI coding assistant. I decide what Orbis Reader does, how it looks and behaves, and when a change is finished. Claude Code writes the code including all of the TypeScript, the styles, the automated tests, and the build scripts. Claude Code also writes the majority of the documentation.
Orbis Reader is designed to work on every device, and wherever possible every feature works the same on a phone, a tablet and a computer. Its dialogs are designed for the phone first. They work just as well on a computer, but they're laid out to fit the smaller screen rather than squeezed onto it afterward.
Each change runs through automated tests and checks, and I test Orbis Reader on macOS, Windows, Android, iPhone and iPad.
Orbis Reader isn't the only way to read ebooks in Obsidian. Before I started on it, I looked through the community plugins that support ebooks. Several already do a great deal well. If Orbis Reader isn't the right fit for you, search for "EPUB" or "ebook" in Settings → Community plugins → Browse, and one of the others may suit you better.
The open-source projects Orbis Reader builds on, such as foliate-js and lamejs, are their authors' work; see License.
License
MIT — see LICENSE.
Third-party components and their licenses are listed in NOTICES. In
particular, recorded (pre-generated) audio is encoded to MP3 using
lamejs, a JavaScript port of the
LAME MP3 encoder, under the LGPL-3.0 (full
license texts in licenses/). It is vendored, unmodified, in
src/vendor/lamejs, and stays under the LGPL there. The
reader engine, foliate-js (MIT), is
vendored with Orbis's changes in src/vendor/foliate-js.
Word look-up can download two offline dictionaries, neither of them bundled.
Webster's Revised Unabridged Dictionary (1913) is in the public domain.
Open English WordNet (2025 edition) is derived from
Princeton WordNet by the Open English WordNet community and licensed under
CC BY 4.0 (full text in
licenses/CC-BY-4.0.txt). The asset Orbis builds from
it is modified — reshaped for offline look-up, as described in
NOTICES — and is not the release itself.
PDF export can use the DejaVu fonts as its
Expanded character set, so a PDF can show arrows, Greek, Cyrillic,
mathematical symbols and other characters beyond the standard PDF fonts. The
fonts are not bundled with Orbis Reader; they are downloaded to your device on
request, and each PDF includes only the characters it uses. Fonts are
© Bitstream, Inc., and glyphs imported from the Arev fonts are © Tavmjong Bah;
DejaVu's own changes are in the public domain. Full terms are in
licenses/dejavu-fonts-LICENSE.txt.
Feedback
Report a bug or request a feature as an issue in this repository. Pull requests are by invitation only; see Contributing.