OPDS
Open Publication Distribution System (OPDS) is a specification for generating and serving catalogs of digital content. It is used by many applications, such as Panels and Chunky Reader.
So long as an OPDS client properly implements the OPDS specification, you should be able to use it with Stump. Each OPDS client might have a different way of collecting this information during their onboarding steps. If you have any trouble using your preferred client, please open an issue on GitHub or feel free to pop into the Discord for help. This page can be updated with your findings to help others in the future.
Supported OPDS Versions
Stump fully supports OPDS 1.2 and has experimental support for 2.0. At the time of writing, there are few clients which actually support 2.0, so it is difficult to test. If you have any experiences with OPDS 2.0, please consider updating this page with your findings!
OPDS 1.2
The general structure of the URL to connect to your Stump server is:
http(s)://your-server(:10801)(/baseUrl)/opds/v1.2/catalog
Tested Clients
Note: The ✨ emoji indicates a client which the developer of Stump personally uses
The following clients have been tested with Stump:
| OS | Application | Page Streaming | Issues/Notes |
|---|---|---|---|
| iOS | Panels | ✅ | ✨ |
| iOS | Chunky Reader | ✅ | |
| Android | Moon+ Reader | ❌ | Users report OK experience |
| Android | KyBook 3 | ❌ | No testing at this time |
| Android | Librera | ❌ | Supports covers, categories, and downloads, but shows file names not book titles |
| Android | Cantook by Aldiko | ❌ | No auth support, does not work. Use 2.0 |
| Linux | Foliate | ❌ | Loads cover previews, file names and categories |
| Windows | Thorium 3 | ❌ | Loads cover previews, file names and categories |
If you have any experiences, good or bad, using any of these clients or another client not listed here, please consider updating this page with your findings.
Using an API Key
This functionality is gated behind the feature:api_keys user permission. To learn more about
permissions, see the permissions guide.
There is a special router for OPDS v1.2 that allows you to embed an API key in the URL directly. This is primarily only done to support clients which do not support passing auth credentials in the request headers. The URL structure for this is:
http(s)://your-server(:10801)(/baseUrl)/opds/(api_key)/v1.2/catalog
For additional information on API keys, see the API keys guide.
OPDS 2.0
The general structure of the URL to connect to your Stump server is:
http(s)://your-server(:10801)(/baseUrl)/opds/v2.0/catalog
Stump hasn’t implemented facets support yet, but it is planned for a future release once I
understand what they actually are
Tested Clients
The following clients have been tested with Stump:
| OS | Application | Page Streaming | Issues/Notes |
|---|---|---|---|
| iOS & Android | Stump | ✅ | Actively being developed, experimental |
| iOS | Cantook by Aldiko | ❓ | Supports catalog traversal and media downloads. Issues with rendering media covers, however this appears to be an issue on their end |
| Android | Cantook by Aldiko | ❓ | Supports catalog traversal and media downloads. Issues with rendering media covers, however this appears to be an issue on their end |
| Android | Librera | ❓ | Does not work. Likely lacking OPDS 2.0 support |
| Linux | Foliate | ❌ | Loads cover previews, book names, publisher and categories |
| Windows | Thorium 3 | ❌ | Loads covers and their previews, book names, publisher and categories |