quickopds 0.1

Configuration-free script that statically creates an OPDS feed for a directory containing ebooks.

quickopds

Python script that statically creates an OPDS feed for a directory containing ebooks. No configuration needed. Results are ready for hosting on a web server.

What is OPDS?

If you have some ebook files that are hosted on the internet, you can create an OPDS feed so that they can be accessed from ereader devices and apps that understand OPDS, making navigation and discovery simple. In this way, it's just like a podcast feed, except it's for ebooks instead of audio files.

An OPDS feed is an XML file hosted along with the ebooks, which contains structured data about the books. quickopds can generate this XML file for you.

For a list of devices supporting the OPDS protocol, see https://github.com/opds-community/awesome-opds

Installation

The easiest way is via pipx. Just type:

pipx install quickopds

and the quickopds command should be available in your path.

Usage

The simplest way to use this is to open a terminal, navigate to a directory containing ebooks, and run

quickopds --url https://your-domain.here/path/to/ebooks

replacing the above URL with the URL where you intend to serve this directory.

This will search for books in the current directory, generate an OPDS feed and put it in this directory as index.xml using some sensible defaults. If you host this directory at the URL you specified, it should work as a valid OPDS server.

If you add any books to this directory in the future, you just need to run the same command again, and the feed will be regenerated using the new contents of the directory.

The full usage is as follows:

usage: quickopds [-h] [--url URL] [--title TITLE] [--author AUTHOR] [directory]

Statically generate an opds ebook feed for a directory

positional arguments:
  directory        path to the local directory containing the ebooks (default current working directory)

options:
  -h, --help       show this help message and exit
  --url URL        url where the feed will be hosted (default https://example.com/ebooks)
  --title TITLE    title for the feed (default 'My ebook catalog')
  --author AUTHOR  named owner of the feed (default 'quickopds')

Supported file formats

Supported ebook formats are epub, azw3, pdf, html, and txt. Supported image formats (for book covers) are jpeg, png and gif. Additional formats could be added to the source code easily.

Files that only differ by their filename extension will be treated as different formats of the same book. Image formats will be treated as cover images for the book. There's also support for the special filename styles used by Standard Ebooks: _advanced.epub and .kepub.epub.

Styling

The script will also generate a file called style.xsl, which will be saved along with the index.xml feed. This gives you a human-readable webpage for free, since loading the xml file in a web browser will now display the whole feed in a human-readable way, with clickable links to download books.

Apache configuration

If you're running an Apache web server, you can add

DirectoryIndex index.xml

to an .htaccess file in this directory, so that index.xml is served at the directory URL you specified. This means that you can access the feed directly via a URL like https://your-domain.here/path/to/ebooks without needing to append /index.xml.

Example

An example of a feed generated by quickopds is hosted at https://myoung.uk/ebooks. Feel free to take a look.

Missing features

This is a quick OPDS feed, focusing on simplicity and ease of setup, with almost no configuration available, and few advanced features. It doesn't support:

• Custom metadata insertion
• Custom HTML styling
• Search functionality
• Categories
• Proper image thumbnails
• Running as a service

However, note that the generated file is just a simple XML file, so you can modify it easily by hand to do some of the more basic stuff.

More fully featured OPDS servers can be found at https://github.com/opds-community/awesome-opds.