Your tool for handling audiobook requests on a Plex/Audiobookshelf/Jellyfin instance.

If you've heard of Overseer, Ombi, or Jellyseer; this is in the similar vein, but for audiobooks.

• Motivation
  • Features
  • Out of Scope Features
• Getting Started
  • Quick Start
  • Basic Usage
    • Auto download
    • Audiobookshelf Integration
    • Organizing Downloads
    • OpenID Connect
      • Getting locked out
    • Environment Variables
• Contributing
  • Conventional Commits
  • Local Development
• Tools

Earr aims to be a simple and lightweight tool for managing audiobook requests for your media server. It should be easy to set up and use, while integrating nicely with other common tools in the *arr stack. Earr serves as as the frontend for you and your friends to easily make audiobook wishlists or create requests in an organized fashion.

It is not intended as a full replacement for Readarr/Chaptarr, but instead intended to be used alongside them.

• Employs the Audible API to make it easy to search for and request audiobooks.
• Add manual audiobook requests for any books not available on Audible.
• Easy user management. Only three assignable groups, made to get out of your way.
• Automatic downloading of requests. Integrate Prowlarr to use all your existing indexer settings and download clients.
• Send notifications to your favorite notification service (apprise, gotify, discord, ntfy, etc.).
• Optionally copy, move or hardlink finished downloads into a folder structure of your choosing, e.g. /Author/Series/Book.
• Single image deployment. You can deploy and create your first requests in under 5 minutes.
• SQLite and Postgres support!
• Lightweight website. No bulky javascript files, allowing you to use the website even on low bandwidth.
• Mobile friendly. Search for books for accept requests on the go!

• Earr does not rename files nor edit metadata after downloads. Placing finished downloads into a folder structure is supported and opt-in, see Organizing Downloads, but everything beyond that is left to other tools. Earr also supports multiple REST API endpoints that allow for easy interoptability with scripts and other apps.
  • Combinations:
    • Know of or have an app or script that works with Earr? Open an issue and I'll add it here or to the docs.
  • Alternatives:
    • Listenarr: A more all-in-one approach with built-in file organization.
    • I'd love to add more alternatives for Earr here. If you know of any good ones, open an issue!

Earr is intended to be deployed using Docker or Kubernetes. For "bare-metal" deployments, read up on local development in the wiki.

Run the image directly:

docker run -p 8000:8000 -v $(pwd)/config:/config jedibrooker/earr:1

Then head to http://localhost:8000.

NOTE: Earr uses the /config directory inside the container for storing configs and data. Mount that directory locally somewhere to ensure persistent data across restarts.

1. Logging in the first time the login-type and root admin user has to be configured.
2. Head to Settings>Users to create accounts for your friends.
3. Any user can search for books and request them by clicking the + button.
4. The admin can head to the wishlist to see all the books that have been requested.

Auto-downloading enables requests by Trusted and Admin users to directly start downloading once requested.

1. Ensure your Prowlarr instance is correctly set up with any indexers and download clients you want. More info.
2. On Prowlarr, head to Settings>General and copy the API Key.
3. On Earr, head to Settings>Prowlarr and enter the API key as well as the base URL of your Prowlarr instance, i.e. https://prowlarr.example.com.
4. Head to Settings>Download to configure the automatic download settings:
   1. Enable Auto Download at the top.
   2. The remaining heuristics determine the ranking of any sources retrieved from Prowlarr.
   3. Indexer flags allow you to add priorities to certain sources like freeleeches.
   4. Keep searching for outstanding requests retries requests that have not produced files yet, including grabs that stalled. It uses the same quality rules, only applies to requests from trusted users, and gives up after a configurable number of attempts so nothing retries forever.

A source is only downloaded automatically if it clears the quality, seeder and title-match settings. If nothing does, nothing is grabbed and the book stays on the wishlist.

Audiobookshelf (ABS) integration lets Earr:

• Check if a book already exists in your ABS library and mark it as downloaded in search results to avoid duplicate requests.
• Trigger a library scan in ABS when a request is marked as downloaded in Earr (manual or automatic), so the new item appears quickly.

Setup steps:

1. In ABS, create an API token for an account with access to your audiobook library (Admin recommended).
2. In Earr, go to Settings > Audiobookshelf and enter:

• Base URL of your ABS server (e.g. https://abs.example.com or http://localhost:13378)
• API Token from step 1
• Select the target Library
• Enable “Use ABS to mark existing books as downloaded” if you want Earr to flag existing titles during search.

Notes:

• Earr searches ABS by ASIN and by “title + first author” to detect existing books; this is a best-effort match and may not catch every case depending on your metadata.
• ABS is automatically asked to scan after successful downloads are marked in Earr. ABS typically auto-detects updates, but this helps pick up changes sooner.

Earr can place finished downloads into a folder structure of your choosing. This is off by default.

Prowlarr hands grabs to your download client and never reports back, so Earr watches the folder your download client writes finished downloads to and matches new items there against the releases it grabbed. Both folders therefore have to be mounted into the Earr container.

services:
  earr:
    image: jedibrooker/earr:1
    volumes:
      - ./config:/config
      # the same paths your download client uses, so hardlinks work
      - /mnt/data/downloads:/downloads
      - /mnt/data/audiobooks:/audiobooks

Head to Settings>Library and configure:

1. Organize downloads to turn the feature on.
2. Mode:
   • hardlink keeps a single copy on disk and lets torrents keep seeding. Both folders have to be on the same filesystem, which for Docker means the same volume mount, not two separate mounts.
   • copy uses twice the space but works everywhere.
   • move frees up the download folder but breaks seeding.
3. Completed downloads folder and Library folder, as seen from inside the container.
4. Folder structure, see below.

The folder structure is a / separated template. Placeholders are replaced with the metadata of the book:

Two rules keep templates short:

• A folder that would end up empty is left out, so {author}/{series}/{title} becomes Andy Weir/The Martian for a book that is not part of a series.
• Text in square brackets disappears as a whole when a placeholder inside it is empty, which makes [{series_position} - ]{title} render as just the title for standalone books.
• A | inside those brackets adds a fallback, so [{series} #{series_position}|{title}] names the folder after the series for a series book and after the title for a standalone one.

The settings page previews both cases while you type. File names inside the folder are left alone.

With Write metadata.json enabled (the default), the title, subtitle, authors, narrators, series and ASIN are written into the organized folder as a metadata.json. Audiobookshelf reads that file and prefers it over what it can infer from file and folder names, so a release with messy file names still ends up with the right metadata. Only fields Earr actually knows are written, and an existing metadata.json is left alone unless Overwrite existing files is on, so anything corrected by hand in ABS survives a re-import.

Notes:

• Audible does not always expose series information. The series position is read from the subtitle and may be missing for some books. Manual requests never have a series.
• A download is only picked up once it stopped changing and has no partial files left.
• Existing files are never replaced unless Overwrite existing files is turned on.
• If a download is not picked up because the download client renamed it, lower the Match threshold, or use POST /api/library/import with the ASIN and the path to organize it by hand.

Head to the OpenID Connect page in the wiki to learn how to set up OIDC authentication with your favorite auth provider.

Head to the environment variables page in the wiki.

Building, shipping and configuring this fork, including the storage layout the library organizer needs: docs/DEPLOYMENT.md.

Please read the contribution guidelines before contributing.

This project uses Conventional Commits to allow for a more organized commit history and support automated changelog generation. Pull requests will be squashed in most cases (with some exceptions).

Head to the local development page in the wiki.

Earr builds on top of a some other great open-source tools. A big thanks goes out to these developers.

• Prowlarr - Does a lot of the heavy lifting concerning searching through indexers and forwarding download requests to download clients. Saves me the ordeal of having to reimplement everything again.
• External Audible API - Audible exposes key API endpoints which are used to, for example, search for books.

just test          # pytest
just types         # basedpyright
just test_format   # djlint + ruff
just test_jinja    # jinjax template parameters
just check_migrations

Tests live in tests/ and run against an in-memory SQLite database and real temporary directories, so the file operations are exercised for real rather than mocked.