discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
Swappppy/Openshelf · source
Snapshot 0 · 2026-11-04T12:47:28Z · Dart · GPL-3.0
Content fingerprint
23ac6cfaf120a3174d5585672d06ca791357a555fecd9fd839c8ec9a2222b652GitHub description at capture
Openshelf is a free, open-source personal library manager. It functions as a comprehensive reading tracker, organizer (by category, collection, imprint, or any combination), and book archival tool. Everything stays on your device, no account required, and no data ever leaves your phone.
README at capture
# Openshelf
[](LICENSE)
[](https://flutter.dev)
[](#-technical-stack)
<img src="assets/Screenshots/Openshelf-banner-en.png" alt="Openshelf Banner">
**Your library. Your data. Your app.**
Openshelf is a free, open-source personal library manager. It functions as a comprehensive reading tracker, organizer (by category, collection, imprint, or any combination), and book archival tool. Everything stays on your device, no account required, and no data ever leaves your phone.
---
## My Intention
I built Openshelf as the definitive app for book archival and tracking. As a collector with a large library, I found every alternative lacking features, hidden behind paywalls, or cluttered with ads.
Openshelf is designed for **book lovers**, not just readers. It is for people who care about the craftsmanship of managing a personal collection. While the open-source stack has some limits in database depth compared to proprietary giants, Openshelf strives to deliver the best experience with high-quality FOSS tools.
---
## Download
[<img src="https://fdroid.gitlab.io/artwork/badge/get-it-on.png" alt="Get it on F-Droid" height="80">](https://f-droid.org/en/packages/org.ftena.openshelf/)
[<img src="assets/github/get-it-on-github.png" alt="Get it on GitHub" height="80">](https://github.com/Swappppy/Openshelf/releases/latest)
Latest release: **v1.4.1**
---
## Roadmap
<img src="assets/Screenshots/Openshelf-roadmap-en.png" alt="Openshelf Roadmap">
This is a brief roadmap showing what has already been done and what is to come.
I would also like to thank everyone using this app and waiting for future updates. I never thought
that anyone but me would use it, so a big THANK YOU to all of you!
---
## Screenshots
<img src="assets/Screenshots/Openshelf-en/1.png" width="300" alt="Library View - List Layout"> | <img src="assets/Screenshots/Openshelf-en/2.png" width="300" alt="Library View - Grid Layout"> | <img src="assets/Screenshots/Openshelf-en/3.png" width="300" alt="Book Details View"> | <img src="assets/Screenshots/Openshelf-en/4.png" width="300" alt="Statistics Dashboard">
---
## Features
### Library
- **Dynamic Views**: Instant toggle between List and Grid layouts.
- **Reading Status**: Five trackable states: *Want to read, Reading, Read, Abandoned, and Paused*.
- **Powerful Search**: Full-text search across Title, Author, ISBN, and personal notes among other advanced filtering.
- **Granular Control**: Cascading ordering in every book or tag list (each with custom ordering).
- **Dynamic Properties**: Enable, disable, or rearrange book fields in the library view at will.
### Books
- **Custom Covers**: Search via multiple APIs, or use a URL, photo, or gallery for custom covers.
- **Extensive Metadata**: Manage categories, imprints (exclusive), and collections (exclusive).
- **Interactive Forms**: Quick page updates via a **scrollable drum picker** and quick notetaking with infinite space.
- **Progress Tracking**: Automatic reading dates and status updates based on your current page.
- **Dynamic Tags**: Every category, imprint, and collection is fully interactive and searchable within the book form.
### Smart Shelves
- **Live Views**: Save any filter combination as a self-updating smart shelf.
- **Progress Bars**: Automatic progress indicators for shelves and relevant tags.
- **Visual Mosaics**: Custom mosaic cover displays for your collections.
### Categories
- **Flexible Management**: Add categories via the dedicated page or directly in the book form.
- **Visual Cataloging**: Optional colors for easy identification.
- **Cloud View**: Algorithmic sizing based on book count, using a user-adjustable curve.
- **Graphic Picker**: Intuitive visual selector within the book form.
### Imprints
- **Professional Branding**: Support for 1:1 logo images or initial-based placeholders.
- **Dedicated Progress**: Each imprint tracks its own reading progress bar.
### Collections (Series)
- **Saga Tracking**: Custom cover fade displays for series.
- **Numbered Ordering**: Collections store and display both the name and the book number in the series.
- **Progress Tracking**: Each collection has its own dedicated progress bar.
### Statistics
- **Custom Dashboard**: Dedicated stats page with reorganizable and resizable widgets.
- **Interactive Widgets**:
- **Streak (1x1)**: Tracks how many days in a row you have read.
- **Pages (1x1)**: Total volume of pages in your library.
- **Goals (1x1 & 2x1)**: Set targets by pages, books, or shelves. Supports multiple goals via swipe with custom progress bars and cover-based backgrounds.
- **States (1x1)**: Visual distribution across the five reading states.
- **Now Reading (1x1 & 2x1)**: Swipable and interactable list of active reads.
- **Added Books (2x2, 2x1, 1x1)**: Temporal graph of acquisitions.
- **Categories (2x2, 1x2)**: Top 10 genres with names, counts, and colors.
- **Publishing Year (2x2, 1x2, 2x1)**: Historical bar graph of your library's timeline.
- **Reading History (2x2, 1x2)**: Yearly breakdown of books finished.
- **Collections (2x2, 1x2)**: Distribution across your top collections.
- **Last Added (1x2, 2x1, 1x1)**: Scrollable list of recent arrivals.
- **Average Length (1x1)**: Average pages per book.
- **Period Highlights (2x2, 1x2)**: Customizable breakdown of books read (Last month, 3 months, year, or 3 years).
- **Reading Speed (1x1)**: Average days to complete a book.
- **Haptic Feedback**: Tactile UI interactions for a premium, responsive feel.
---
## APIs
Openshelf orchestrates multiple providers simultaneously to ensure high-confidence metadata:
- **[Open Library (FOSS)](https://openlibrary.org)**: Primary source for book metadata and high-quality covers.
- **[Inventaire (FOSS)](https://inventaire.io)**: Secondary source focused on linked open data and deep edition lookups.
- **[Google Books](https://books.google.com)**: Optional proprietary source (requires a free API key).
The app implements a **four-step high-confidence lookup** (ISBN -> Title+Publisher -> Title+Author -> Deep Dive) to ensure you always get the best possible record.
---
## Technical Stack
Openshelf is built using modern Flutter development practices with a 100% on-device architecture:
- **Framework**: [Flutter](https://flutter.dev/) (Multi-platform UI).
- **State Management**: [Riverpod](https://riverpod.dev/) (Reactive, thread-safe state handling).
- **Local Database**: [Drift](https://drift.simonbinder.eu/) (High-performance reactive SQLite wrapper).
- **OCR Engine**: [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) (100% FOSS).
- **Scanning**: [Mobile Scanner](https://pub.dev/packages/mobile_scanner).
---
## Key Code Features
### Hybrid FLOSS Scanner (Dual-Mode)
To avoid hardware conflicts and provide maximum precision, the scanner implements a mutually exclusive system:
- **Barcode Mode**: High-speed line detection for traditional ISBN barcodes.
- **ISBN Mode (OCR)**: Optimized Tesseract engine tuned with **Page Segmentation Mode (PSM) 7** for single-line recognition. It utilizes **background Isolates** and **lossless PNG processing** to ensure the UI remains at 60fps while recognizing complex or wide fonts.
### Zero-Flicker Transitions
The Library view implements a custom `AnimatedSwitcher` logic combined with Riverpod's `skipLoadingOnRefresh`. This allows for a **seamless cross-fade** between List and Grid layouts without any black background flicker or loading spinners, maintaining existing data on screen while the new layout initializes.
### Intelligent Image Management
- **Smart Cover Cropping**: Automatic ratio detection (2:3) when downloading covers; triggers a dynamic crop tool if the ratio is off.
- **Background Compression**: Automatic JPEG optimization (max-height 1000px, 75% quality) to keep app storage lean.
- **Lossless Buffer**: Internal use of PNG during OCR processing to ensure zero artifact noise for the recognition engine.
### Polymorphic Database Tags
Built on **Drift**, the database uses a polymorphic tag system. A single `Tags` table manages Categories, Imprints, and Collections via a type discriminator. This allows for unified search queries and complex filtering with minimal overhead.
---
## Known Issues
- [Crash on launch on GrapheneOS](KNOWN_ISSUES.md#crash-on-launch-on-grapheneos)
- FIXED - [Error when manually migrating a database from v1.1.1 to v1.2.2](KNOWN_ISSUES.md#error-when-importing-library-from-v111-to-v122-untested-for-other-versions)
See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for details and workarounds.
---
## Translations
Openshelf uses **[Weblate](https://hosted.weblate.org/projects/openshelf/)** for community translations. English and Spanish are built-in.
> [!NOTE]
> Many strings have been translated using AI to improve the app's reach and accelerate localization efforts.
>
> If you are a native speaker and notice anything that sounds a bit "off", please let me know or update it directly on Weblate.
>
> Currently, this includes French, Italian, Catalan, and Portuguese. I speak Catalan myself and those look good to me, if this approach works for you, I'll continue adding more languages. The more the merrier!
<a href="https://hosted.weblate.org/engage/openshelf/">
<img src="https://hosted.weblate.org/widgets/openshelf/-/multi-auto.svg" alt="Translation status" />
</a>
> [!TIP]
> To contribute a new language or improve existing ones, visit the [Openshelf project on Weblate](https://hosted.weblate.org/projects/openshelf/).
---
## Contributing
Bug reports, feature requests, and pull requests are welcome!
1. Please open an issue first for anything beyond small fixes.
2. Follow standard Flutter/Dart conventions.
3. Run `flutter analyze` before submitting a PR.
---
## License
Openshelf is licensed under the **GNU General Public License v3.0**. See the [LICENSE](LICENSE) file for more details.
---
*Developed for book lovers.*