Skip to content
JuanSoFlyPublic

About

A high-performance, offline-first e-reader for Android built with a hybrid Flutter + Rust architecture. Supports PDF, EPUB, DJVU, MOBI, CBZ, and DOCX

Topics

Resources

Stars

12 stars

Watchers

2 watching

Forks

Repository files navigation

Ferrous Reader Logo

Ferrous Reader

A high-performance offline document and book reader for Android, built with Flutter and Rust.

Latest Release Platform Flutter Rust FRB v2 License: MIT

Download Latest Release Get it on Obtainium

Ferrous Reader Showcase

Download • Overview • App Walkthrough • Key Features • Spatial Dimensions • Supported Formats • Architecture • Technical Specifications • Prerequisites • Getting Started • Building Releases • Project Structure • Troubleshooting


Download

Total Downloads

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


Overview

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.


App Walkthrough

Experience Ferrous Reader's tactile 120Hz interface, native typography engine, and seamless offline library management:

01. Offline Library & Carousel 02. Reflowable EPUB Typography 03. Realistic 3D Page Turn
Offline Library EPUB Typography 3D Page Turn
Instant Library Indexing
Parallel Rust walkdir storage scan, "Continue Reading" shelf, and format filtering.
Native Non-WebView Engine
Reflowable text in native Flutter widgets with custom margins and book textures.
120 FPS Physics Curl
Hardware-accelerated page curls with dynamic lighting and ambient shadow simulation.
04. Rich In-Text Annotations 05. Annotations Hub 06. Synchronized Text-to-Speech 07. Custom Collections
Annotations Annotations Hub Synchronized TTS Collections
5-Color Highlighter
Yellow, coral, green, blue, and purple highlighting with instant note attachments.
Centralized Notes Store
Global review hub organizing all quotes, notes, and chapter bookmarks locally.
Non-Blocking TTS
Sentence lock tracking with floating audio controls running on native worker threads.
Android SAF Storage
Scoped storage compliant directory mapping and custom reading shelf organization.

Key Features

  • Screen-Fitted Paging Engine: SafeScreenPaginator partitions reflowable EPUB, MOBI/AZW, and TXT chapters into viewport-fitted PageSlice units using paragraph budgeting and dynamic text measurement. EpubPagedViewer, MobiPagedViewer, and TxtPagedViewer use pure screen-sized PageView.builder widgets for both horizontal and vertical reading modes, with seamless chapter boundary swapping.
  • Precision Typography & Offset Resolution: Stateless TextOffsetResolver and centralized ReaderTypographyMetrics guarantee 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 (RealisticPageTurn and AppleBooksPageCurl) 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.

Spatial Dimensions

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.

Supported Formats

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

Architecture

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
Loading

Separation of Concerns

  • 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-rs with pure-Rust crypto).
    • Text segmentation and tokenization for sentence-level TTS highlighting across reflowable formats.
    • Automated character encoding detection (chardetng and encoding_rs) for plain text files.

Technical Specifications

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

Prerequisites

Before building Ferrous, ensure the following tools are installed on your host system:

  • Flutter SDK: 3.44.0 or higher (Installation Guide)
  • Rust Toolchain: 1.80.0 or 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 r26d or r26b (configured via ANDROID_NDK_HOME)
  • JDK: Java Development Kit 17 (Temurin recommended)
  • flutter_rust_bridge_codegen:
    cargo install flutter_rust_bridge_codegen --version 2.11.1

Getting Started

Follow these steps to set up the development environment, compile dependencies, and run Ferrous on an Android device or emulator:

1. Clone the Repository

git clone https://github.com/JuanSoFly/Ferrous.git
cd Ferrous

2. Configure Environment (Optional)

If you use local tool paths, you can source the environment helper:

source ./setup_env.sh

3. Fetch Flutter Dependencies

flutter pub get

4. Generate Bridge Bindings

Generate the type-safe FFI glue code between Dart and Rust:

flutter_rust_bridge_codegen generate

5. Install PDFium Binaries

Ferrous 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.sh

Tip

If developing on an Android emulator, include x86_64:

PDFIUM_ABIS="arm64-v8a,x86_64" bash scripts/setup-pdfium-android.sh

For offline manual setup instructions, refer to docs/pdfium-setup.md.

6. Run the App

Connect an Android device with USB debugging enabled (or start an emulator) and execute:

flutter run

Building Releases

To generate optimized Android production packages:

Split APKs (Recommended)

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-icons

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

Android App Bundle (AAB)

For distribution through Google Play:

flutter build appbundle --release --obfuscate --split-debug-info=build/app/outputs/symbols

Output: build/app/outputs/bundle/release/app-release.aab


Project Structure

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)

Troubleshooting

Missing PDFium Library (dlopen failed)

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.

Out-of-Sync FFI Bindings

If you modify files under rust/src/api/, re-run the code generator to update the Dart bindings:

flutter_rust_bridge_codegen generate

Diagnostic Logging & Issue Reporting

If you encounter unexpected errors or format parsing issues:

  1. Open Settings > Diagnostic Logs inside the app to inspect the runtime trace.
  2. Select Feedback / Report Issue to copy the sanitized diagnostic stack directly to your clipboard.
  3. Paste the diagnostic trace into the GitHub Issues report template for expedited triage.

Ferrous Reader Release Download Trends

About

A high-performance, offline-first e-reader for Android built with a hybrid Flutter + Rust architecture. Supports PDF, EPUB, DJVU, MOBI, CBZ, and DOCX

Topics

Resources

Stars

12 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages