Ferrous

Ferrous Reader

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

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

Download

Precompiled Android packages (APKs) are available on the GitHub Releases page, or automatically via Obtainium:

[!NOTE] Verifying Release Integrity: Every GitHub Release includes an official SHA256SUMS.txt manifest as well as individual .sha256 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-v<version>-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, low memory overhead, and typography control. By combining a reactive Flutter front-end with an asynchronous Rust backend via flutter_rust_bridge (v2), Ferrous offloads computationally intensive workloads—such as PDF parsing, full-storage indexing, archive decompression, and text tokenization—to background native threads, keeping UI animations and page interactions fluid at 120Hz.

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

• Blazing Fast File Indexing: Scans device storage and Storage Access Framework (SAF) trees in seconds via parallel directory traversal in Rust (walkdir).
• Smooth 120Hz UI: Heavy I/O and document decoding run asynchronously outside the UI isolate on a Rust thread pool (tokio), avoiding frame drops.
• Hardware-Accelerated PDF Rendering: Powered by Google PDFium via pdfium-render, generating thread-safe bitmaps directly for Flutter textures.
• Native Non-WebView EPUB Engine: Renders reflowable book content directly into a native Flutter widget tree with hyphenation and full typography control.
• Synchronized Text-to-Speech (TTS): Integrated TTS with dynamic word and sentence highlighting across page boundaries and chapters.
• Granular Library Management: Multi-directory library location support via Android Storage Access Framework (SAF), collection grouping, advanced sorting, and format filtering.
• Material 3 Design: Dynamic color palette adaptation, customizable themes, reading progress persistence, and animated shimmer placeholders.

Supported Formats

Architecture

Ferrous utilizes a hybrid boundary model where Flutter handles UI composition and state presentation, while Rust manages high-throughput, latency-critical operations.

Separation of Concerns

• Flutter (Frontend):
  • Material 3 user interface with dynamic theme switching and smooth gesture interactions.
  • Responsive reading screens for both paginated and continuous scroll modes.
  • Hive NoSQL database for instant bookmarking, reading progress tracking, and collection management.
• Rust (Backend):
  • Multi-threaded, non-blocking I/O operations powered by tokio.
  • PDFium binding management with safe, asynchronous document loading and page caching.
  • Archive reading (zip) for fast on-the-fly cover extraction without writing temporary files to disk.
  • Text segmentation and tokenization for sentence-level TTS highlighting.

Technical Specifications

Prerequisites

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

• Flutter SDK: 3.24.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

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

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:

flutter build apk --split-per-abi --release

Outputs are generated in: build/app/outputs/flutter-apk/

• app-arm64-v8a-release.apk (modern 64-bit devices)
• app-armeabi-v7a-release.apk (legacy 32-bit devices)
• app-x86_64-release.apk (emulators & ChromeOS)

Android App Bundle (AAB)

For distribution through Google Play:

flutter build appbundle --release

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

Project Structure

Ferrous/
├── .github/workflows/       # CI/CD automated release pipelines
├── android/                 # Android native project & SAF integration
│   └── app/src/main/jniLibs # Target ABI native libraries (libpdfium.so)
├── assets/                  # Application launcher icons & visual assets
├── docs/                    # Technical guides (PDFium setup, architecture notes)
├── lib/                     # Flutter / Dart presentation layer
│   ├── app/                 # Application shell & routing
│   ├── core/                # Models, utilities, constants, and widgets
│   ├── data/                # Repositories & Hive database services
│   ├── features/            # Feature modules (library, reader, collections, settings)
│   └── src/rust/            # Generated Dart FFI bridge code
├── rust/                    # Native Rust compute crate
│   ├── Cargo.toml           # Rust crate dependencies & release profiles
│   └── src/api/             # Rust exposed API modules (PDF, MOBI, CBZ, TXT, DOCX, scanning)
├── rust_builder/            # Cargokit integration layer for cross-compiling Rust
└── scripts/                 # Automation scripts (setup-pdfium-android.sh)

Troubleshooting

Missing PDFium Library (dlopen failed)

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