What is OPDS, and how do reader apps use it?
OPDS is a format for catalogues of ebooks. A catalogue is a set of web feeds that a reader app on a phone, a tablet, or an e-reader can browse: lists of authors, series, and books, each book with its cover, its details, and links to download its files. Readwyn serves an OPDS catalogue of your own libraries, so reader apps such as KOReader, Thorium, Moon+ Reader, Panels, and Chunky can browse them and download books over your home network.
Two kinds of feed
An OPDS 1.2 catalogue (the specification) is made of Atom feeds, and Readwyn’s come in two kinds:
- A navigation feed lists other feeds: your libraries, or the authors of a library.
- An acquisition feed lists books. Each book entry links to its cover and its files.
A reader app starts at the root of the catalogue and follows the links. In Readwyn, the root’s address ends in /opds, for example http://192.168.1.20:7314/opds.
Readwyn’s feeds
| Feed | Kind | What it lists |
|---|---|---|
| The root | navigation | Your libraries, each with its book count |
| A library | navigation | Recently added, Currently reading, By author, By series, By shelf, and All books |
| Recently added | acquisition | The books, newest first |
| All books | acquisition | The books by title |
| By author, By series, By shelf | navigation | The authors, series, or shelves, each with a book count |
| One author or shelf | acquisition | Its books by title |
| One series | acquisition | Its books by their number in the series |
| Search | acquisition | The books whose title, authors, or series match |
If you keep one library, the root opens it at once. Currently reading shows up only for a reader app that you’ve allowed to see it.
Search and pages
Every feed links to itself and to the start of the catalogue, and a feed inside a library links up to that library. Each one also points to the search, in two forms: an OpenSearch description, and a template that puts your words in the address.
Long feeds are split into pages of 50 books, or 100 names. A page links to the first, last, previous, and next pages, and gives the total number of results.
A book entry
A book entry in Readwyn’s catalogue carries the title, authors, date added, languages, publisher, publication date, ISBN, genres, a cover and a thumbnail, and the description. OPDS 1.2 has no element for a series, so Readwyn puts the series and its number at the start of the text, for example “The Expanse, book 2”.
Each format of the book is one download link, with its file type and size: the EPUB 3 that Readwyn converted comes first, then the original file (which one to take). A comic has only its CBZ, CB7, or CBT archive.
How Readwyn serves it

Readwyn speaks OPDS 1.2 over plain HTTP, not OPDS 2.0. The catalogue is read only: a reader app can download books and covers but can’t change anything. Every request has to carry one reader app’s user name and password (HTTP Basic), which Readwyn makes for each app in “Add a reader app…”. Reader apps have the Guest level, so the feeds show no status, progress, rating, or review.
The catalogue has its own port, 7314 by default, next to the 7313 that paired Macs use, and it works on your home network only. The Readwyn app serves it while “Readwyn server” and “Share with reader apps (OPDS)” are both on (the steps, with KOReader). The headless server for Linux, ryn-server, can’t serve reader apps yet.
The catalogue stays quick in a big library. Readwyn timed every kind of feed page against a library of 60,000 books: with the library’s files already in the system’s file cache, no page took more than 45 ms.