Lagrange Reader

An offline-first Android reader for BookOrbit, Komga, and Kavita.

Lagrange Reader is an independent Android app for reading and listening to books hosted on BookOrbit, Komga, and Kavita. It began with a personal need: 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, Komga, or Kavita server, whether they run it themselves or received an account from someone else, and wants a native Android experience for their library.

Your configured server remains the source of truth for its library. Lagrange is the Android client: it lets you browse, download, read, listen where supported, and keep working when your connection is unavailable. When you reconnect, queued progress and other supported changes synchronize back to the active provider.

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.

Contributions are welcome. Start with an issue or feature discussion, then follow the repository workflow in CONTRIBUTING.md before opening a pull request. Security reports should follow SECURITY.md.

The following screenshots show the main reading and library experience. More screenshots are available below.

Use Lagrange if you have:

• access to a BookOrbit, Komga, or Kavita 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, Komga, or Kavita server. If you do not already have server access, start with the BookOrbit project, Komga, or Kavita.

1. Install the latest Lagrange release.
2. Open the app and choose BookOrbit, Komga, or Kavita, then enter your server URL. Prefer HTTPS, especially outside your home network.
3. Sign in with the account provided by your server administrator.
4. Browse your libraries, open a book, or download content from Book Detail for offline use.

The current sign-in flow supports BookOrbit username/password and server-hosted OIDC sign-in in a WebView, Komga Basic Auth and server-hosted OAuth2/OIDC sign-in in a WebView, and Kavita username/password plus server-hosted OIDC sign-in in a WebView. Native OIDC/AppAuth is not implemented. See BookOrbit OIDC / SSO Authentication, Komga integration, and Kavita integration.

Lagrange is a standalone native Android client, not a wrapper around any provider's 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. The configured provider supplies authenticated server and library data; Lagrange owns the Android interface, local state, reading, listening, and offline behavior.

The important boundary is simple: the configured provider 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 any provider'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 supported local reading/listening progress to the configured provider, receive supported 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/.otf font, 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.

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 currently supports BookOrbit, Komga, and Kavita. Each provider has different capabilities, authentication methods, and offline behavior. See the provider documentation for details:

• BookOrbit
• Komga
• Kavita

Provider-specific validation is tracked in the provider function matrix.

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.

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 provider server that you configure. Depending on the provider and 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; a server-history view only reads analytics records already stored by providers that expose that capability.

The configured provider 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 provider 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:

The app does not request location, contacts, camera, microphone, phone, SMS, storage-wide, or advertising-ID permissions.

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 local flow.

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.

Lagrange Reader is licensed under the GNU General Public License, version 3. A Google Play release is planned.

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.