Lagrange Reader is an independent Android app for reading and listening to books hosted on BookOrbit. It began with a personal need: I love BookOrbit, but I wanted an app that lets me take my library with me and read offline.
It is now for anyone who already uses a BookOrbit server, whether they run it themselves or received an account from someone else, and wants a native Android experience for their library.
BookOrbit remains the server and source of truth for your library. Lagrange is the Android client: it lets you browse, download, read, listen, and keep working when your connection is unavailable. When you reconnect, queued progress and other supported changes synchronize back to BookOrbit.
This is a community project, not an official BookOrbit application. Development was AI-assisted, with the implementation, testing, and product decisions reviewed by the project owner.
Pull requests for new features and general fixes are temporarily paused for a few days while the multi-server architecture and provider-module refactor are prepared. This short pause is intended to let the refactor stabilize before additional changes are integrated.
Please do not open a pull request during this pause unless a maintainer has requested it or it fixes a security vulnerability. Security reports should follow SECURITY.md. Issue reports and design discussion remain welcome. See CONTRIBUTING.md for the current contribution policy.
The following screenshots show the main reading and library experience. More screenshots are available below.
More screenshots
Use Lagrange if you have:
- access to a BookOrbit server and an account on that server;
- an Android phone or tablet running Android 8.0 (API 26) or newer;
- books, comics, PDFs, or audiobooks that you want available away from the server.
Lagrange is not a standalone ebook reader and does not provide a BookOrbit server. If you do not already have BookOrbit access, start with the BookOrbit project.
- Install the latest Lagrange release.
- Open the app and enter the URL of your BookOrbit server. Prefer HTTPS, especially outside your home network.
- Sign in with the account provided by your BookOrbit administrator.
- Browse your libraries, open a book, or download content from Book Detail for offline use.
The current sign-in flow supports username/password, explicit BookOrbit OIDC provider sign-in in a WebView, and a generic server-hosted sign-in fallback. Native OIDC/AppAuth is not implemented. See OIDC / SSO Authentication.
Lagrange is a standalone native Android client, not a wrapper around the BookOrbit web interface. It has its own Compose browsing experience, Room-backed local catalog and caches, durable offline downloads, background synchronization, Readium-based publication readers, and persistent Media3 audiobook playback. BookOrbit supplies authenticated server and library data; Lagrange owns the Android interface, local state, reading, listening, and offline behavior.
The important boundary is simple: BookOrbit stays authoritative, while Lagrange maintains useful local state so reading and listening can continue through unreliable connectivity. This also means Lagrange does not attempt to replace BookOrbit's administration, integrations, or web interface.
- Offline-first library: browse cached books and reopen downloaded EPUB, PDF, CBZ, and supported audiobook files without a connection.
- Two-way sync: send local reading/listening progress to BookOrbit, receive server-side progress and status changes, and replay queued offline progress after reconnecting.
- EPUB reading: paginated chapters, themes, text size, independent margins, chapter/page navigation, exact resume, keep-awake mode, per-library font selection through grouped normal/accessibility menus, one imported custom
.ttf/.otffont, read-along narration for local EPUB 3 media overlays, and service-owned Android text to speech with sentence highlighting, preset or custom 0.5×–2× speed and pitch, optional speed-scaled punctuation pauses, uninterrupted rotation/screen-lock playback, media controls, background progress persistence, and separate Listen from here/Keep listening actions. - PDF and comic reading: Readium-powered PDF and image readers with fullscreen controls, page navigation, Preview isolation, and CBZ/online CBR support.
- Audiobook playback: compact and full players with seeking, chapter selection, previous/next chapter controls, playback speed, sleep timer, resume, responsive portrait/landscape layouts, session history, read-along support, and optional pausing/resuming when Android reports competing audio focus (enabled by default).
- Library discovery: Home, libraries, series, authors, search, achievements, local books, filters, sorting, and series navigation.
- Reliable offline downloads: progress, cancellation, retry/update flows, cache validation, and safe local replacement.
- Personalized controls: five app themes, reader themes, orientation lock, reduce motion, cellular download policy, cache management, and background-network controls.
| Format | Online | Offline | Notes |
|---|---|---|---|
| EPUB / KEPUB | Yes | Yes | Full paginated reader with themes, margins, chapters, resume, publisher narration, and foreground-service Android text to speech that continues through rotation and screen lock. |
| Yes | Yes | Readium PDF reader with page navigation and resume. | |
| CBZ | Yes | Yes | Image-based comic reader. |
| CBR / CB7 | Yes | Yes | Online page extraction is supported; offline reading uses client-side RAR4/RAR5/7z extraction into a cached CBZ. User-confirmed offline opening works. |
| Audiobooks supported by BookOrbit | Yes | Yes | Readium audio playback with chapters, speed control, seeking, and resume. |
The following ebook formats are intentionally not supported at this time: MOBI, AZW, AZW3, and FB2. Conversion may be considered later. Audiobook and unusual comic files still benefit from broader device testing.
Lagrange targets the BookOrbit API used by the current v1.5.3 release. The implemented API behavior is documented in docs/bookorbit-api.md, including libraries, books and files, progress, downloads, reading sessions, achievements, and statistics where supported.
The compatibility table below is based on the tagged BookOrbit server history and the API change introduced in BookOrbit's dedicated audiobook playback commit. It describes the supported API boundary, not a complete end-to-end test matrix for every server release.
| BookOrbit server | Lagrange capabilities |
|---|---|
v2.10.0+ |
Library and book browsing, non-audio online content, downloads and offline reading, progress and status synchronization, reading sessions, achievements, statistics where supported, and remote audiobook playback through the dedicated manifest, asset-content, and playback-state APIs. |
v2.0.1–v2.9.x |
Library and book browsing, generic online content serving, downloads and offline reading, progress and status synchronization, reading sessions, achievements, statistics where supported, and audiobook playback through the pre-v2.10.0 generic file-serving API. |
Earlier than v2.0.1 |
Not verified. |
Native mobile OIDC redirects are a known upstream compatibility gap; the interim WebView sign-in remains the supported path for that scenario. Server administrators should review the BookOrbit release history and API documentation before upgrading a production instance, and report incompatibilities through GitHub Issues.
| Format | What syncs | Accuracy notes |
|---|---|---|
| EPUB / KEPUB | Overall percentage, plus a one-based chapter/page fallback |
Server percentage is generally an accurate overall-progress signal, but the exact in-chapter/on-screen location is approximate since exact Readium Locator/CFI is not uploaded. Same-device resume from the local Readium Locator is usually exact. |
| Page-index progress | Synchronizes the current page index; subject to queue/throttle and network delay, so it does not guarantee pixel- or viewport-exact cross-device resume. | |
| CBZ | Page-index progress | Same page-index synchronization and delay characteristics as PDF. |
| CBR / CB7 | Page-index progress | Same page-index synchronization and delay characteristics as PDF; offline reading uses client-side extraction into a cached CBZ. |
| Audiobooks | Periodic position/percentage snapshots | Position is sampled locally and queued/throttled before upload, so server-side progress reflects a periodic snapshot rather than an exact wall-clock playback timestamp. |
| Unsupported formats (MOBI, AZW, AZW3, FB2) | Nothing | No reader or progress sync is available for these formats. |
Progress uploads are queued and throttled rather than sent immediately, and can be delayed by connectivity; a clean reader/player close attempts a best-effort flush of the pending queue but is not guaranteed to complete before the app fully closes offline.
Lagrange separately records active reading/listening intervals through BookOrbit's file-scoped POST /api/v1/books/files/{fileId}/sessions endpoint. Sessions are authenticated, stored in a durable offline queue, retried in the background, and deduplicated with a stable session ID. The server source is web, which BookOrbit reports in its native BookOrbit source bucket.
| Format | Session starts | Pause/close behavior | Progress and timing |
|---|---|---|---|
| EPUB / KEPUB | When usable publication content opens | Ordinary backgrounding pauses the interval unless foreground TTS is actively reading; pausing TTS or closing the reader finalizes it | Percentage/chapter fallback; visible reading plus active foreground-service TTS time |
| When usable pages open | Same pause/resume and close behavior as EPUB | Page-based percentage; active foreground time only | |
| CBZ / CBR / CB7 | When usable comic pages open | Same pause/resume and close behavior as EPUB | Page-based percentage; CBR/CB7 may be normalized to a cached CBZ locally, while the original BookOrbit file ID is retained |
| Audiobooks | When actual playback begins | Tapping pause finalizes the active listening interval; play starts a new interval; player close also finalizes it | Wall-clock active listening duration and periodic position/percentage; playback speed does not multiply session duration |
Preview sessions are excluded. Sessions shorter than 10 seconds are discarded by the client. Paused, background, and idle time is not counted. Server sessions support analytics and reading history; exact local audiobook seeking remains backed by Lagrange's local session history.
Lagrange does not include behavioral telemetry, advertising tracking, an analytics SDK, or a remote crash-reporting service. It does not collect usage events or device identifiers for the Lagrange project.
The app does send functional requests to the BookOrbit server that you configure. Depending on the features you use, this includes authentication, library and book metadata, cover and media requests, reading/listening progress, reading-status changes, personal ratings, Statistics requests, and server reading-history requests. These requests are required for the app to browse, synchronize, read, listen, and recover progress.
Lagrange stores app data locally in its private Android sandbox, including session cookies, cached catalog data, downloaded files, reader state, queued progress, preferences, and exact local audiobook session history. Exact local audiobook session-history events are not uploaded by Lagrange; the server-history view only reads analytics records already stored by BookOrbit.
BookOrbit may retain or log normal server-side request information such as account activity, request timestamps, and network metadata. That server-side retention is controlled by the BookOrbit server and its administrator, not by Lagrange. Use HTTPS for the configured server; cleartext HTTP can expose credentials, session tokens, metadata, progress, and content on the network. See docs/privacy.md for more details.
Lagrange requests only the permissions needed for networking, media playback, and playback notifications:
| Permission | Why it is requested |
|---|---|
INTERNET |
Connect to the configured BookOrbit server for authentication, catalog data, content, synchronization, and media playback. |
ACCESS_NETWORK_STATE |
Detect whether a network is available and apply the app's online/offline and background-network behavior. |
FOREGROUND_SERVICE |
Keep audiobook playback running in a foreground service when the app is backgrounded. |
FOREGROUND_SERVICE_MEDIA_PLAYBACK |
Declare that the foreground service is used for media playback under current Android rules. |
POST_NOTIFICATIONS |
Show audiobook playback controls and other user-visible notifications on Android versions that require notification permission. |
The app does not request location, contacts, camera, microphone, phone, SMS, storage-wide, or advertising-ID permissions.
BookOrbit is the server and web platform; Lagrange is an independent Android client. The table describes the current integration boundary rather than implying that the two projects share the same UI or implementation.
| Capability | BookOrbit server/web platform | Lagrange Android client |
|---|---|---|
| Authentication | Provides authenticated accounts, server sessions, configured OIDC providers, public state/callback APIs, and the HTTPS callback used by the WebView OIDC flow. | Uses username/password, explicit BookOrbit OIDC WebView sign-in, and generic Open server sign-in fallback. Native AppAuth remains deferred. |
| Library and catalog | Owns libraries, books, authors, series, metadata, scanning, and catalog APIs. | Browses BookOrbit libraries and caches catalog data for offline fallback. |
| Reading and listening | Serves book files, reader data, progress APIs, and audiobook media. | Provides native EPUB, PDF, comic, and audiobook readers with resume, themes, navigation, and playback controls. |
| Offline use | Remains the connected source of server content. | Downloads supported content and reopens it offline, including CBR/CB7 files via client-side RAR4/RAR5/7z extraction into a cached CBZ. |
| Progress and status | Stores reading/listening progress and book statuses. | Queues progress offline, synchronizes it, and exposes the server status controls in the Android UI. |
| Ratings and metadata sources | Owns book metadata, provider IDs, and per-user book data. | Displays and updates supported per-user ratings and opens centralized links for known metadata providers. |
| Audiobook sessions | Stores server reading sessions and reading attempts as analytics/history records. | Shows server history after local history; local exact-position audiobook sessions remain device-only and seekable. |
| Statistics | Provides summary, daily reading, heatmap, source, peak-hour, timeline, goal, completion, pace, and related statistics APIs. | Currently consumes the summary and daily-reading endpoints in the lazy-loaded Statistics screen. |
| Achievements | Owns achievement definitions and user progress. | Provides an Achievements destination that loads the user's server-backed achievements. |
| Annotations, bookmarks, and notes | Provides server modules and APIs for these reading records. | Not currently exposed as a dedicated Lagrange feature. |
| Integrations and administration | Includes integrations such as OPDS, KOReader, Kobo, Readwise, StoryGraph, notifications, and administrative/audit tools. | Focuses on the Android reading/listening experience and does not expose the server administration surface. |
Remaining follow-up work includes but is not limited to:
- Support for additional book formats; MOBI, AZW, AZW3, and FB2 remain unsupported.
- Implemented the explicit BookOrbit OIDC WebView flow and retained the generic Open server sign-in fallback. Real-provider/device validation remains required; native AppAuth is separate follow-up work.
- Broader bulk actions for Local books beyond the implemented multi-select
Delete localflow.
More details are in the Roadmap
- Windows, macOS, or Linux with a current Android Studio installation.
- JDK 17.
- Android SDK with API 35 installed.
- An Android device or emulator running API 26 or newer for manual testing.
Clone the repository, open it in Android Studio, and let it use the included Gradle wrapper. From a terminal at the repository root, the release build is:
# macOS/Linux
./gradlew assembleRelease
# Windows PowerShell
.\gradlew.bat assembleRelease
The generated APK is:
app/build/outputs/apk/release/app-release.apk
For local builds, the signed APK is generated under app/build/outputs/apk/release/. Distributed APKs are published as GitHub Release assets. Starting with 1.5.2, releases provide Lagrange-<version>.apk as the normal combined download, plus Lagrange-<version>-x86.apk, Lagrange-<version>-x86_64.apk, and Lagrange-<version>-arm.apk for manual ABI selection. If you are unsure which ABI to use, download the plain Lagrange-<version>.apk file. Keep release-key.jks and keystore.properties backed up securely; they are intentionally ignored by Git.
Useful verification commands are:
# macOS/Linux
./gradlew testDebugUnitTest lintDebug assembleDebug assembleDebugAndroidTest
# Windows PowerShell
.\gradlew.bat testDebugUnitTest lintDebug assembleDebug assembleDebugAndroidTest
Debug APKs are built for 64-bit ARM devices only (arm64-v8a); use the timestamped debug APK produced by assembleDebug for device handoff testing.
For machine setup details and the manual test matrix, see docs/setup.md and docs/testing.md.
Lagrange Reader's interface and interaction ideas were informed by the clarity and workflows of Plex, Komga, Audiobookshelf, and Suwayomi. These projects are inspirations only; Lagrange Reader is independently developed and is not affiliated with, endorsed by, or sponsored by them.
I contacted the BookOrbit maintainers on July 28, 2026 to ask permission to distribute or promote this client, and have not received a response yet. The app is independent, and its name, logo, and documentation should not be read as an endorsement by the BookOrbit maintainers.
Lagrange Reader is licensed under the GNU General Public License, version 3. The project may be distributed through both free GitHub releases and paid Google Play releases. A paid release remains subject to GPLv3: recipients receive the corresponding source and may redistribute the GPL-covered application under the license terms.
Third-party libraries and embedded assets remain under their respective licenses. See THIRD_PARTY_NOTICES.md for the dependency and attribution inventory. See docs/privacy.md for the app's local-data and network behavior.
Thank you to the BookOrbit maintainers and contributors for the server and library experience that inspired this app, to the Readium Foundation and open-source library authors whose work makes the reader possible, and to everyone who tests Lagrange and reports issues.