Skip to content

About

Native Jetpack Compose Komga client for Android

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

KMReader for Android

Native Jetpack Compose Komga client for Android.

Android Kotlin Compose Komga

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.

Features

Readers

  • 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.

Browse and discovery

  • 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, More menu (edit, komf identify), and multi-select batch actions (mark read/unread, download, add to list, delete).

Downloads

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).

Server and sync

  • 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.json snapshot, 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).

Tracking and metadata

  • 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.

Platforms

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.

Design reference

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

Platform differences

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.

Requirements

  • JDK 17
  • Android SDK 37 (compileSdk = 37, minSdk = 28, targetSdk = 36)
  • Gradle 9.7.1 — pinned by the committed wrapper, so ./gradlew downloads it; no separate Gradle installation is needed (Android Studio works too).

local.properties must point at your SDK:

sdk.dir=/path/to/Android/Sdk

Build and run

./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.json

On 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.

Releases

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.

Project layout

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

Compatibility

  • 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.

Community

Acknowledgements

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.

About

Native Jetpack Compose Komga client for Android

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages