ReadMeABook: an audiobook request pipeline for Plex and Audiobookshelf

The request to library loop, in one box

ReadMeABook is described as a fully featured audiobook request and downloading engine, and the summary line at the top of the readme is a formula worth reading twice: Radarr and Sonarr for audiobooks, all in one.

The problem it solves is a pipeline with many manual handoffs. You run Plex or Audiobookshelf with audiobooks. You want more audiobooks. You search indexers, download torrents or NZBs, organise the files, and wait for your server to scan them. The project's own description of the flow is the request pipeline: request a book, Prowlarr searches, qBittorrent or SABnzbd downloads, files are organised, the library imports.

So it is not a downloader in isolation and not a media server in isolation. It is the glue that connects a request interface to a search index, a download client and a library, and it also does the parts that usually break: merging a multi-file download into a single M4B with chapters, and importing it into the library.

The audience is self-hosters with a home server stack already in place. The prerequisites are listed as Docker, Plex or Audiobookshelf, qBittorrent or SABnzbd, and Prowlarr, and the feature list names each of those integrations: torrents via qBittorrent, usenet via SABnzbd, and Prowlarr for indexer search across both torrents and NZBs.

It also ships an unusual extra, BookDate, an AI recommendation surface with a Tinder-style swipe interface where you swipe right to request.

Next.js, Prisma, PostgreSQL, Redis and Bull

The technology choices in the manifest describe the architecture as clearly as any diagram would.

The application is Next.js 16.0.7 with React 19.2.1, and the scripts are the standard ones: `next dev`, `next build`, `next start`, plus `eslint` for linting and `vitest run` for tests, with `vitest` in watch mode and a coverage variant using `@vitest/coverage-v8`. The test tooling is `@testing-library/react` with `jest-dom` and `user-event`, and the repository has a `vitest.config.ts` and a `tests/` directory.

State lives in PostgreSQL through Prisma, with `@prisma/client` at 6.19.0 and dedicated scripts for `prisma generate`, `prisma migrate dev`, `prisma studio` and `prisma db push`. The `prisma/` directory is at the repository root, which is where the schema and migrations live.

The asynchronous work is Bull on top of ioredis, which is the job queue pattern you would expect: downloads and imports are long running and should not block a request. Redis is also the rate limiter and the cache store, given the `ioredis` dependency and the compose file mounting a redis data directory.

The rest of the dependency list tells you what the features are made of. `parse-torrent` and `axios` for the indexer and download side, `cheerio` and `fast-xml-parser` and `xml2js` for scraping and parsing indexer and metadata feeds, `archiver` and `adm-zip` for packaging and unpacking, `jsonwebtoken` and `bcrypt` for authentication, `openid-client` for OIDC OAuth, `zod` for validation, `string-similarity` for fuzzy matching of titles, `react-swipeable` for the BookDate swipe, `date-fns` for dates, and `swr` for client side data fetching.

One compose file, one port, and a path mapping that must line up

The quick start is two commands and a browser:

# Download docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/kikootwo/readmeabook/main/docker-compose.yml -o docker-compose.yml

# Start the container
docker compose up -d

Then you open http://localhost:3030 and follow the setup wizard, which the feature list describes as a step-by-step guided config with connection testing.

The manual path gives you the same container with the volumes and environment spelled out:

services:
  readmeabook:
    image: ghcr.io/kikootwo/readmeabook:latest
    container_name: readmeabook
    restart: unless-stopped
    ports:
      - "3030:3030"
    volumes:
      - ./config:/app/config
      - ./cache:/app/cache
      - ./downloads:/downloads        # Your download client's path
      - ./media:/media                # Your audiobook library
      - ./pgdata:/var/lib/postgresql/data
      - ./redis:/var/lib/redis

The important line in that file is not the image, it is the pair of volume mounts. The documentation marks it as important in bold: your download client, qBittorrent or SABnzbd, and ReadMeABook must see files at the same path, and there is a Volume Mapping Guide in the documentation for when downloads are not being detected. That is the classic failure in this kind of tool. The download client writes to its own path inside its own container, and the library app has to find the same bytes, and the two paths only agree if you map them consistently.

The compose file in the repository also shows the ownership model, with a PUID and PGID pair and a comment explaining the hybrid approach: the PostgreSQL user keeps UID 103 because of a PostgreSQL requirement and uses your PGID, while the redis and node processes are fully remapped to your PUID and PGID. There is a note for LXC users that only the container UID 103 needs to be passed through.

Chapter merging, sidecars, approvals and OIDC

The feature list is where the practical differences between this and a plain download client show up.

Chapter merging turns a multi-file download into a single M4B with chapters, which is the difference between a library entry that a player can navigate and a folder of loose files. The e-book sidecar feature is optional and described as EPUB or PDF downloads from Shadow Library, alongside the audiobook itself, so the metadata and the text stay together. User friendly audible-backed searches are also listed, alongside multi-file chapter merging, e-book sidecar support, OIDC OAuth, and admin approval workflows.

The request approval workflow is the feature that makes this usable by more than one person. For a multi-user setup, a request does not become a download automatically; an administrator approves it. That is the difference between a private tool and something you would put in front of a family or a small group.

On authentication, the manifest has `jsonwebtoken` for sessions and `openid-client` for OIDC OAuth, and the compose file notes that `PUBLIC_URL` is required for OAuth, which is the usual consequence of putting a callback URL in the configuration. `bcrypt` is there for password hashing, and there is a `rmab:recover` script, `node scripts/recover-credentials.js`, which suggests the credential store can be rebuilt when it is lost.

There is also a Book Drop style manual import path in the compose comments, an optional host folder that appears as a browsable root in the file picker under admin, audiobook, Manual Import, for files you already have and do not want to fetch.

BookDate, recommendations, and the matching problem

BookDate is the feature that makes the project a bit different from the *arr family it compares itself to.

The description is that BookDate gives AI recommendations with a Tinder-style swipe interface, and that you swipe right to request. The feature list names the providers as OpenAI, Claude or Local, so the recommendation model can be a hosted API or something running on your own hardware, and the swipe itself is built on `react-swipeable`.

The interesting engineering detail is in the dependencies rather than the marketing. There is `string-similarity`, a small library for computing how similar two strings are, and `cheerio` for parsing HTML. Between them, those are the tools for the part of the problem that is genuinely hard here: deciding that the thing the user asked for and the thing the indexer found are the same book, and that the recommended title is the one they wanted. An audiobook library is full of near-duplicate titles, different editions, and different narrators, and the request pipeline is only as good as its matching.

So BookDate is not a bolt-on gimmick in the code, it sits on the same matching infrastructure that the request flow uses, with a different front end on top. Whether an AI recommendation model is a good way to browse for audiobooks is a question of taste, and the project is candid that the interesting part is the swipe, but the recommendation side is where the provider choice matters, and the Local option means the recommendation does not have to leave your network.

Where the legal responsibility actually sits

This is the part of the evaluation that a technical readme does not answer, so it is worth being explicit about what the project does and does not do.

The application does not host content. It searches indexes that the user configures through Prowlarr, and it downloads through the user's own qBittorrent or SABnzbd, which means the indexers, the sources and the content are all outside the project. The tool is automation glue.

That does not settle the question, though, and the project does not pretend to. The e-book sidecar feature is described explicitly as optional EPUB or PDF downloads from Shadow Library, which is a shadow library service, and that is a source whose legality depends on your jurisdiction and on the rights in the works. A feature that is off by default and a single line in a feature list is still a feature, and an administrator enabling it is making a decision about where their users' books come from.

The same applies more broadly. Whether downloading particular titles through particular indexers is lawful or permitted by the terms of the services involved is a question the operator has to answer, and it is the operator, not the maintainer, who configures the indexers and the client.

The licence has a related dimension that is easy to miss for a self-hosted service. AGPL-3.0 is network copyleft: the standard is that users interacting with the software over a network must be offered the corresponding source. A ReadMeABook instance that is only on your own LAN, with you and your family, is a private use case. A ReadMeABook instance that your friends or your club use over the internet is a case where the AGPL obligations are live, and the source is published on GitHub, so the obligation is largely already met for the unmodified application. Modifying it and then hosting it for others is where the obligation becomes something to think about.

A solo project with an unusual build process

The maintenance record is steady. v1.2.1 was published on 2026-05-18, v1.2.2 on 2026-08-11, and v1.2.3 on 2026-09-14,. The project is not archived, and the version is at 1.2.3 with the manifest at the same number, so the package and the release track each other.

The deployment story is unusually thorough for a project of this size. There is a `docker-compose.yml` for the standard deployment, a `docker-compose.debug.yml`, a `docker-compose.local.yml`, a `dockerfile.unified` for building the image locally, a `docker/` directory, a `docker-entrypoint.sh`, and an `unraid.xml` for people who run Unraid. There is also a `build-unified-image.yml` workflow and a `run-tests.yml` workflow, so the image build and the test suite are both in CI.

The one part of the readme that deserves attention is the section on being built with AI assistance. It states that the application is human-engineered, that architecture, design decisions, code review and project direction are managed by a principal engineer, and that AI tools such as Claude and GitHub Copilot are used as force multipliers. The supporting mechanisms are listed: a token-optimized documentation system designed for AI consumption in `CLAUDE.md`, structured navigation so an AI can find context without reading the whole codebase, consistent architectural patterns, and human review of all AI-generated code before merge. There is an `AGENTS.md` and a `documentation-agent-prompt.md` at the root, and a `documentation/` directory that contributors are pointed at.

Whether an AI-assisted workflow suits you is a matter of taste and of review capacity, and the documentation in the repository is unusually explicit about which parts are human decisions, which is more than most projects of this size offer.

Editorial conclusion

ReadMeABook fits a self-hoster running Plex or Audiobookshelf who already has a download client and an indexer configured and wants the request, chapter merging and import steps automated in one interface, including a multi-user approval flow. It does not fit a user who wants a legal storefront rather than an indexer pipeline, and the optional e-book sidecar feature points at a source whose legality is a question each user has to answer for their own jurisdiction. Before you deploy it, read the volume mapping guide, because the download client and the app must see the same filesystem path or imports silently fail, and read the AGPL-3.0 terms, since it is network copyleft and other users interacting with your instance are entitled to the source.

Frequently asked questions

Official sources

1. Issues
2. kikootwo/ReadMeABook on GitHub
3. License: AGPL-3.0
4. README
5. Releases