Worldhopper

Your gateway to digital reading through OPDS

A modern, feature-rich Android application for browsing and reading comics, manga, and books from OPDS servers.

About Worldhopper

Worldhopper is a powerful yet intuitive mobile application designed for readers who want seamless access to their digital library through OPDS servers. Whether you're reading manga, comics, or books, Worldhopper provides a smooth, immersive experience with intelligent features that adapt to your content.

What is OPDS?

OPDS (Open Publication Distribution System) is an open standard for distributing digital publications. It allows you to connect to any OPDS-compatible server and access your entire library through a single, unified interface.

What is OPDS-PSE?

OPDS-PSE (Page Streaming Extension) is an extension to OPDS that enables efficient streaming of individual pages from comics and manga. Worldhopper fully supports OPDS-PSE, providing optimized reading experiences for image-based publications.

Who is Worldhopper for?

• Comic readers who want a dedicated app for their digital collection
• Manga enthusiasts seeking a smooth reading experience
• Book lovers with OPDS-enabled libraries
• Self-hosters running their own media servers
• Privacy-conscious readers who prefer local storage over cloud services

Key Features

• Multiple OPDS servers with HTTP Basic Authentication support
• Browse catalogs with grid view, cover art, and pull-to-refresh
• Dual reading modes - Image viewer for comics/manga, EPUB reader for books
• Automatic progress tracking - Resume exactly where you left off
• Offline reading with intelligent caching and download management
• Light and dark themes with Material Design 3
• Fullscreen reading with zoom, pan, and smooth page navigation

QoL features

Guess the next chapter in OPDS catalogs

The app can guess the next chapter in OPDS catalogs based on the current chapter's title and the titles of the next few chapters. This feature helps users navigate through their library more efficiently when a chapter is finished.

Supported Formats

Format	Description	Use Case
OPDS Catalog	Standard Atom feeds	Server discovery and navigation
OPDS-PSE	Page Streaming Extension	Comics and manga with streamed pages
EPUB	Electronic Publication	Books and text-based content
Image Streams	JPEG, PNG, GIF sequences	Comics, manga, and graphic novels

Getting Started

Prerequisites

• Android device running Android 6.0 (Marshmallow) or higher
• OPDS server with accessible URL and credentials (if required)
• Internet connection for initial setup and browsing

Installation

Building from Source

1. Install Flutter (version 3.0 or higher)

   # Follow official Flutter installation guide
   # https://flutter.dev/docs/get-started/install
   

2. Clone the repository

3. Install dependencies

   flutter pub get
   

4. Run the application

   # For development
   flutter run
   
   # For release build
   flutter build apk --release
   

---

How to Use

First-Time Setup

1. Launch Worldhopper on your Android device
2. Add your first OPDS server
   • Tap the "Add Server" button
   • Enter the server URL (e.g., https://your-server.com/opds)
   • Provide authentication credentials if required
   • Save the server configuration
3. Browse your library
   • Navigate through collections and categories
   • Use pull-to-refresh to update content
4. Select a publication
   • Tap on any cover to view details
   • Check description, authors, and metadata
5. Start reading
   • Tap "Read" to begin
   • Swipe or tap to navigate pages
   • Use pinch-to-zoom for detailed views

FAQ

Where is my data stored?

All your data is stored locally on your Android device. This includes:

• Server configurations and credentials
• Reading progress and history
• Cached images and downloaded content
• User preferences and settings

Nothing is synced to the cloud or transmitted to external servers except when fetching content from your configured OPDS servers.

Does it work offline?

Yes, partially. Once you've opened a publication and pages have been cached, you can continue reading that content offline. However, browsing the catalog and discovering new content requires an internet connection to communicate with your OPDS server.

What OPDS servers are supported?

Worldhopper supports any standards-compliant OPDS server, but so far I have only tested it with Kavita.

How do I add authentication?

When adding a server, simply fill in the "Username" and "Password" fields. Worldhopper uses HTTP Basic Authentication, which is supported by most OPDS servers. Your credentials are stored securely on your device.

Can I read books as well as comics?

Yes! Worldhopper automatically detects whether a publication is:

• An EPUB book - Opens in the integrated EPUB reader
• An image stream (comic/manga) - Opens in the image viewer

The app seamlessly handles both content types.

What if my server doesn't support OPDS-PSE?

That's fine! OPDS-PSE is an optional extension. If your server provides:

• Standard OPDS catalogs, Worldhopper will browse them
• EPUB files, they'll open in the EPUB reader
• ZIP archives of images, they can be streamed as individual pages

Is my reading progress synced between devices?

Currently, reading progress is stored locally on each device. Cross-device synchronization is not supported at this time. Each device maintains its own independent reading history.

How much storage does the app use?

The app itself is lightweight. Storage usage depends on:

• Number of cached pages from your reading sessions
• Downloaded content you've saved for offline access
• Thumbnail images for browsing

You can manage cached content through your device's app settings.

---

Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or suggesting ideas, your input helps make Worldhopper better for everyone.

Reporting Bugs

Found an issue? Please open an issue with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Device information (Android version, device model)
• Screenshots if applicable

Suggesting Features

Have an idea for improvement? We'd love to hear it!

• Check existing issues to avoid duplicates
• Describe the feature and its benefits
• Explain your use case
• Consider potential implementation approaches

Development Setup

Requirements:

• Flutter SDK 3.0 or higher
• Android Studio or VS Code with Flutter extensions
• Android device or emulator for testing

Setup Steps:

1. Fork the repository
2. Clone your fork locally
3. Create a feature branch (git checkout -b feature/amazing-feature)
4. Make your changes
5. Test thoroughly on Android devices
6. Commit with clear messages (git commit -m 'Add amazing feature')
7. Push to your fork (git push origin feature/amazing-feature)
8. Open a Pull Request

Pull Request Process

1. Update documentation - Reflect any changes in README or code comments
2. Follow code style - Use consistent formatting and naming conventions
3. Test your changes - Ensure everything works on Android
4. Describe your PR - Clearly explain what and why you changed
5. Link related issues - Reference any issues your PR addresses
6. Be responsive - Address review feedback promptly

Code Style Reference

• Follow Dart's official style guide
• Use meaningful variable and function names
• Add comments for complex logic
• Keep functions focused and single-purpose
• Write tests for new features when applicable

Technologies Used

• Flutter & Dart - Primary framework and language
• sqflite - Local SQLite database
• http - Network requests to OPDS servers
• flutter_cache_manager - Image caching and storage
• flutter_epub_viewer - EPUB reading functionality
• xml - OPDS feed parsing
• provider - State management

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

• Be respectful and constructive in discussions
• Welcome newcomers and help them get started
• Focus on what's best for the community
• Show empathy towards other contributors

Thank you for helping make Worldhopper better!