251 lines
8.8 KiB
Markdown
251 lines
8.8 KiB
Markdown
<div align="center">
|
|
|
|
<img src="res/logo.png" alt="Worldhopper Logo" width="200"/>
|
|
|
|
# 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.
|
|
|
|
[](https://www.android.com)
|
|
[](https://flutter.dev)
|
|
[](LICENSE)
|
|
|
|
</div>
|
|
|
|
## 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.
|
|
|
|
<div align="center">
|
|
|
|
|
|
|
|
</div>
|
|
|
|
## 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)
|
|
```bash
|
|
# Follow official Flutter installation guide
|
|
# https://flutter.dev/docs/get-started/install
|
|
```
|
|
|
|
2. **Clone the repository**
|
|
3. **Install dependencies**
|
|
```bash
|
|
flutter pub get
|
|
```
|
|
|
|
4. **Run the application**
|
|
```bash
|
|
# 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!
|