NovelRead

NovelRead is a privacy-friendly, offline Android novel reader built with Kotlin and Jetpack Compose. It focuses on reliable local-book importing, comfortable long-form reading, precise reading-position restoration, and a clean bookshelf experience.

Project status: Active development. NovelRead currently reads local books and does not yet include online book sources or internet search.

Features

• Import local TXT, EPUB, HTML, and Markdown books through Android's Storage Access Framework.
• Preserve TXT paragraph structure and detect common chapter headings and text encodings, including UTF-8, GB18030, and GBK.
• Normalize titles and authors inferred from imported file names, with editable book metadata and custom covers.
• Organize the bookshelf with groups, visibility controls, sorting, filtering, grid/list layouts, and horizontal group switching.
• Read with paged or continuous scrolling modes.
• Choose Slide or Cover page-turn effects in paged mode.
• Keep chapter titles, paragraph indentation, page anchors, progress, and cross-chapter landing positions consistent.
• Navigate with touch gestures, on-screen controls, or optional volume keys.
• Search the full text of an imported book and jump to an exact result.
• Save reading progress, bookmarks, and notes.
• Use foreground text-to-speech with configurable rate and pitch.
• Export and restore books, chapters, covers, settings, progress, bookmarks, and notes in a self-contained backup archive.
• Use localized English and Simplified Chinese interfaces.

Supported formats

Format	Import behavior
TXT	Detects common encodings and chapter headings while preserving paragraph boundaries.
EPUB	Imports metadata, supported cover images, spine order, and readable chapter text.
HTML	Uses heading elements as chapter boundaries and converts blocks to readable text.
Markdown	Uses level-one and level-two headings as chapter boundaries and extracts readable text.

EPUB, HTML, and Markdown content is converted to the app's shared plain-text chapter model. Native EPUB layout, embedded fonts, advanced links, footnotes, and media overlays are not currently preserved.

Technology stack

• Kotlin 2.0.21 and Java 17
• Jetpack Compose with Material 3
• Room for books, chapters, progress, bookmarks, notes, and bookshelf groups
• DataStore for reader and bookshelf preferences
• Kotlin Coroutines and Flow for asynchronous state handling
• Kotlin Serialization for backup data
• Gradle 8.9 with Android Gradle Plugin 8.7.3
• Minimum Android version: Android 8.0 (API 26)
• Compile and target SDK: 35

Getting started

Prerequisites

• Android Studio with Android SDK 35 installed
• JDK 17
• An Android device or emulator running Android 8.0 or later

Clone and build

git clone https://github.com/hzySerein/NovelRead.git
cd NovelRead

On Windows:

.\gradlew.bat assembleDebug

On macOS or Linux:

./gradlew assembleDebug

The debug APK is generated at:

app/build/outputs/apk/debug/app-debug.apk

Android Studio creates local.properties for the local SDK path. This file is machine-specific and intentionally excluded from version control.

Verification

Run the local verification gates on Windows:

.\gradlew.bat testDebugUnitTest
.\gradlew.bat assembleDebug
.\gradlew.bat lintDebug

When a device or emulator is connected, instrumentation and Compose tests can also be run with:

.\gradlew.bat connectedDebugAndroidTest

Project structure

app/src/main/java/com/example/novelread/
|-- core/       Shared reader, search, and TTS logic
|-- data/       Importers, Room entities/DAOs, repositories, covers, and backup
|-- domain/     Application models and normalization rules
`-- ui/         Compose screens, state, navigation, ViewModels, and theme

Additional design and implementation notes are available in docs/, including the importer, backup, TTS, UI, and reader performance contracts.

Privacy and limitations

• NovelRead currently works offline and does not request the Android internet permission.
• Imported book content and reading data remain in the app's local storage unless the user explicitly exports a backup.
• Text-to-speech is foreground-only; it does not provide background playback or lock-screen media controls.
• Online book-source import and online catalog search are not implemented yet.

License

No license has been added to this repository yet. Until a license is provided, the source code remains protected by the default copyright rules.