Using OperaLibre
This is the everyday guide for listeners and the person who looks after the library. Connect to an OperaLibre server, use the native app’s on-device library, or try the bundled demo. Getting Started explains the OperaLibre server setup.
Try the demo
Choose Explore the on-device demo on the server connection screen to try OperaLibre without a server or account. The bundled demo pairs a 2 minute, 7 second excerpt of Alice’s Adventures in Wonderland, read by Kristen McQuillin for LibriVox, with the full Project Gutenberg ebook #11 and sentence timings. The recording and ebook text are public domain in the USA; copyright status elsewhere can differ. The EPUB retains its original license and credits. Sources, credits, and license, on the demo book page and in Settings, is available offline.
Sign in and listen
- Open the OperaLibre address in a browser. The person who set it up creates the first administrator account on this screen.
- Sign in with your own reader name and password.
- Select a book, then use Play, the speed control, 15-second rewind, 30-second skip, and the sleep timer as needed.
Tapping a book you have started in Up Next loads your saved position in the player without starting playback. Its play button resumes immediately. To start playback from either tap, enable Play when opening a book in progress in the native app’s Settings → Behavior, or under Behavior in the browser’s reader menu. This choice is remembered on the device.
OperaLibre remembers a reader’s position automatically. Each reader has separate progress, so two people can listen to the same book independently.
The small Preview bar beneath a server book’s cover plays its opening five minutes (or the whole book if it is shorter). Previews pause your current reading and leave your listening progress and Up Next queue unchanged. When the sample ends, choose Continue listening to start a reading where the sample stopped. Books already in progress resume your saved position; if the preview covered the entire book, listening starts from the beginning. Previews need a connection to an OperaLibre server and pause when you leave the app or book page. To hide the Preview bar on a device, turn off Audio previews in the native app’s Settings → Behavior, or under Behavior in the browser’s reader menu.
Fix a book that is too quiet
Audiobooks are mastered at very different levels, so a device volume that suits one book leaves the next one hard to hear. Book Volume, in the player’s playback sheet (the speed pill) and on the book’s own page, trims or lifts that single book by up to 24 dB without touching anything else. It is saved per reader on the server, so a book you turned up on your phone is already turned up on every other device you sign in from.
When the server has ffmpeg, it also checks each book’s mastering in the background and lifts books that were recorded far too quietly, or turns down ones that are far too loud, so they play near a normal speech level. The playback sheet shows Audio adjusted when this is happening, with a switch to turn it off for that book. Setting Book Volume yourself always takes priority; turning the switch back on returns the book to the suggested level. The sheet also notes books whose tracks vary a lot in loudness or whose audio leans to one side or is on one channel only. Your audio files are never changed.
The setting is a boost, not a re-recording: past the point where a book’s loudest passages reach full scale a limiter holds them there, so very large boosts trade some dynamic range for audibility. A frontend hosted separately from the OperaLibre server can only turn a book down, not up — the browser will not let it read the audio closely enough to amplify it.
Safari and other WebKit web players currently allow reductions only because routing audio through their boost engine can distort playback. This also applies to downloaded and imported books. Saved boosts remain available in supported players; Safari plays them at Original. To use boost, use the native iOS app or desktop Chrome or Firefox with a frontend served by OperaLibre.
Keep the player in its own window
In a desktop browser, Pop out in the player (or the window button in the mini player) moves the controls for the book that is playing into a small window of their own, so you can pause, skip, scrub, and change speed while you work in other windows. Resize it to suit: tall shows the cover above the controls, wide puts them side by side, and short leaves a single strip. Space plays and pauses, and the left and right arrow keys skip back 15 and forward 30 seconds. In Chrome and Edge the window stays above your other windows; other browsers, and addresses that use plain http:// instead of HTTPS or localhost, open an ordinary popup, which your browser may ask you to allow. Playback stays in the original tab, so closing that tab closes the window too. Back to tab or Bring back closes it.
Set your own sleep timer
Nightfall, on the book’s own page and behind the timer button in the phone player, offers the usual 5, 15, 30, 45, and 60 minute stops. End of chapter stops when the chapter you are listening to finishes, however long that takes; if you skip or pick another chapter, it waits for the end of the one you land in. It appears for books that have chapter markers. Choose Custom and type any length from 1 to 600 minutes when none of those matches the chapter you are in the middle of. Durations you type are kept on that device — the three most recent sit alongside the presets — so a length you use often is one tap away the next night. The countdown only runs while the book is playing.
Keep a passage as a clip
Audio clips are a beta feature, off by default. Enable Audio clips under Settings → Beta Features in the app, or Beta Features in the browser’s account menu. The choice is remembered on this device.
Tap the gold ribbon on the cover’s top-right corner in the player when you hear something worth keeping. It saves the last 30 seconds and the next 10, so the line you just heard is in it along with enough around it to make sense later. Nothing else happens: the book keeps playing and your place does not move.
Open a book from your Library and choose the Clips tab on its details page to browse its passages. The Chapters tab returns to the chapter list. The player’s Details menu also has a Saved clips entry. Browsing, naming, or sharing a saved clip leaves your current playback alone until you choose to preview it. Use the play button beside a passage for a preview. Tap its name to trim it, name it, or share it. Drag the audio strip beneath the gold frame to choose the passage; letting go plays a preview. Choose Length to keep between one second and five minutes, and use the minus and plus buttons for one-second adjustments. You can also give it a name or add a note, then choose Save changes. Previewing a clip opens its book and returns to your listening place in that book, paused, when it ends or you stop it. Continue from here moves your place to the clip and keeps playing beyond it.
Share audio sends the clip as a small audio file through the phone’s share sheet, or saves it as a download in a browser. The server cuts the file on request, which needs ffmpeg; without it the button is not shown.
To hide clipping on this device, turn off Audio clips under Beta Features. Turn it back on to see your saved passages again.
Clips are private to the reader who saved them and are kept on the server, so they appear on every device you sign in from. A clip saved with no connection waits on the device and is sent the next time the server is reachable. Clips need an OperaLibre server and are unavailable for books imported onto the device or the demo.
Add books to the library
You can add books in either of these ways:
- Copy files into the library folder. Put them in the folder chosen as
library_root, then choose Rescan library from the administrator controls. Follow Library Layout for the expected folder and filename patterns. - Upload through the app. An administrator can choose Upload audiobook in the library header (in the phone and tablet apps, Add then Upload to the server), enter the book name, select one audio file (such as an M4B) or every track for a multi-file book, then upload. The app puts it in a new library folder and rescans automatically.
Uploads accept the audio types listed in Library Layout. Cover art initially comes from the artwork embedded in the audio files’ tags. An administrator can open Edit Info, choose a JPEG, PNG, or WebP cover, and Save Info to replace it for everyone with access to the book. Images must be at most 8 MiB, 16 million pixels, and 8192 pixels per side; OperaLibre saves a resized copy without changing the audio. Restore original cover returns to the embedded artwork, or the placeholder if there is none.
Cover changes survive rescans and server restarts. They require a writable book folder; keep its hidden OperaLibre cover files when moving or backing up your library, alongside a server backup containing your metadata edits.
For a book without an EPUB, an administrator can choose Add EPUB on the details page (under More on mobile) and select a matching, unencrypted ebook up to 64 MiB (or the configured upload limit, if lower). OperaLibre validates it, saves it beside the audio, and rescans. Existing files are never overwritten, and a book with a sync map cannot be paired with a different reading copy until that map is removed. Other companion formats can be copied into the book’s folder, followed by a rescan.
Organize books with custom tags
An administrator can open a book, choose Edit book info, and add one or more custom tags. Each tag can also have its own optional book number. This is useful when a title has an immediate series but also belongs to a wider world or reading order: keep its normal series as Mistborn, then add Cosmere with the appropriate Cosmere book number. Tags survive library rescans, appear on the book, participate in search, and can be selected as the library sort.
Plan your next read
Up Next on your library shelf lists the books you have already started, most recent first, followed by the books you plan to listen to after them. To plan a book, open it and choose Add to Up Next; this does not start the book or change its listening position, and works for a finished book you want to hear again. On a phone or tablet, touch and hold a planned book and drag it to a new place; anywhere, the up arrow moves it earlier. Remove one with the × button or from its own page. Select a planned title to open it without playing, or use its play button to start listening.
Your queue is saved on this device, separately for each server and account. When offline, only available device books and downloads are shown; other queued books return when you reconnect.
Sort and filter your shelf
Use Sort by to choose the order and the arrow beside it to reverse that order. Your choice is remembered separately for Your Library and Audible. The count below the controls shows how many books match.
Sorting by series, tag, genre, or progress groups the shelf under headings. Select a heading to fold that group away, such as a long series you are not reading right now, and select it again to open it. Folded groups stay folded on that device, and a search shows matching books even inside a folded group.
Search Your Library with words from a book’s title, author, narrator, series, tags, or genres. Every word must match the book, but they can come from different fields: Carroll Wonderland finds Alice’s Adventures in Wonderland by Lewis Carroll. Capitalization and extra spaces do not matter.
Open Filters to combine reading progress, genres, and tags, and to show only books downloaded on this device or books you can read along with. Selecting multiple genres or tags includes any of those choices within that group; combining groups narrows the results. Larger genre and tag lists have their own search fields. Counts update as you filter, and selected filters remain visible as removable chips after you close the panel. Clear all removes filters; the search field has its own clear button.
For a wider reading order, filter to Cosmere and choose Tag under Sort by. Books then follow their Cosmere numbers, even if Cosmere is not their first tag. With multiple tags selected, the first selected tag that a book carries determines its group and number; without tag filters, its first tag is used.
Spread out your shelf
In a wide browser window, the Expand shelf button at the top of the shelf gives it the whole window, with Up Next across the top and your books below as covers. Books sorted by title or author are filed under their letters, with an A–Z index along the edge to jump between them; sorted by series or tag, each group’s name sits beside its books. Opening a book shows its page in a window over the shelf. While a book plays, the player sits along the bottom. Select it, or choose Player at the top, to go back to the full player. Collapse shelf returns to the usual layout, and the browser remembers your choice.
Add people and recover access
An administrator opens Administration → Users & access to add a reader, remove one, reset a password, or limit their shelf to selected books. In the native apps, Administration is inside Settings. Give every household member their own account rather than sharing the administrator password. See Users & Accounts for owner and administrator permissions.
If every administrator password is lost, the server owner can recover access by following Resetting a forgotten admin password. Keep a backup of data_dir: it contains accounts and listening progress.
Use it on a phone or tablet
Install the web app
Open the OperaLibre address in Safari, Chrome, or another modern mobile browser and sign in.
- iPhone or iPad (Safari): tap Share, then Add to Home Screen.
- Android (Chrome): open the browser menu and choose Install app or Add to Home screen.
Open it from the new home-screen icon afterward. The web app offers the same library, player, readalong, and progress sync as the browser. Your phone must be able to reach the server; see Getting Started: Running on the LAN.
Listen from this device
In the native iPhone, iPad, or Android app, choose Listen from this device on the connection screen, then tap Add on the shelf and choose Add files to this device. Files are copied into the app’s private storage; no server or account is needed. Select all tracks of a multi-file book together. You can also add device books while connected to a server; they stay on the device and are not uploaded automatically.
Open an imported book’s details and choose More → Add EPUB to pair an unencrypted ebook up to 64 MiB for offline reading. This preserves the audio and listening position. The EPUB opens beside the audio, but following the narration needs a sentence map, and the app can’t make one for an imported book yet. Removing a device book deletes its imported audio and EPUB while keeping listening progress; your original files are left in place.
Download server books for offline use
In the native iPhone, iPad, and Android apps, open a book’s details and choose Download. The app saves its audio, cover, companions, and available sync map. The button then reads On device: the audio is saved on this phone or tablet. Adding a purchase to your server does not save it on your device. Before disconnecting, check Audio, Ebook, and Sentence sync on the book’s details or under Settings → Downloads. Audio can finish even if an ebook, cover, companion, or sync map could not be saved. Retry missing files fetches those files without downloading the audio again or changing your listening position. Canceling a retry keeps your existing download. Downloads and cached server shelves belong to the selected server account; imported device books are separate.
Files marked ready remain available without reaching the server, including after restarting the app. An ebook needs an EPUB; sentence sync needs both the EPUB and a sentence timing map. Not provided or not supported means the book does not offer that feature, rather than a failed download. Progress is kept locally and reconciled when the server becomes reachable again. Tap On device on a downloaded book to confirm removing the device copy; the server’s book and your listening progress remain. Removing the book currently open in the player stops playback. To free space automatically, turn on Settings → Behavior → Remove downloads when finished; finishing a book, or marking it finished, then deletes its downloaded copy from that phone. It is off by default, and books you imported from the device are never removed this way. A book that finishes in CarPlay, or while the server is unreachable, keeps its download. The browser and home-screen web app do not create this offline library.
Native iPhone and iPad app
The repository also includes a native iPhone and iPad app with background spoken-audio playback. Building it requires a Mac with Xcode and an Apple development team:
- From the repository root, run
npm run ios:open -w @operalibre/web. - In Xcode, select the App target, then select your development team under Signing & Capabilities.
- Connect your iPhone, select it as the run destination, and press Run.
- In the app, choose OperaLibre, enter the server’s LAN address (for example
http://192.168.1.20:4920), and sign in.
The app supports HTTP for private home-network and Tailscale-style addresses. Use HTTPS for a public server.
On a wide iPad window, Shelf shows the collection across the available width, while Listening shows the shelf beside the player or selected book details. Starting playback or opening details brings back Listening. Narrow iPad windows use a single pane, and the ebook opens in its own full-screen reader. The app keeps the active tab in step as you resize or rotate.
To reach the same server from more than one network, save its other addresses under Settings → Connection → Address aliases. Each address keeps its own sign-in: the first time you use one, tap Sign in beside it and enter your password. After that the app moves between your signed-in addresses by itself whenever one stops answering. Signing out signs you out of all of them.
Siri and Shortcuts
On iOS 16 or later, say “Siri, resume OperaLibre,” “Siri, resume my audiobook in OperaLibre,” or “Siri, resume my book in OperaLibre.” The Resume Audiobook action is also available in Apple’s Shortcuts app. To use “Siri, resume my audiobook” without the app name, create a personal shortcut named Resume my audiobook and add OperaLibre’s Resume Audiobook action.
Open OperaLibre and play a book once before using Siri. Resume uses the loaded player, or the last book’s saved position on this device after a cold launch. If there is no recent playback record and several books are in progress, open the app to choose one. Finished books are not automatically restarted. Downloaded books can resume offline; streaming needs access to your server and a valid saved media URL. Cold launches use the device’s cached library; open the app to refresh changes made on another device. Listening progress from Siri is kept locally and reconciled with the server when the app opens.
CarPlay
The iPhone app appears on the car screen once it is connected to CarPlay. It has three tabs — Listening, Downloaded, and Library — and tapping a book resumes it where you left off. The Now Playing screen carries the usual transport, a playback-speed button, and a Chapters list under Up Next.
A few things worth knowing:
- The car reads a snapshot of your library that the phone app writes as the shelf changes, so open the app on the phone once after signing in or adding books. This is also what makes the car screen work when the app was not already running.
- Books you have downloaded play with no network at all. Books that stream are still listed, marked with a cloud, and need the server to be in reach — which it usually is not once you have driven away.
- Progress from a drive is saved by the phone app, not by the car, so it reaches the server the next time you open OperaLibre. Your position is kept on the device meanwhile.
- Starting a book in the car takes over playback; the shelf shows an Audiobook playing banner with an Open player button to bring it back to the phone.
To try it in the CarPlay simulator, build with signing on so the entitlement is linked into the binary, then re-sign without it — SpringBoard refuses to launch a simulator build whose signature claims the CarPlay entitlement, while CarPlay only lists apps whose binary carries it:
xcodebuild -project apps/web/ios/App/App.xcodeproj -scheme App -configuration Debug \
-destination 'generic/platform=iOS Simulator' -derivedDataPath dist/ios-derived \
CODE_SIGN_IDENTITY="-" CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=YES \
CODE_SIGN_STYLE=Manual PROVISIONING_PROFILE_SPECIFIER="" DEVELOPMENT_TEAM="" build
codesign --force --sign - dist/ios-derived/Build/Products/Debug-iphonesimulator/OperaLibre.app
Install that build, then turn on I/O › External Displays › CarPlay in Simulator. (npm run build:ios signs nothing, so the app runs on the phone screen but will not appear on the car’s.)
Apple gates CarPlay behind an entitlement it grants per app: request com.apple.developer.carplay-audio for your App ID at developer.apple.com/contact/carplay. Until it is granted, Xcode cannot sign a build for a device — remove CODE_SIGN_ENTITLEMENTS from the App target’s build settings to keep installing the app in the meantime. The CarPlay simulator (I/O › External Displays › CarPlay in Simulator) needs no entitlement.
Native Android app
The repository includes a native Android 7+ app. Building it requires Android Studio, an installed Android SDK, and JDK 21:
- From the repository root, run
npm run android:open -w @operalibre/web. - Let Android Studio finish its first Gradle sync, then select an emulator or connected Android device.
- Press Run.
- In the app, choose OperaLibre, enter the server’s LAN address (for example
http://192.168.1.20:4920), and sign in.
For a directly installable development build, run npm run build:android; the APK is written to apps/web/android/app/build/outputs/apk/debug/app-debug.apk. Configure release signing in Android Studio before distributing the app. Private-network HTTP is supported; public servers should use HTTPS.
Use another audiobook app
The server implements part of the Audiobookshelf API for compatible clients. For BookPlayer, add an Audiobookshelf server, enter the OperaLibre address with /abs appended (for example http://192.168.1.20:4920/abs), and sign in with a normal OperaLibre account. Its browsing and download HTTP contracts have been checked; full app playback has not been verified. BookPlayer imports downloads locally and does not automatically send listening progress back to OperaLibre. The official Audiobookshelf app needs additional endpoints that OperaLibre does not implement. See Client compatibility for coverage.
There is also an OPDS catalog for generic reading apps; see the API Reference for the feed address.
Read along with the ebook
The ebook reader is available by default when a book has a text companion. Open it from the book details or the Read along button while listening.
To read while listening, place an EPUB, PDF, text, or HTML companion beside the audio as described in Library Layout. Books with a text companion show an Ebook tag with a book icon in the library. Synced EPUBs show Follow along with a book-and-headphones icon instead when the follow-along add-on is enabled: their text follows the audio. Disabling the add-on returns them to Ebook until it is enabled again. Use the library’s Ebook only and Follow along filters to find either group. Their details page opens with an invitation to Open reader. On the phone apps the Now Playing screen has a Read along button as well. The reader remembers that you had it open for a book and your place in it, so selecting the book again brings the text straight back.
In a browser the reader fills the window. The book’s contents run down the left, with the title above them as the way back to the book; the page sits in the middle; and on a wide window the right-hand column shows whether the page is following the narration, your place, and the sync tools. The player stays docked along the bottom with speed, the sleep timer, and the chapter list. A narrow window reads full screen instead, with the same bars as the phone apps.
Any EPUB opens beside the audio. To follow the narration, the owner must enable Follow along under Administration → Experiments, and the book must have an aligned sync map. You can then tap a mapped sentence to play from there. In the ebook, press Follow to start following the narration. Following starts off for a new reader and remembers the last choice afterward. With following on:
- The narrated sentence is highlighted and the page turns with the narration.
- Turning a page by hand pauses following so you can read ahead. To rejoin the audio, turn following back on (the target Follow button in the reader), and the marker snaps to the narrated sentence again.
- Themes and text size are under Aa above the page, next to the full-screen focus mode. The arrows under the page, the arrow keys, and swipes turn pages.
If you update the frontend separately, update the server too so ordinary readers can check the experiment setting. Older servers that deny that check offer no Follow button until upgraded; a denied check does not enable sentence following. The app retains a previously confirmed setting for offline reading.
On the phone and tablet apps the ebook opens as a full-screen reader of its own, over whatever you were doing, and closing it puts you back there. It reads like a paper book: tap the left or right edge of the page to turn it, swipe if you prefer, and tap a mapped sentence in the middle to play from there. A turned page curls over like paper, and a page you drag follows your finger until you let go: carry it across to turn it, or put it back down to stay where you are; to turn pages instantly instead, switch off Page turn animation in Settings → Behavior. It is also skipped when the device asks for reduced motion. A tap on an empty part of the page hides the bars for distraction-free reading and brings them back. The title bar holds the follow toggle, the Contents sheet (chapters and any other companion files), and the Appearance sheet (theme, text size, Improve sync). The theme starts on auto, which turns the page dark whenever the app is in its dark look (the system theme, or the appearance chosen in Settings on the phone); pick paper, sepia, or night to fix it. Under the page a strip shows the sync state and the page within the chapter, and holds the full player so you never have to leave the book: play/pause, skip back and forward, and buttons for speed, the sleep timer, and the chapter list that open over the page. When the book isn’t the one playing, a Listen while you read button starts it instead. Full-screen focus mode on the web uses the same layout.
EPUBs without an aligned map have no Follow button; OperaLibre does not estimate sentence timings. To enable sentence following, an administrator can either put a matching .sync.json file beside the book and rescan, or set up automatic alignment:
- Open Administration → Experiments and install the optional follow-along generator (owner only).
- Choose Enable.
- Open the book’s reader and select Improve sync.
The reader explains what the button does before you press it, and shows a progress bar with the chapter being aligned, the percentage done, how long it has been running, and a rough estimate of the time left. The bar is read from the server, so closing the reader, moving to another book, or reloading the page does not stop the run — reopening the book picks the progress back up.
Alignment matches numbered chapter labels across formats such as “Chapter One” and “1”, and “Interlude Three” and “I-3”. It keeps narrated image titles separate from prose and recognizes trailing illustrations that share an EPUB document with a chapter. The reader can use accessible image descriptions to distinguish a part heading from an illustration on the same page. When confidently matched speech skips whole EPUB sentences, those sentences remain unhighlighted; surrounding narration keeps its own timing. Additional speech, such as a diagram description absent from the visible EPUB text, can likewise be kept separate when matching phrases bracket it. Suspect speech-recognition windows are retried automatically with a stronger model and, if needed, shorter overlapping windows. A shorter retry is used only when it improves the ordered text matches. These checks can increase generation time. These improvements apply when generating a new map; updating the client alone does not regenerate saved timings.
Follow-along generation is developed and tested with English books. The audiobook and EPUB must be in the same language; a translation cannot be aligned with audio in another language. Other languages that separate words with spaces, such as Spanish, French, or German, can be aligned, but they use a general multilingual recognizer that is less accurate than the English one, so expect more retries and more unhighlighted passages. The EPUB’s language metadata selects the recognizer, so a Spanish book whose EPUB is labelled English aligns poorly. When that happens, sync says so and offers to re-sync the book in the language it heard; see below. Chapter words and spelled-out numbers are understood only in English (“Chapter Twelve”); in other languages, chapters are paired by identical titles, leading digits, or their order. Languages written without spaces between words, such as Chinese, Japanese, and Thai, are not supported.
Generation downloads any missing model files, so initial use requires network access. Generation runs locally and audiobook contents are not uploaded anywhere, unless the owner turns on OpenAI transcription. Jobs run one at a time; repeated requests for the same book reuse its queued, running, or paused job.
Optional: speech recognition with OpenAI
By default, follow-along sync runs entirely on your server. An owner who prefers can instead have OpenAI’s speech recognition transcribe the narration, using their own OpenAI API key. While it is on, short clips of each book’s narration are sent to OpenAI as the book syncs and billed to that key, under OpenAI’s terms. Book text, accounts, and listening history stay on the server, and matching the audio to the text still runs locally, so the follow-along add-on is still required.
To use it, open Administration → Experiments, choose OpenAI under Speech recognition in the follow-along card, paste your key, and choose Use OpenAI. To go back, choose On this server and Use this server; the saved key is deleted, and a book that is syncing stops sending audio at its next clip. Existing maps are kept either way.
To monitor several books together, open Administration → Experiments and expand Sync activity under the follow-along sync generator. It shows running and queued books, progress, elapsed time, and recent completed or failed results. Select a book title to open it. The view refreshes while expanded; collapsing it does not stop server jobs. Use the small × to remove a queued or paused book, or dismiss a completed, failed, or cancelled result. A new finished sync replaces older results for that book, including old failures after a successful re-sync or chapter re-run. Dismissal applies to everyone and survives restarts; it leaves maps, chapter grades, and listening progress unchanged. Books without a current map stay under Ready to optimize, and Poor or Failed maps stay under Needs attention. A failed scheduled-start notice can also be dismissed beside the book. Dismissing a job result clears its matching scheduled-failure notice. Use the up/down arrows to change the queue order. Pause stops the current section and keeps completed chapters or tracks saved, without waiting for a long track to finish. Resume puts the book back at the end of the queue and repeats the unfinished section. Paused books stay paused across server restarts. Server updates interrupt running syncs at their last saved section and resume them automatically once the server is ready; the unfinished section is repeated. A failed update resumes the queue on the current server. The queue, saved sections, and recent results survive restarts. Interrupted books resume from the last completed section once the library is ready and the generator is enabled; an unfinished section is repeated. If the audio, EPUB, alignment runtime, or server alignment code changes, generation starts over. Previous maps stay usable until replacements are saved.
When an update includes a mapping improvement that warrants regeneration, older generated maps show an Outdated map badge in Sync activity. Ordinary updates do not trigger this. Maps generated before revision tracking was introduced are treated as older maps. You can re-sync a single book, sync all missing and outdated maps now, or enable nightly batches. Choose a time and a books-per-night limit (two by default, from 1 to 100); the panel estimates the minimum number of nights needed. Batches run one book at a time and may continue into the day. Current maps and third-party sidecars are left alone. Disable the nightly rule to stop future batches; work already queued continues. Individually scheduled books keep their chosen start time. Starts missed by more than 15 minutes move to the next night for nightly batches, or show as missed for individual schedules.
Each synced book is graded Good, Review, Poor, or Failed beside its title in the book list. OperaLibre grades every chapter by how much of its text gets highlighted and how much of its audio has no matching sentence, and a book takes the grade of its worst chapter longer than two minutes, so a short title card or author note can’t sink it. An explicit alignment failure still marks the book Failed regardless of the chapter’s length. Text the narration deliberately leaves out, such as an edition’s extra passage, doesn’t count against it. Books graded Poor or Failed are listed first under Needs attention. Select a grade to see that book’s chapters, worst first, with the share of text highlighted and the unmatched time. A chapter short on highlights may be back matter the narrator skips rather than a sync problem, so listen to a flagged chapter before re-syncing. Maps made before grading existed, and .sync.json files you added yourself, receive an estimated grade after the next library scan, without running alignment again; re-syncing a book gives it a full grade. A grade never stops a map from being used.
One chapter that can’t be aligned, for example because the speech recognizer crashes on it, no longer stops the rest of the book. That chapter keeps its sentences from the book’s previous map, or, without one, stays unhighlighted while the reader holds its place through its audio. It is graded Failed, and the finished sync reads Completed · N chapters need attention in Sync activity, naming what went wrong. If the first three chapters all fail, or every chapter does, the problem is more likely the alignment add-on than the book, so the sync fails and the previous map stays as it was.
Poor and Failed chapters say why in the chapter list, and failed syncs say why in Sync activity and the reader, in plain words with the original error under Technical details. Some problems are fixed during the same sync, once per chapter, keeping the new timing only when it grades better:
- The speech recognizer crashed: the chapter is tried again with a different recognition model.
- The narration was hard to make out: the chapter gets one more pass with a larger, slower model.
- This audio belongs to another chapter: when a chapter’s opening words clearly match another chapter’s text, as with swapped chapter markers, the chapter is aligned with that text instead.
Others need you:
- The narration is in a different language: the narrator isn’t speaking the language in the EPUB’s label. Choose Re-sync as English (or whichever language was heard) in the book’s chapter list. This sets the language for that book alone and re-syncs the affected chapters. The chapter list then shows which language the book is recognized in; choose Use the EPUB’s language to undo it from the next sync.
- This EPUB may be a different edition: the narration is clear, but most of it isn’t in the text. Use an EPUB of the same edition as the audiobook.
- Problems with the add-on itself, unreadable audio, or a step that ran too long say what to check, and can be tried again once that is sorted out.
To fix chapters without re-syncing the whole book, open the book’s grade, tick the chapters below Good, and choose Re-run selected chapters. Only those chapters are aligned again; the rest of the map is left exactly as it was. A chapter that fails again keeps its earlier sentences and shows the new error. Re-runs wait in the same queue as other syncs and can be paused, moved, or removed. A book can have one sync queued at a time, so let a re-run finish, or remove it, before re-syncing that book. Re-running needs a current map that OperaLibre generated, whose chapters still match the book: if the audio, its chapter markers, or the EPUB changed since the last full sync, or the map is outdated or one you added yourself, re-sync the whole book instead.
Generated maps are saved in data_dir/sync; disabling or removing the add-on keeps them but disables sentence following. The app remembers the last server setting so downloaded audio, EPUBs, and sync maps can still follow sentences after an offline restart; reconnecting applies any setting changes made on the server. A matching .sync.json file beside the book takes priority, except when a current generated map replaces an outdated OperaLibre map. Sync quality is best when the audio track names, or the chapters embedded in an M4B, correspond to the EPUB chapter titles. Processing time and memory depend on the book and server; generation can compete with playback on smaller machines. The current implementation transcribes successive windows across long chapters and then aligns their text; it does not yet use sparse speech sampling. Wait for queued and running jobs to finish before updating, disabling, or removing the add-on.
Development and manually managed installations may instead set alignment_cli_path to an existing echogarden executable. A manually configured generator is treated as installed and enabled, but OperaLibre does not update or remove it.
Extras: maps, illustrations, and supplements
Audible titles often come with a PDF of maps or illustrations rather than the book’s text. OperaLibre opens each companion during a scan and tells the two apart, so a picture PDF is offered as Extras instead of being presented as the book. A book can have both: the reader then shows tabs above the page for the ebook, each supplement, and a gallery of any loose pictures in the book’s folder (in the phone reader these are listed under Other files in the Contents sheet). A book with only extras shows a View extras invitation in place of the reader.
Connect an AI assistant
An AI assistant you already use can read from your server: to recap a book you set down weeks ago without spoiling what comes next, suggest what to read next from your own shelf, track a series or your achievements, or answer questions about your listening. Nothing is shared until you connect one, and each listener connects their own.
AI assistants are an experiment the owner turns on under Administration → Experiments. While it is off, nobody can connect one. Once it is on, each listener finds AI assistants in Settings in the phone and Mac apps, or in the account menu in a browser. Choose Connect an assistant, give it a name, and choose what it may do:
- Your library: the books you can open, with their descriptions and series.
- Where you are: how far through each book you are.
- Listening history: when you listened, what you finished, your stats, and your achievements.
- Book text so far: a book’s text up to the sentence you have reached.
- Get books for you: what you own on Audible and Libro.fm. The assistant can help you choose a title, but you add or request it yourself on Get books. It cannot start downloads or send requests on your behalf. This one starts switched off.
OperaLibre then shows an address and a token. The token is shown only once. Add both to the assistant as an MCP server. In Claude Code:
claude mcp add --transport http operalibre http://192.168.1.20:4920/api/agent/mcp \
--header "Authorization: Bearer olagent_..."
In Codex, put the token in an environment variable such as OPERALIBRE_AGENT_TOKEN and add this to ~/.codex/config.toml:
[mcp_servers.operalibre]
url = "http://192.168.1.20:4920/api/agent/mcp"
bearer_token_env_var = "OPERALIBRE_AGENT_TOKEN"
Other assistants that accept an MCP server address with a bearer token connect the same way. The assistant must be able to reach the address, so use your LAN, Tailscale, or HTTPS address as you would for the app. Assistants whose connector settings offer only an OAuth sign-in, such as the ChatGPT app, cannot connect yet.
Apart from getting books, an assistant can only read. It cannot change your progress or anything else, it never sees other listeners’ activity, and it sees no more than you can in the app: if an administrator narrows your access, the assistant’s narrows with it. Whatever it reads is sent to the company that runs the assistant. Remove an assistant from the AI assistants card to disconnect it. Assistants are also disconnected when someone else resets your password, when your account is removed, and when the owner restores a backup. If the owner turns the experiment off, connected assistants stop working until it is turned back on.
Recaps need a book with its text and a follow-along map (see Read along with the ebook), because the map marks exactly where you are in the text, or a book transcribed for chapter notes. The assistant gets nothing past that point, and it is asked not to fill in the plot from its own knowledge of the book.
Chapter notes
Chapter notes give each chapter a spoiler-free synopsis, a full summary, and the people and places in it, including for books that have no ebook. They are an experiment the owner turns on under Administration → Experiments.
Notes start from the book’s words. A book with a follow-along map uses its own text. Any other book is transcribed on your server by the follow-along sync add-on, so install that first. Writing the notes needs a language model, which the owner chooses on the same card: paste an Anthropic API key, or give the address of any OpenAI-compatible endpoint, such as Ollama or LM Studio on your own network. With no model chosen, books are only transcribed, and a connected assistant writes its own recap from the transcript.
An administrator makes a book’s notes from the book’s page with Make notes (or Transcribe). Transcribing takes a while on modest hardware, and one book is worked on at a time. A chapter’s text goes to the model you chose only then, and running it again sends only chapters that changed. Remove deletes the book’s notes and transcripts.
Notes appear on the book’s page and in the player’s details. Summaries of chapters you have not finished stay hidden until you choose Show spoilers. Assistants with Book text so far can read them the same way: everything for chapters you have heard, only the synopsis for the chapter you are in, and nothing later unless you ask the assistant to spoil it.
Import Audible books with Libation (optional)
Install a recent Libation CLI on the same computer as OperaLibre, or use the OperaLibre installer’s optional Audible setup. Add the CLI path and libation_files_dir for an existing installation to server.config, then restart.
In installed apps, open Settings → Book stores → Audible; on the web, open the account controls under Get books → Audible. Check setup checks the server’s installation and storage. Connect an account with the guided Amazon browser sign-in, or use accounts already configured in Libation. Choose Reconnect if a sign-in expires. Give each account a short label such as Personal or UK so books show the label rather than an email address.
Choose Add to server to import a purchase into the shared library. Download it to your device separately for offline listening. Administrators with direct-download access can enable Automatically add new purchases per account; existing purchases and Audible Plus titles stay manual. Queued imports resume after a server restart, and approved reader requests retain their approval. Detailed setup and troubleshooting are in Libation / Audible Import.
Reading achievements
Open Reader’s ledger from the account menu, or the Ledger tab in the iPhone and Android apps. The ledger is part of an OperaLibre library, including books kept on the device.
Achievements on that page are calculated from the books you can open and from your recorded listening. OperaLibre does not store a separate award or the date one was earned. Finishing a book, or changing its author, narrator, genre, or series, can change the set you have earned. Hours of listening are measured time. A finished book’s length is its original runtime, at any playback speed. Books that live only on the device count when the ledger is showing that on-device library.
The milestones are books finished (1, then 10, 25, and 100), a finished book of at least 24, 48, or 72 hours, five authors, five genres, and three books by one author, with one narrator, or in one series. Streaks use your longest run of consecutive listening days (7, 30, and 100). Total listening has marks at 24, 100, and 500 hours. Filter the grid with All, Earned, and In progress. A card that names a book opens that book.
Reading together, under the grid, compares your place with other readers who share their activity: who is further through a book you have both started, and who has finished more volumes of a series. A tie is left off the list, and the list is the current library rather than a history of who passed whom. It shows up to six standings. Turn on Share my reading activity on the ledger, or under Shared reading in Settings on the phone apps. Standings need a connection to the OperaLibre server.
Games
The installed iPhone and Android apps include a Games tab. Chapter Match is a board where you swap adjacent symbols to line up three or more. Shelf Sort deals stacks of mixed-colour books: move books onto an empty stack or a matching colour until each stack holds one colour, with a new colour joining every couple of shelves. Cover Grid cuts one of your book covers into a sliding puzzle of 3×3, 4×4 or 5×5 pieces: slide pieces into the gap until the cover is whole. Turn on piece numbers or peek at the whole cover if you get stuck. Covers downloaded to the device work offline. The tab is in the bottom navigation by default. Turn it off with Games tab under Settings → Behavior. The games run on the device, and Cover Grid only reads covers your server already shows you; nothing about play is sent anywhere.
Color vision
Under Settings → Display → Color vision in the apps, or Account menu → Display on the web, choose Red–green, Blue–yellow, or Monochrome to change interface accents and status colors. The choice stays on this device and works offline. Covers and book illustrations keep their original colors; ebook links and narrated-sentence highlights follow the selected palette.
Turn on Stronger visual cues for outlined selections, underlined links, patterned listening progress, and a numbered listening calendar (1–4, from less to more). It works with any palette, including Default colors. Chapter Match uses a different symbol for each piece, and Shelf Sort prints a volume number on every book, so neither game depends on colour alone.
Light and dark themes
The iPhone and iPad apps can turn dark with your device or stay light or dark all the time; choose under Settings → Display → Appearance. Themes, just below it, sets how each appearance looks, with the light themes (Parchment, Linen, Sage, Harbor, Pure White) beside the dark ones (Warm, Graphite, Midnight, Reading Room, True Black). Each choice is remembered on the device and applies only while the app is in that appearance, so with System you can pick one of each. The Shelf and Games follow the appearance like every other screen.
The iPhone and iPad apps also follow the text size set in iOS (Settings → Display & Brightness → Text Size, or Accessibility → Display & Text Size → Larger Text for the largest sizes). The ebook reader keeps its own text size under Aa.
Check for application updates
Open Administration → Overview and choose Check for updates under Software versions. In a browser this checks the installed server and its separately updatable web application; in the installed iOS app it checks the connected server. Owners can install supported managed-package updates from the same card when one is available.
Other servers and apps
The OperaLibre apps connect to OperaLibre servers. Earlier versions could also connect to a Jellyfin server; after updating, that saved connection is removed and the app opens at the connection screen so you can enter an OperaLibre server address.
Other apps can still use your library. The server’s Audiobookshelf-compatible API lets Audiobookshelf apps such as BookPlayer connect to an OperaLibre server, and its OPDS catalog serves OPDS readers. See Client compatibility.
macOS app
The macOS app is a small native window around the web app. From the repository root, run ./script/build_and_run.sh, then enter the address of a running OperaLibre server on its first screen. It remembers the address and sign-in token between launches. Start the OperaLibre server separately with npm run dev:server while developing, or use the production server command in Getting Started.
OperaLibre → Check for Updates… installs the latest signed web app. If a newly installed version fails to start, the app goes back to the version it was running before (or the one it shipped with). A version that fails to load, or that still shows nothing after loading on two separate launches, is not offered again until a fixed or newer release is published.