Readwyn 0.1.0

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

FeedKindWhat it lists
The rootnavigationYour libraries, each with its book count
A librarynavigationRecently added, Currently reading, By author, By series, By shelf, and All books
Recently addedacquisitionThe books, newest first
All booksacquisitionThe books by title
By author, By series, By shelfnavigationThe authors, series, or shelves, each with a book count
One author or shelfacquisitionIts books by title
One seriesacquisitionIts books by their number in the series
SearchacquisitionThe 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

Settings › Other devices › Reader apps: the switch Share with reader apps (OPDS) is on, the address http://192.168.1.20:7314/opds with Copy and port 7314, a warning about the Wi-Fi, and three reader apps
The catalogue in Settings › Other devices

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.