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.

Table of Contents

• Motivation
  • Features
• Getting Started
  • Quick Start
  • Basic Usage
  • Documentation
    • Auto download
    • OpenID Connect
      • Getting locked out
    • Environment Variables
• Contributing
  • Conventional Commits
  • Local Development
  • Initialize Database
  • Running
  • Docker Compose
• Docs

Motivation

AudioBookRequest 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. AudioBookRequest 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.

Features

• 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.).
• Single image deployment. You can deploy and create your first requests in under 5 minutes.
• SQLite database by default. (Watch #137 for 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!

---

Getting Started

AudioBookRequest is intended to be deployed using Docker or Kubernetes. For "bare-metal" deployments, head to the local development section.

Quick Start

Run the image directly:

docker run -p 8000:8000 -v $(pwd)/config:/config markbeep/audiobookrequest:1

Then head to http://localhost:8000.

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

Basic Usage

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.

Documentation

Head to https://markbeep.github.io/AudioBookRequest/ for more detailed documentation and tutorials.

Auto download

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 AudioBookRequest, 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.

OpenID Connect

OIDC allows you to use an external authentication service (Authentik, Keycloak, etc.) for user and group authentication. It can be configured in Settings>Security. The following six settings are required to successfully set up oidc. Ensure you use the correct values. Incorrect values or changing values on your authentication server in the future can cause lead to locking you out of the service. In those cases head to Getting "locked" out.

• well-known configuration endpoint: This is located at /realms/{realm-name}/.well-known/openid-configuration for keycloak or /application/o/{issuer}/.well-known/openid-configuration for authentik.
• username claim: The claim that should be used for usernames. The username has to be unique. NOTE: Any user logging in with the username of the root admin account will be root admin, no matter what group they're assigned.
• group claim: This is the claim that contains the group of each user. It should either be a string or a list of strings with one of the following case-insensitive values: untrusted, trusted, or admin. Any user without any groups is assigned the untrusted role.
• scope: The scopes required to get all the necessary information. The scope openid is almost always required. You need to add all required scopes to that the username and group claim is available.
• client id
• client secret

In your auth server settings, make sure you allow for redirecting to /auth/oidc. The oidc-login flow will redirect you there after you log in. Additionally, the access token expiry time from the authentication server will be used if provided. This might be fairly low by default.

Applying settings does not directly invalidate your current session. To test OIDC-settings, press the "log out" button to invalidate your current session.

Getting locked out

In the case of an OIDC misconfiguration, i.e. changing a setting like your client secret on your auth server, can cause you to be locked out. In these cases, you can head to /login?backup=1, where you can log in using your root admin credentials allowing you to correctly configure any settings.

Environment Variables

ENV	Description	Default
ABR_APP__PORT	The port to run the server on.	8000
ABR_APP__DEBUG	If to enable debug mode. Not recommended for production.	false
ABR_APP__OPENAPI_ENABLED	If set to true, enables an OpenAPI specs page on /docs.	false
ABR_APP__CONFIG_DIR	The directory path where persistant data and configuration is stored. If ran using Docker or Kubernetes, this is the location a volume should be mounted to.	/config
ABR_APP__LOG_LEVEL	One of DEBUG, INFO, WARN, ERROR.	INFO
ABR_APP__BASE_URL	Defines the base url the website is hosted at. If the website is accessed at example.org/abr/, set the base URL to /abr/
ABR_DB__SQLITE_PATH	If relative, path and name of the sqlite database in relation to ABR_APP__CONFIG_DIR. If absolute (path starts with /), the config dir is ignored and only the absolute path is used.	db.sqlite
ABR_APP__DEFAULT_REGION	Default audible region to use for the search. Has to be one of us, ca, uk, au, fr, de, jp, it, in, es, br.	us
ABR_APP__FORCE_LOGIN_TYPE	Forces the login type and prevents it from being modified. Can be one of basic, forms, oidc, or none to disable the login. oidc requires both the ABR_APP__INIT_ROOT_USERNAME and ABR_APP__INIT_ROOT_PASSWORD environment variables to be set.
ABR_APP__INIT_ROOT_USERNAME	Sets the initial username of the root user when first launching ABR. Has no effect if a root admin already exists.
ABR_APP__INIT_ROOT_PASSWORD	Sets the initial password of the root user when first launching ABR. Has no effect if a root admin already exists.	us

---

Contributing

Suggestions are always welcome. Do note though that a big goal is to keep this project on a smaller scale. The main focus of this project is to make it easy for friends to request and potentially automatically download Audiobooks without having to give direct access to Readarr/Prowlarr. It might make sense to first create an issue before undertaking a big project and opening a pull request. Your idea could already be worked on in the background.

Conventional Commits

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).

Local Development

NOTE: If you use VSCode, you can also open up the project with the given dev container settings and then follow the instructions below to get everything set up correctly.

Python virtual environments help isolate any installed packages to this directory. Project was made with Python 3.12 and uses new generics introduced in 3.12. Older python versions might not work or could have incorrect typing.

For improved dependency management, uv is used instead of pip.

# This creates the venv as well as installs all dependencies
uv sync

For local development, environment variables can be added to .env.local and they'll be used wherever required.

Initialize Database

Alembic is used to create database migrations. Run the following before starting up the application for the first time. It will initialize the directory if non-existant, create the database file as well as execute any required migrations.

just alembic_upgrade # or simply 'just au'
# or if you don't have 'just':
uv run alembic upgrade heads

In case of any model changes, remember to create migrations using alembic revision --autogenerate -m "<message>".

Running

Running the application is best done in multiple terminals:

1. Start FastAPI dev mode:

just dev # or simply 'just d'
# or if you don't have 'just':
uv run fastapi dev

Website can be visited at http://localhost:8000.

2. Install daisyUI and start Tailwindcss watcher. Required for any CSS styling.

just tailwind # or simply 'just tw'

# or if you don't have 'just':
npm i
uv run tailwindcss -i static/tw.css -o static/globals.css --watch
# Alternatively npx can be used to run tailwindcss
npx @tailwindcss/cli@4 -i static/tw.css -o static/globals.css --watch

3. Optional: Start browser-sync. This hot reloads the website when the html template or python files are modified:

browser-sync http://localhost:8000 --files templates/** --files app/**

NOTE: Website has to be visited at http://localhost:3000 instead.

Docker Compose

The docker compose can also be used to run the app locally:

docker compose --profile local up --build

Docs

Hugo is used to generate the docs page. It can be found in the /docs directory.