A high-performance offline document and book reader for Android, built with Flutter and Rust.
Download • Overview • App Walkthrough • Key Features • Spatial Dimensions • Supported Formats • Architecture • Technical Specifications • Prerequisites • Getting Started • Building Releases • Project Structure • Troubleshooting
Precompiled Android packages (APKs) are available on the GitHub Releases page, or install directly with automated updates via Obtainium:
| Architecture | Target Devices | Release Asset Pattern | Download |
|---|---|---|---|
arm64-v8a |
Modern 64-bit phones & tablets (Recommended) | ferrous-v*-arm64-v8a.apk |
Latest arm64-v8a APK |
armeabi-v7a |
Legacy 32-bit Android devices | ferrous-v*-armeabi-v7a.apk |
Latest armeabi-v7a APK |
x86_64 |
Android emulators & ChromeOS | ferrous-v*-x86_64.apk |
Latest x86_64 APK |
Tip
If you are unsure which build your phone requires, choose arm64-v8a, which works on virtually all modern Android devices.
Note
Verifying Release Integrity:
Every GitHub Release includes an official SHA256SUMS.txt manifest as well as individual .sha256 checksum files. You can verify that your downloaded package matches the official build using:
# Verify integrity with the checksum manifest
sha256sum -c SHA256SUMS.txt
# Or verify build provenance with the GitHub CLI (Sigstore attestation)
gh attestation verify ferrous-v1.4.4-arm64-v8a.apk --repo JuanSoFly/Ferrous(F-Droid packaging metadata is also tracked in fdroid/com.juansofly.ferrous.yml for repository inclusion).
Ferrous Reader is an open-source, offline-first mobile reading application designed for speed, minimal resource consumption, and granular typography control. By combining a reactive Flutter front-end (package:ferrous) with a high-throughput Rust engine (crate:rust_lib_ferrous) via flutter_rust_bridge (v2), Ferrous offloads computationally intensive workloads—such as PDFium rendering, full-storage indexing, archive decompression, and sentence tokenization—to background native threads, keeping UI animations and page interactions fluid at 120Hz.
Note
Ferrous is fully offline. It operates with zero telemetry, zero analytics, and persists all library metadata, reading locations, themes, and annotations locally on the device using Hive.
Experience Ferrous Reader's tactile 120Hz interface, native typography engine, and seamless offline library management:
- Screen-Fitted Paging Engine:
SafeScreenPaginatorpartitions reflowable EPUB, MOBI/AZW, and TXT chapters into viewport-fittedPageSliceunits using paragraph budgeting and dynamic text measurement.EpubPagedViewer,MobiPagedViewer, andTxtPagedVieweruse pure screen-sizedPageView.builderwidgets for both horizontal and vertical reading modes, with seamless chapter boundary swapping. - Precision Typography & Offset Resolution: Stateless
TextOffsetResolverand centralizedReaderTypographyMetricsguarantee mathematical parity between layout measurement and rendering, mapping screen taps directly to exact character offsets for instant bookmarks, notes, and sentence-synchronized Text-to-Speech (TTS). - Tactile Paper Textures & Book Crease: 8 authentic paper textures (Japanese Washi, Vintage Parchment, Fine Laid Linen, Deckle Rag Folio, Heavy Kraft, Slate Ledger, Obsidian Velvet, Natural Paper) paired with realistic 3D book spine crease shadow simulation.
- Realistic 3D Page Turn & Curl: Realistic physics curl (
RealisticPageTurnandAppleBooksPageCurl) with hardware-accelerated shaders, ambient shadow simulation, and dynamic lighting. - Split View / Dual Reader Screen: Side-by-side reading (
SplitReaderScreen) for comparing two books or studying dual documents with an adjustable split divider and quick document swap. - Kindle Carta 1300 E-Ink Mode: High-contrast monochrome theme with physical halftone scrims (GPU
ImageShader), mechanical slider controls, and 0ms instant page transitions. - Hardware-Accelerated PDF Engine: Powered by Google PDFium via
pdfium-render, generating thread-safe native texture bitmaps directly for continuous scrolling, rapid page flipping, and automatic whitespace detection. - Native Comic & Manga Reader: Direct Rust JPEG decoding (
jpeg-decoder) with zero-cost chunk conversions, streaming ZIP/RAR (unrar-rs) extraction with pure-Rust crypto, interactive scrubber, and adaptive edge-color letterboxing. - Synchronized Text-to-Speech (TTS): Multi-threaded text segmentation with sentence-lock tracking, 3 customizable highlight styles (
softPill,underline,classicClean), adjustable speech rate and pitch, and non-blocking background workers. - Instant Dictionary Lookup: Built-in word definitions via the Free Dictionary API directly from the reader text selection toolbar.
- Blazing Fast File Indexing: Scans device storage and Android Scoped Storage (SAF) trees in seconds via parallel directory traversal in Rust (
walkdir). - Privacy-First Offline Architecture: Zero telemetry, zero analytics, private local Hive database persistence, and built-in diagnostic logging with clipboard export for frictionless bug reporting.
Ferrous introduces Spatial Dimensions—5 distinct structural and aesthetic archetypes that transform navigation, layout density, and interface geometry across the entire application:
| Dimension | Navigation Style | Library Presentation | Design Characteristics |
|---|---|---|---|
| Modernist | Bottom Glassmorphic Bar | Staggered Masonry Grid | Contemporary fluid design with soft rounded cards and standard navigation. |
| Floating Island | Detached Capsule Dock | Bento Showcase & Hero | Translucent floating pill dock, organic squircles, and magazine-style bento cards. |
| Cyber Terminal | Top Command HUD | Monospace Telemetry | Sharp industrial geometry, monospace data chips, ASCII meters, and open bottom view. |
| Athenaeum | Classical Ribbon Navigation | Embossed Index Spines | Library card catalog layout with authentic leather spine textures and Roman markers. |
| Compact Slate | Micro Dock | Zero-Shadow List | Flat, ultra-dense single-row list designed for distraction-free reading and fast browsing. |
| Format | Parsing Engine | Rendering Pipeline | TTS Support | Capabilities |
|---|---|---|---|---|
PDF (.pdf) |
Rust (pdfium-render) |
Native texture bitmaps | Yes | Fast page flipping, text selection, TTS extraction, continuous scroll, whitespace detection |
EPUB (.epub) |
Dart (epubx) + Rust cover extractor |
Native Flutter widgets (SafeScreenPaginator, flutter_html) |
Yes | Screen-fitted paged reading, custom typography, dynamic hyphenation, CSS themes |
MOBI / AZW / AZW3 (.mobi, .azw, .azw3) |
Rust PalmDOC/PDB engine (rust_lib_ferrous) |
Native Flutter widgets (SafeScreenPaginator, flutter_html) |
Yes | Chapter navigation, embedded images, metadata extraction, paged & continuous modes |
Comic & Manga Archives (.cbz, .cbr, .zip, .rar) |
Rust (zip, unrar-rs, jpeg-decoder) |
Canvas image stream | No | Streaming archive extraction, direct Rust JPEG decoding, pinch-to-zoom, adaptive edge colors |
Plain Text (.txt) |
Rust (txt) |
Rich HTML & layout widgets | Yes | Auto encoding detection (chardetng, encoding_rs), formatted indentation, lists |
Word Documents (.docx) |
Rust (docx-rs) |
Structured HTML widgets | Yes | Document flow, paragraph formatting, and styled table layouts |
Ferrous utilizes a hybrid boundary model where Flutter handles UI composition, state presentation, and gestures, while Rust manages high-throughput, latency-critical operations.
flowchart LR
UI["Flutter Frontend<br/>(package:ferrous / UI Isolate)"]
FFI["flutter_rust_bridge v2<br/>(FFI Transport)"]
RUST["Rust Native Engine<br/>(crate:rust_lib_ferrous / tokio)"]
PDF["PDFium Engine<br/>(PDF Rendering)"]
SCAN["walkdir<br/>(Storage Scanner)"]
PARSERS["Format Decoders<br/>(PalmDOC, CBZ, CBR, DOCX, TXT)"]
TTS["TTS Pipeline<br/>(Text Segmentation)"]
UI <===>|"Type-Safe FFI"| FFI
FFI <===>|"Async Worker Tasks"| RUST
RUST --> PDF
RUST --> SCAN
RUST --> PARSERS
RUST --> TTS
- Flutter (Frontend):
- Material 3 user interface with dynamic theme switching and 5 spatial layout dimensions.
- Screen-fitted paged reader and continuous scroll modes backed by
SafeScreenPaginator. - Hive NoSQL database for instant bookmarking, reading progress tracking, and collection management.
- Text selection toolbar with annotation highlighting, notes, and instant dictionary lookups.
- Rust (Backend):
- Multi-threaded, non-blocking I/O operations powered by
tokio. - PDFium binding management with safe, asynchronous document loading and page caching.
- Direct JPEG decoding and zero-copy archive decompression (
zip,unrar-rswith pure-Rust crypto). - Text segmentation and tokenization for sentence-level TTS highlighting across reflowable formats.
- Automated character encoding detection (
chardetngandencoding_rs) for plain text files.
- Multi-threaded, non-blocking I/O operations powered by
| Component | Technology | Role & Details |
|---|---|---|
| Target OS | Android 7.0+ (API Level 24+) | Compile SDK 36; supports arm64-v8a, armeabi-v7a, x86_64 |
| Frontend Framework | Flutter 3.44+ (Dart SDK ^3.5.4) | package:ferrous: Material 3 UI, custom renderers, gesture recognizers |
| Backend Engine | Rust 1.80+ (2021 Edition) | crate:rust_lib_ferrous: High-performance compute engine and file I/O |
| FFI Layer | flutter_rust_bridge 2.11.1 |
Auto-generated, type-safe foreign function interface |
| PDF Renderer | Google PDFium (pdfium-render 0.8.37) |
Native C++ rendering via dynamic binary loading (libpdfium.so) |
| Comic & Archive Engine | zip 2.2, unrar-rs 0.15.0, jpeg-decoder 0.3 |
Zero-copy streaming decompression with pure-Rust crypto and direct JPEG decoding |
| Text Processing | chardetng, encoding_rs, hyphenatorx |
Auto encoding detection and multilingual hyphenation dictionary |
| Binary Optimization | Fat LTO (lto = "fat"), strip symbols, panic=abort |
Aggressive dead-code elimination, minimized APK binary footprint |
| Database | Hive (hive_flutter 1.1.0) |
Fast, lightweight embedded key-value document store |
| Concurrency | tokio (Rust) |
Multi-worker thread pool executing off the UI isolate |
| File Access | Android SAF + Rust walkdir |
Scoped storage compliance (androidx.documentfile) with rapid recursive traversal |
Before building Ferrous, ensure the following tools are installed on your host system:
- Flutter SDK:
3.44.0or higher (Installation Guide) - Rust Toolchain:
1.80.0or higher (stable)rustup default stable
- Android Targets for Rust:
rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
- Android NDK: Version
r26dorr26b(configured viaANDROID_NDK_HOME) - JDK: Java Development Kit 17 (Temurin recommended)
- flutter_rust_bridge_codegen:
cargo install flutter_rust_bridge_codegen --version 2.11.1
Follow these steps to set up the development environment, compile dependencies, and run Ferrous on an Android device or emulator:
git clone https://github.com/JuanSoFly/Ferrous.git
cd FerrousIf you use local tool paths, you can source the environment helper:
source ./setup_env.shflutter pub getGenerate the type-safe FFI glue code between Dart and Rust:
flutter_rust_bridge_codegen generateFerrous requires libpdfium.so for each targeted Android architecture. An automated helper script is provided to download and place prebuilt binaries:
# Default installs arm64-v8a and armeabi-v7a
bash scripts/setup-pdfium-android.shTip
If developing on an Android emulator, include x86_64:
PDFIUM_ABIS="arm64-v8a,x86_64" bash scripts/setup-pdfium-android.shFor offline manual setup instructions, refer to docs/pdfium-setup.md.
Connect an Android device with USB debugging enabled (or start an emulator) and execute:
flutter runTo generate optimized Android production packages:
Generating separate APKs per ABI significantly reduces download sizes. Production builds apply code obfuscation, symbol splitting, and icon tree-shaking:
flutter build apk --split-per-abi --release --obfuscate --split-debug-info=build/app/outputs/symbols --tree-shake-iconsOutputs are generated in build/app/outputs/flutter-apk/:
ferrous-v1.4.4-arm64-v8a.apk(modern 64-bit devices)ferrous-v1.4.4-armeabi-v7a.apk(legacy 32-bit devices)ferrous-v1.4.4-x86_64.apk(emulators & ChromeOS)
For distribution through Google Play:
flutter build appbundle --release --obfuscate --split-debug-info=build/app/outputs/symbolsOutput:
build/app/outputs/bundle/release/app-release.aab
Ferrous/
├── .github/workflows/ # CI/CD lint, release packaging & download stats
├── android/ # Android native project & SAF integration
│ └── app/src/main/jniLibs # Target ABI native libraries (libpdfium.so)
├── assets/ # Launcher icons, showcase animations & visuals
├── docs/ # Technical guides (PDFium setup, architecture notes)
├── fdroid/ # F-Droid packaging metadata (com.juansofly.ferrous.yml)
├── lib/ # Flutter presentation & logic layer (package:ferrous)
│ ├── app/ # Application shell & bottom navigation
│ ├── core/ # SafeScreenPaginator, models, dimensions & services
│ ├── data/ # Hive adapters, repositories, SAF & TTS services
│ ├── features/ # Feature modules
│ │ ├── annotations/ # Notes & centralized Annotations Hub
│ │ ├── collections/ # Custom shelves & book grouping
│ │ ├── dictionary/ # In-app word definitions dialog
│ │ ├── library/ # Library carousel, grid views & book cards
│ │ ├── reader/ # Format readers (PDF, EPUB, MOBI, CBZ, TXT, DOCX, Split)
│ │ └── settings/ # Themes, spatial dimensions & library locations
│ └── src/rust/ # Auto-generated Dart FFI bridge code
├── rust/ # Native Rust compute crate (crate:rust_lib_ferrous)
│ ├── Cargo.toml # Crate dependencies & fat LTO release profile
│ └── src/api/ # Rust exposed API modules (PDF, PalmDOC, CBZ, TXT, DOCX, scan)
├── rust_builder/ # Cargokit integration layer for cross-compiling Rust
└── scripts/ # Automation scripts (setup-pdfium-android.sh, stats graph)
Important
If the app crashes on opening a PDF with Failed to bind to pdfium library: dlopen failed: library "libpdfium.so" not found, ensure that scripts/setup-pdfium-android.sh has been executed for your target device's ABI, and verify that android/app/src/main/jniLibs/<abi>/libpdfium.so exists before running flutter run.
If you modify files under rust/src/api/, re-run the code generator to update the Dart bindings:
flutter_rust_bridge_codegen generateIf you encounter unexpected errors or format parsing issues:
- Open Settings > Diagnostic Logs inside the app to inspect the runtime trace.
- Select Feedback / Report Issue to copy the sanitized diagnostic stack directly to your clipboard.
- Paste the diagnostic trace into the GitHub Issues report template for expedited triage.








