Self-hosted · open source · AGPL-3.0
Read and listen
in perfect tandem.
ReadPort is a reader and a player for the ebook and audiobook libraries you already keep. It mounts them read-only, pairs matching editions, and lets you move between the page and the narration at the same sentence.
One containerNothing leaves your machineLives beside Calibre-Web Automated, Audiobookshelf and Kavita
Call me Ishmael. Some years ago, never mind how long precisely, having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world. It is a way I have of driving off the spleen and regulating the circulation. This is my substitute for pistol and ball.
Chapter 3 of 135
The Spouter-Inn
Read by a patient narrator · 21h 12m
The reading layer for a self-hosted library
Not another library manager. The place you actually read.
Calibre, Audiobookshelf and Kavita are good at keeping books. ReadPort sits beside them, on the same folders, and owns only what a reader needs: your progress, your marks, and the timings that tie an audiobook to its text.
A serious reader
Paginated or scrolling, two-page spreads on a wide screen, five themes, seven typefaces, hyphenation, right-to-left books. And marks you can find again: highlights in five colours, notes, bookmarks, and one page that searches them all.
A resilient player
Chapters, 0.5× to 3× with the pitch kept, a sleep timer, bookmarks, lock-screen controls, and progress that survives a killed tab. A folder of mp3s plays as one book.
One place, kept in both
Where an ebook and an audiobook are the same work, ReadPort times the narration against the text. Switch mid-sentence in either direction, or read along while it plays.
Your library already has the book and the narration. ReadPort teaches them to keep the same place.
How it works
Three gates. Only the narration can open the middle one.
- 01
Mount, read-only.
Point it at the folders Calibre, Audiobookshelf or Kavita already manage. ReadPort never writes into them. The one folder it does write is where finished alignments are saved as files you own.
- 02
Pair, then listen.
Matching editions are proposed from title, author, identifiers and length, with their evidence shown. Metadata never links two books on its own: the narration is checked against the text first.
- 03
Switch mid-sentence.
Listen from here in the reader; Read from here in the player. Reading to listening lands a few seconds behind you on purpose: hearing a line twice is a nuisance, hearing one you have not reached is a spoiler.
Every row is real evidence the app shows; nothing here links two books by itself.
The engine
Forced alignment, not transcription.
The words are already in the EPUB; only their timing is unknown. So ReadPort does not try to discover them. One acoustic model listens to about 7% of the narration, finds where the audio and the text provably agree, and interpolates the rest. Then it listens again wherever the reading rate says the interpolation would be a lie.
A six-hour audiobookember = the seconds actually decoded · ticks = anchors
- 72 s
- to time a 67-minute audiobook
- ≈ 6 min
- for a six-hour audiobook, on a 6-CPU box
- 7%
- of the audio actually decoded
- 830 of 880
- sentences timed on the validation book
- 1 model
- 317 MB, every language, one download
- 0 bytes
- written into your library
Read along: the reader, with a voice.
Press it in the reader of an aligned pair and the narration starts at the sentence in front of you. The spoken sentence is washed as it is read and the page turns itself to keep up. Tap any line to move the voice to it. Turn a page by hand and the page stops following; it starts again on its own the moment the voice catches up. Where the alignment has nothing to say, the wash is dropped and the bar says so, rather than guessing.
Everything else a reader wants
The details are where a reading app is won.
Marks worth keeping
Five highlight colours picked in the same tap that makes the mark; notes carried by a dashed underline; bookmarks. A Notes & marks page searches the note, the passage, the title and the author at once.
Shelves and groups
Automatic shelves the server computes, your own named ones, an ordered reading list, and groups built from the metadata your files already carry: tags, narrators, series, years.
A player that behaves
Chapter ticks and time left in the chapter, skips from 10 to 60 seconds set per direction, a sleep timer to the end of the chapter, an ambient tint taken from the cover, Media Session on the lock screen.
Offline, honestly
Per-title downloads with real size and progress, verified byte for byte. A Downloaded shelf that works with no network at all. Audio stored in 8 MB chunks so an iPhone never buffers a whole book.
A household, not a login
The first-run wizard creates the admin; after that you add people or send one-time invite links. Admin, curator and reader roles, and progress, marks and downloads per person. No open sign-up.
Alignments are files
One gzipped JSON document per pair, in a folder you choose, matched back to books by a fingerprint of the text and the track lengths. A from-scratch reinstall adopts them on its first scan.
Progress that cannot regress
Every checkpoint is written locally before it is sent, as an idempotent event with explicit intent. A stale background tab can never move you backwards; a deliberate rewind always wins.
No cloud, no socket
Nothing leaves the machine. No Docker socket, non-root runtime, read-only mounts, one 2 GB memory cap for alignment. Optional header SSO from Authentik, Authelia or oauth2-proxy.
Self-host
One container in front of the folders you already have.
Docker, your library, and enough CPU to be patient with. The stock compose file mounts a bundled sample library, so the reader, the player and pairing are usable within a minute; point the mounts at your real folders when ready.
git clone https://github.com/ilanKushnir/readport && cd readport
cp .env.example .env # set RP_SESSION_SECRET (openssl rand -hex 32)
docker compose up -d # point the library mounts at your folders first
# open http://<host>:8383 and create the admin account- Library folders mounted :ro, always
- One read-write folder: your alignments
- 317 MB of disk for the one model, only when you ask
- Non-root, no Docker socket, 2 GB cap on alignment
- Reverse proxy with HTTPS for the installable PWA
- Header SSO from Authentik, Authelia, oauth2-proxy (optional)
Coexists with Calibre / Calibre-Web Automated, Audiobookshelf, Kavita, Shelfmark and plain folders. Full guide: docs/self-hosting.md.
Questions
The honest answers.
Everything here is documented in the repo; the docs say exactly where each claim stands.
Does ReadPort change my files?
No. Library folders are mounted read-only and never written. The single writable folder is the one you choose for finished alignments: one .rpalign file per pair, readable with gunzip, and the only thing ReadPort will ever put there.
Do I need a GPU?
No. Alignment is CPU only. On a 6-CPU box a 67-minute audiobook is timed in 72 seconds and a six-hour one in about six minutes. Reading and listening need almost nothing.
Which formats does it read and play?
EPUB for ebooks. For audio: m4b, mp3, m4a, flac, ogg and opus, single-file or a folder of files. PDF, MOBI/AZW3 and comics are detected and reported as unsupported rather than rendered badly.
Does it replace Audiobookshelf or Calibre-Web?
No, and it does not try to. ReadPort is a reading layer over the folders they manage: keep them for acquisition, metadata and organising, and let ReadPort do the reading, the listening and the switching.
Which languages work?
One model covers every language it can romanise: Latin scripts, Cyrillic, Greek, Hebrew and Arabic. It has been validated end to end on full-length, human-narrated audiobooks in English and Russian. Treat the numbers as evidence that the approach works, not as a guarantee for every book in your library.
How exact is the switch, really?
Sentence exact only where the timing came from a real acoustic match at high confidence. Otherwise it degrades to the nearest aligned sentence, or refuses with a reason and names the nearest aligned points before and after. Front matter, credits and chapter announcements produce gaps on purpose, and the page says so instead of guessing.
Can my family use it?
Yes. The setup wizard creates the admin account; then you add people or send one-time invite links. There are three roles, and everyone gets their own progress, marks and downloads. There is no open sign-up.
What is the license?
AGPL-3.0-or-later. The bundled Literata typeface is SIL OFL and the sample stories are original works. The one download, Meta’s MMS forced aligner, is CC BY-NC 4.0 and is never fetched behind your back: the wizard offers it, Settings has it, and a command installs it on a headless server.
Give your library a reader.
It takes a minute to start and it never touches your files.