Name
lijn-opds — OPDS catalog configuration reference
Synopsis
Add OPDS catalogs from Settings > Catalogs or from the library’s catalog browser. A Project Gutenberg catalog is preconfigured on first launch.
Description
Lijn supports OPDS 1.x (Atom/XML) catalog browsing and acquisition feed download. OPDS 2.0 (JSON) is detected and rejected with a hint to use the server’s 1.x endpoint instead.
Adding a Server
| Name | Display name (also drives default path and icon detection) |
| URL | Root catalog URL; bare host:port is prefixed with http:// |
| Icon | Picked manually or auto-detected |
| Login | Optional username and password (Basic Auth) |
Quick-start presets: Stump (/opds/v1.2), Komga (/opds/v1.2/catalog), Kavita (/api/opds). A Test Connection button validates before saving.
If the URL has no path and the root returns 404 or non-OPDS content, these paths are probed in order:
/opds/v1.2/catalog, /opds/v1.2, /api/opds, /opds, /opds/catalog
Authentication
HTTP Basic Auth only. Credentials are Base64-encoded in the Authorization header. Passwords are stored in the device Keychain, local-only — they do not sync to other devices.
401 responses are reported as “authentication required”. 403 responses are reported as “authentication failed”.
Browsing
The catalog root renders smart-folder cards: feed entries are classified by href path and title keywords into Continue Reading, Recent, Hot, Authors, Series, Genres, Collections, All Books, and more. Calibre content-server hex-encoded navigation catalogs are decoded. Classification is verified against the feed sources of calibre-web, Calibre, Komga, Kavita, and Stump.
Navigation is hierarchical with continuous-scroll pagination (rel="next"). The last successful feed for each URL is cached on disk and rendered first, so catalogs open instantly and stay browsable offline.
Facets
OPDS facet links are grouped and exposed as a filter menu in the browser toolbar; the active facet is checkmarked.
Search
If the server advertises a search link, Lijn resolves the OpenSearch description document (or uses a templated href directly) and substitutes the query. Available from the browser search bar.
Download
Acquisition links are prioritized in this order:
CBZ > PDF > CBR > EPUB
Downloads run on a background URLSession with byte-level progress and survive app relaunch. The complete file must download before reading can begin (no streaming; OPDS-PSE page-streaming links are recognized but not used for reading).
Downloaded files are imported into the local library with metadata and cover extraction, Spotlight indexing, and widget updates. Re-downloading an already-imported entry is detected and skipped. When browsing a series feed, the series name from the browse context is applied (Calibre omits it from entries).
Server Persistence
Server configurations are stored locally in UserDefaults; passwords in the local Keychain. Nothing syncs across devices.
Network
Plain HTTP is allowed for local and self-hosted servers only (NSAllowsLocalNetworking). Public catalogs must use HTTPS.
Supported Features
| Navigation feeds | Yes |
| Acquisition feeds | Yes |
| OpenSearch | Yes |
Pagination (rel="next") | Yes |
| Facet links | Yes (toolbar filter menu) |
| Thumbnail/cover images | Yes (cached, deduplicated fetches) |
| Download with progress | Yes (background, survives relaunch) |
| Offline feed cache | Yes (last successful feed per URL) |
| OPDS 2.0 (JSON) | No |
| DRM / LCP | No |
| Streaming / partial read | No |
Known Limitations
- OPDS 2.0 JSON feeds are not parsed
- DRM-protected content cannot be opened
- The full file must download before reading begins
- Only HTTP Basic Auth is supported (no OAuth, no API keys)
- MOBI acquisition links are recognized but not selected for download; CBZ/PDF/CBR/EPUB are the download targets
Compatible Servers
Verified against: Calibre Content Server / Calibre-Web, Kavita, Komga, and Stump. Any OPDS 1.x compliant server should work. A Project Gutenberg catalog ships preconfigured.
See Also
Author
Aymane Bengrina — Studio Alticcio
alticc.io