Lagrange Reader is an independent Android app for reading and listening to books hosted on BookOrbit. It started with a simple personal need: I love BookOrbit, but I wanted an app that lets me take my library with me and read offline.
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, offline downloads, background synchronization, Readium-based publication readers, and persistent Media3 audiobook playback. BookOrbit supplies the authenticated server and library data; Lagrange owns the Android interface, local state, reading, listening, and offline behavior.
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.
The following screenshots show the main reading and library experience. More screenshots are available below.
More screenshots
- 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, and keep-awake mode.
- 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 player with seeking, chapter selection, playback speed, resume, and read-along support.
- 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, and resume. |
| Yes | Yes | Readium PDF reader with page navigation and resume. | |
| CBZ | Yes | Yes | Image-based comic reader. |
| CBR / CB7 | Yes | Limited | Online page extraction is supported; offline reading requires the server and is not client-side RAR/7z extraction. |
| 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 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 and server sessions; the server also has an OIDC/SSO direction available for deployments that configure it. | Uses the current native username/password flow; direct OIDC/SSO is 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; CBR/CB7 files that require RAR/7z extraction remain server-backed. |
| 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.
- Optional client-side offline RAR/7z extraction for downloaded CBR/CB7; server-backed extraction remains the current behavior.
- Direct OIDC/SSO authentication after a BookOrbit provider and redirect contract are confirmed.
- Broader bulk actions for Local books beyond the implemented multi-select
Delete localflow. - Android API 33+ pull-down and lock-screen audiobook Back 10 / Forward 30 controls are physically validated.
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 at app/build/outputs/apk/release/app-release.apk. Distributed APKs are published as GitHub Release assets. 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
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 have not yet asked the BookOrbit maintainers for permission to distribute or promote this client. I want to test it further first, roughly another two to three weeks of real world use, before starting that conversation. The app is independent, and its name, logo, and documentation should not be read as an endorsement by the BookOrbit maintainers.
The project uses the custom LICENSE, which allows free personal and non-commercial use, modification, building, and redistribution. Commercial rights are reserved to the project owner. This is source-available, but it is not an OSI-approved open-source license.
See docs/privacy.md for the app's local-data and network behavior. The project builds on BookOrbit, Readium, AndroidX, Jetpack Compose, Kotlin, Media3, OkHttp, Room, and other open-source libraries; their respective licenses and notices remain authoritative.
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.