Requests that wait for you
A listener's request waits under Awaiting approval until an admin says yes. Nothing is searched for or downloaded before then.
The Time Machine · asked for by SamAWAITING
Treasure Island · approvedDOWNLOADING
Self-hosted · Open source · MIT licensed
Your audiobooks: found, fetched, and playing.
Narratarr is an *arr-style audiobook manager with a player built in. Find a book, click once, and it lands in your library, tagged, organized and ready to play.
Install Narratarr
View on GitHub
$ curl -fsSL https://raw.githubusercontent.com/narratarr/narratarr/main/install.sh | bash
Docker, macOS and Linux, with Unraid coming soon. Images for amd64 and arm64, Raspberry Pi 4 and 5 included.
localhost:8484
01Chapter one
Thirty thousand free books, and the shelves you already use.
Browse more than 30,000 free, legal audiobooks and radio shows from LibriVox and Old-Time Radio, by genre, popularity or what's new. Connect Prowlarr or any Torznab indexer, such as Jackett, and they're searched too.
- Search forgives typos. Type
sherlok holmsand you still get Sherlock Holmes. - Results are ranked by how well they match, with a way back to your exact words.
- Hide books in languages you don't read, and see a release's length, format and size before you commit.
LibriVoxOld-Time RadioAudiobookBayProwlarrTorznabAudible catalogOpen Library
Including results for sherlock holmes · Show only close matches
The Adventures of Sherlock HolmesSir Arthur Conan Doyle
The Return of Sherlock HolmesSir Arthur Conan Doyle
The Speckled BandSir Arthur Conan Doyle
The Case-Book of Sherlock HolmesSir Arthur Conan Doyle
LibriVoxOld-Time RadioProwlarrTorznabJackettAudiobookBayAudible catalogOpen Library
Real-DebridqBittorrentAllDebridSABnzbdTorBoxTransmissionPremiumizeNZBGetDelugeAudiobookshelf
Plugs into the *arr stack you already run. Adding a new catalog is one small Python class.
02Chapter two
One click sends it to the right place.
Each release goes to the client you choose: a debrid service, a torrent client on your own machine, or a Usenet downloader. Routing rules pick the client by indexer, and by audiobook or ebook. Rules are checked top to bottom, the first match wins, and anything else goes to your default.
- Every download shows on Activity as it happens, with who asked for it.
- Test a rule and see exactly where a release would go, before anything downloads.
- Follow authors and series, and new books are found and fetched on their own.
03Chapter three
Filed the way Audiobookshelf likes it.
Finished books are named and moved into your folder layout, with the cover and description beside them. Pick a preset or write your own from {author}, {series}, {series_number}, {year}, {title} and {narrator}. When a book has no series, that part drops out along with the words around it.
- Audiobookshelf rescans after every download and keeps everyone's place in each book.
- Tidy library moves the books you already have into the layout, with a preview of every move and an undo.
- Import the audiobooks you already own, or point it at an existing Audiobookshelf library.
Folder layout
{author}/{series}/Vol {series_number} - {year} - {title}
Arthur Conan Doyle/Sherlock Holmes/Vol 1 - 1892 - The Adventures of Sherlock Holmes
Edgar Allan Poe/{series}/Vol {series_number} - 1845 - The Raven
Arthur Conan Doyle
Sherlock Holmes
Vol 1 - 1892 - The Adventures of Sherlock Holmes
cover.jpg
desc.txt
01 - A Scandal in Bohemia.mp3
02 - The Red-Headed League.mp3
03 - A Case of Identity.mp3
Audiobookshelf is rescanning, and keeps everyone's place in each book.
04Chapter four
A real player, right there.
No other app needed. Chapters, including the markers inside .m4b files. Speeds from 0.75× to 3×. A sleep timer that can stop at the end of a chapter. It remembers your place in every book, and lock-screen and headphone controls work too.
- Add it to your phone's home screen and listen anywhere on your Wi-Fi.
- Want it as an ebook too? Read EPUBs right in Narratarr, filed next to the audiobook.
- A Continue listening shelf, and finished books tracked for you.
1.5× speed
Sleep: end of chapter
05Chapter five
Made for the whole household.
Admins run things. Listeners browse, ask for books and listen, and everyone keeps their own place in every book.
Notifications where you are
Word goes to ntfy, Gotify, Discord or any webhook when someone wants a book, and when downloads start, finish or fail. An event log in Settings shows where each one went.
Finished · The Time MachineNTFY ✓
Audiobookshelf in a click
Narratarr finds your server, on this machine, in Docker, on your network or at a public address. Sign in once, and it rescans after every download.
Found Audiobookshelf at 192.168.1.10:13378
Ratings on every card
A star score from Audible's own average, shown only when the book matches exactly. A blank beats a wrong score. Switched off, it asks nobody.
Sort Discover by Rating
A Wanted list that fills itself
Follow authors and series. New releases are added to Wanted and fetched when they turn up, in the languages you read.
Following H. G. WellsALL CAUGHT UP
Ebooks too
Want any book as an audiobook, an ebook or both. The ebook lands beside its audiobook, so Audiobookshelf shows them as one book.
Pride and Prejudice · audiobook + EPUB
An API for your other apps
Other apps can search, request and follow a book's progress with their own tokens, so a phone client can ask Narratarr for books.
POST /api/v1/requests
No telemetry. It phones nobody.
Your library stays on your machine. The fonts are bundled, so the app never calls a CDN, and the README lists every outside service Narratarr can contact, what it sends and when.
Epilogue
Running in a minute.
Every option ends the same way: Narratarr at http://localhost:8484, ready for its first book.
# asks a few friendly questions: Docker or native, where books go, start at login curl -fsSL https://raw.githubusercontent.com/narratarr/narratarr/main/install.sh | bash
Run the same command again to update. Add --docker --yes to skip the questions.
services: narratarr: image: ghcr.io/narratarr/narratarr:latest container_name: narratarr restart: unless-stopped ports: - "8484:8484" environment: - PUID=1000 # run `id -u` to find yours - PGID=1000 # run `id -g` to find yours - TZ=Etc/UTC volumes: - ./config:/config # settings + library database - ~/Audiobooks:/audiobooks # where finished books go
Then docker compose up -d. The container runs as your PUID and PGID, so the files it writes belong to you.
docker run -d --name narratarr --restart unless-stopped \ -p 8484:8484 \ -e PUID=$(id -u) -e PGID=$(id -g) \ -v "$PWD/config:/config" \ -v "$HOME/Audiobooks:/audiobooks" \ ghcr.io/narratarr/narratarr:latest
Coming soon
Narratarr on Unraid
Narratarr isn't in Unraid's Community Applications yet. Once it is, you'll install it from the Apps tab like any other container. Join the Discord to hear the moment it lands.
Get notified on Discorduv tool install git+https://github.com/narratarr/narratarr narratarr # → http://127.0.0.1:8484
The manual
Guides for everything.
Each guide lives on GitHub next to the code, so it always matches the version you run.
01 · START
Your first five minutes
From the first page you see to pressing play on your first book.
Read the guide 02 · INSTALLInstall and update
The guided installer and its options, Docker and uv.
Read the guide 03 · CONNECTProwlarr and download clients
Indexers, debrid services, torrent clients, Usenet, and the paths they share.
Read the guide 04 · ROUTEDownload routing
Rules that pick a client per release, defaults per protocol, and testing a route.
Read the guide 05 · FILEFolder layout
Presets, every variable, and how missing parts drop out of a name.
Read the guide 06 · TIDYTidy library
Move the books you already have into your layout, with a preview and undo.
Read the guide 07 · SHAREAccounts and requests
Admins and listeners, approvals, and signing in from phones.
Read the guide 08 · LISTENListening on your phone
Reach it on your Wi-Fi, add it to your home screen, and keep it safe from the internet.
Read the guide 09 · RATERatings
Where the score comes from, how strictly books are matched, and what's cached.
Read the guide 10 · BUILDThe app API
Tokens, search, requests and status, for apps that ask Narratarr for books.
Read the guide 11 · UNDERSTANDHow it works
Sources, Wanted books, following authors and importing what you own.
Read the guide 12 · ASKFAQ
The questions people ask most, answered.
Read the guidePress play.
Get help, share ideas and hear about new versions first on the Narratarr Discord. Bugs and pull requests are welcome on GitHub.