KMReader for Android is the Android client of the KMReader family, built and maintained inside the kmworks organization next to kmreader (iOS, macOS, tvOS) and kmrs (Komga-compatible server). It is an official sibling app — not a fork, re-skin, or third-party port — and it follows the same design contract as the Apple app: identical information architecture, feature set, and navigation model, translated to Android containers only.
- DIVINA reader for CBZ/CBR image pages: LTR, RTL, and vertical/webtoon directions; spreads with wide-page splitting and solo cover pages; double-tap and pinch zoom with pan; configurable tap zones and long-press action; page transitions, page shadow, progress bar, and chrome gradient; border cropping; preload profiles; per-book preferences; keep-screen-awake.
- EPUB reader on the WebView + ReadiumCSS path: theme presets, typography (font size, weight, line height, margins, columns), publisher styles, flow style, page-turn animation, nested table of contents, and importable custom fonts.
- PDF reader on the official AndroidX PDF viewer: text layer for selection/search, table of contents, page jump, continuous scroll, page presentation and solo-cover options, reading background, and progress overlay.
- Dashboard with Keep Reading, On Deck, Recently Added, Recently Updated, and Read Lists in Progress sections; per-section card style, ordering, visibility, and dedicated section pages.
- Library browse: content-type chips with counts, library scopes, sort and layout switching (list / grid / large grid), and filters for reading status, one-shots, authors, tags, notable entities, publishers, genres, age ratings, languages, release years, and series status — with all/any matching and saved filter presets.
- Lists: collections, ordered read lists, and smart lists, including the condition builder (field / operator / value, match all or any, book or series target) and list creation from anywhere.
- Search tab with series, books, read lists, and collections results.
- Series, book, and one-shot detail pages: hero with server-side thumbnail, action card,
metadata, tracker section,
Moremenu (edit, komf identify), and multi-select batch actions (mark read/unread, download, add to list, delete).
Downloads are managed on device with WorkManager: a download list and queue with pause, resume, retry, and cancel, library-scoped auto-download of unread books, a Wi-Fi-only constraint, storage usage, and cleanup of downloaded books. Offline browsing mode is intentionally out of scope (see Platform differences).
- Multiple Komga servers with instant switching; sign in with username/password or an API key.
- Komga API v1 and v2 through a Retrofit client generated from the pinned
api/openapi.jsonsnapshot, so the wire contract is versioned with the app. - Server-sent events for real-time library updates, client settings sync, reading stats, and an in-app log viewer with share/export.
- Network settings (timeout, concurrency), image cache usage and cleanup, true-black theme, and app icon variants (primary / classic / legacy).
- Tracker accounts for AniList, MyAnimeList, Bangumi, and MangaBaka, with series binding, link editing, progress mapping, and remote progress (requires a kmrs server).
- komf integration for Identify and metadata matching on servers that provide it.
Phones and tablets in one build: bottom navigation on phones, a floating capsule navigation bar on
tablets (≥840dp), and the wide detail layout from the Apple app at ≥960dp with a golden-ratio info
rail of max(38.2%, 340dp). UI is monochrome Material 3 — no brand color, no gradients, no
invented variants. List and collection covers are always the server-generated thumbnails.
The UI ships in English and Simplified Chinese.
docs/preview.html is a self-contained static mock of the full design —
every screen, phone and tablet, no build required. It documents the intended layout and states;
the Compose implementation is the source of truth once a screen ships.
| Area | Screen |
|---|---|
ui/dashboard |
Dashboard, section detail, dashboard customization |
ui/library, ui/browse |
Library browse, filters, search |
ui/lists |
Collections, read lists, smart lists, detail and edit sheets |
ui/detail |
Series, book, one-shot detail; edit and komf sheets |
ui/reader |
DIVINA, EPUB, PDF readers; settings; custom fonts |
ui/offline |
Download management |
ui/tracker, ui/stats |
Tracker accounts and reading stats |
ui/settings |
All settings sub-pages, servers, logs, about, licenses |
Deliberately not implemented, mirroring the scoping of the Apple app to Android:
- Panel-split reading mode (CoreML shot detection) — not implemented.
- AI upscaling and manga translation overlays — not implemented.
- EPUB CoreText layout engine — EPUB always uses the WebView + ReadiumCSS path.
- Page-curl transition — only slide/cover/scroll transitions are offered.
- iOS accessory bar and iOS-only integrations (widgets, Live Activities, Spotlight, Live Text).
- Offline browsing mode — downloads and download management are kept.
Tracker, komf, and reading-stats screens are capability-gated the same way as in the Apple app (server support detected at runtime), so they are absent rather than broken on plain Komga.
- JDK 17
- Android SDK 37 (
compileSdk = 37,minSdk = 28,targetSdk = 36) - Gradle 9.7.1 — pinned by the committed wrapper, so
./gradlewdownloads it; no separate Gradle installation is needed (Android Studio works too).
local.properties must point at your SDK:
sdk.dir=/path/to/Android/Sdk./gradlew :app:assembleDebug # APK at app/build/outputs/apk/debug/
./gradlew :app:installDebug # install on a connected device
./gradlew :core:api:openApiGenerate # regenerate the API client from api/openapi.jsonOn Windows run gradlew.bat instead, for example gradlew.bat :app:assembleDebug.
Or open the repository root in Android Studio and run the app configuration.
The OpenAPI client is generated at build time into core/api/build/generated/, with a small set of
deterministic post-generation fixes for known kotlin-generator quirks (see
core/api/build.gradle.kts). Never hand-edit generated sources; update
api/openapi.json and its sha256 deliberately.
The version lives in app/build.gradle.kts. Bumping versionName (and
versionCode) on main makes the Release workflow build the
APK, add a matching sha256 file, and publish v<versionName>; a run for an already published
version does nothing.
Release builds are minified with R8 (isMinifyEnabled and isShrinkResources) and signed with the
configured keystore. Once the repository secrets KEYSTORE_BASE64 (base64 of the keystore),
KEYSTORE_PASSWORD, KEY_ALIAS and KEY_PASSWORD are set, the workflow publishes
kmreader-android-<version>.apk. Without them it falls back to a debug-signed
kmreader-android-<version>-debug.apk, so the channel keeps working before the keystore exists —
such builds are installable but cannot upgrade a properly signed build in place.
For a local release build, put the same values in an untracked keystore.properties at the
repository root (storeFile, storePassword, keyAlias, keyPassword) and run
./gradlew :app:assembleRelease.
api/ Pinned OpenAPI snapshot + hash (the API contract)
core/api/ Retrofit client generated from api/openapi.json
app/
core/ Data, network, downloads, readers (EPUB/PDF/DIVINA), tracker, komf,
settings, SSE, stats, logging
data/ UI navigation and page models
ui/ Compose screens, per feature area; ui/components for shared UI
docs/ Static design reference
- Komga 1.20.0+ (API v1 and v2).
- Enhanced features (trackers, smart-list editing, reading stats, client settings sync) require a kmrs server or a server with the corresponding integration.
KMReader for Android is built on Jetpack Compose and Material 3, Coil, OkHttp, Retrofit, kotlinx.serialization/coroutines, Room, DataStore, WorkManager, and Hilt. EPUB rendering follows the Readium CSS approach; PDF rendering uses the AndroidX PDF viewer and its bundled PDFium. The in-app licenses screen shows the license of each bundled component.