Audiobookshelf works best when you have an organized directory structure like shown below. This is because information is taken from your folder names. This includes the author name, series name, book title, publish year, volume number, and subtitle. However, you can enable scanner settings to prefer using your audio file ID3 tags or an OPF file over using folder names.

Join our Discord server or Matrix space.

If you are interested in integrating with Audiobookshelf, visit the API documentation.

docker pull ghcr.io/advplyr/audiobookshelf

docker run -d \
  -p 13378:80 \
  -v </path/to/config>:/config \
  -v </path/to/metadata>:/metadata \
  -v </path/to/audiobooks>:/audiobooks \
  -v </path/to/podcasts>:/podcasts \
  --name audiobookshelf \
  --rm ghcr.io/advplyr/audiobookshelf

Volume mappings

• /config will contain the database (users/books/libraries/settings)
• /metadata will contain cache, streams, covers, downloads, backups and logs
• Map any other directories you want to use for your book and podcast collections (ebooks supported as experimental)

version: "3.7"
services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    ports:
      - 13378:80
    volumes:
      - </path/to/audiobooks>:/audiobooks
      - </path/to/podcasts>:/podcasts
      - </path/to/config>:/config
      - </path/to/metadata>:/metadata

Volume mappings

• /config will contain the database (users/books/libraries/settings)
• /metadata will contain cache, streams, covers, downloads, backups and logs
• Map any other directories you want to use for your book and podcast collections (ebooks supported as experimental)

For Debian based systems, you can activate the official Audiobookshelf repository and install the Debian package.

Installation

Activate the repository:

sudo apt install gnupg curl
curl -s https://advplyr.github.io/audiobookshelf-ppa/KEY.gpg | sudo apt-key add -
sudo curl -s -o /etc/apt/sources.list.d/audiobookshelf.list https://advplyr.github.io/audiobookshelf-ppa/audiobookshelf.list

Install Audiobookshelf:

sudo apt update
sudo apt install audiobookshelf

Configuration

The Audiobookshelf service will use the config file localted at /etc/default/audiobookshelf. The default configuration is as follows:

METADATA_PATH=/usr/share/audiobookshelf/metadata
CONFIG_PATH=/usr/share/audiobookshelf/config
FFMPEG_PATH=/usr/lib/audiobookshelf-ffmpeg/ffmpeg
FFPROBE_PATH=/usr/lib/audiobookshelf-ffmpeg/ffprobe
TONE_PATH=/usr/lib/audiobookshelf-ffmpeg/tone
PORT=13378

If you update the configuration, restart the service by running:

sudo systemctl restart audiobookshelf.service

Installation

To activate the repository, run:

dnf install -y "https://github.com/lkiesow/audiobookshelf-rpm/raw/el$(rpm -E %rhel)/audiobookshelf-repository-1-1.el$(rpm -E %rhel).noarch.rpm"

You can now install Audiobookshelf. All dependencies will be installed automatically:

dnf install audiobookshelf

Configuration

You can configure Audiobookshelf in /etc/default/audiobookshelf. Here you can add the same configuration options you would pass to the Docker container.

METADATA_PATH=/var/lib/audiobookshelf/metadata
CONFIG_PATH=/var/lib/audiobookshelf/config
PORT=13378
HOST=127.0.0.1

By default, Audiobookshelf will listen to localhost only. This should be sufficient if you install a reverse proxy (you should!). If you want to listen to all network interfaces, set HOST=0.0.0.0 instead.

Start Audiobookshelf

To run Audiobookshelf and ensure it will be started automatically after a reboot, run:

systemctl start audiobookshelf.service
systemctl enable audiobookshelf.service

To check the current status of the service, run:

systemctl status audiobookshelf.service

Windows installer is not yet available. However...

You can install audiobookshelf on Windows using Docker. Check out the user-contributed guide for installing on Windows and join our Discord/Matrix server for support.

We are looking for a .NET developer familiar with building Windows installers to help!

See Github readme for user-contributed reverse proxy configs

The mobile apps are open source on Github. Report bugs and suggest features there.

Android

Install from the Google Play Store.

iOS

Join Test Flight beta testing and install the app.

Audiobookshelf is configured via environment variables. You can pass them to your Docker container using -e VARIABLE=VALUE or set them in /etc/default/audiobookshelf if you install audiobookshelf via packages.

Here is a list of all available options:

Filesystem

• CONFIG_PATH (default: ./config)
  • Path to the config directory.
  • It will contain the database (users/books/libraries/settings).
• METADATA_PATH (default: ./metadata)
  • Path to the metadata directory.
  • It will contain cache, streams, covers, downloads, backups and logs.

External Tools

• FFMPEG_PATH (default: ffmpeg)
  • Path to the ffmpeg binary.
  • If no path is set, Audiobookshelf will assume the binary to exist in the system path.
• FFPROBE_PATH (default: ffprobe)
  • Path to the ffprobe binary.
  • If no path is set, Audiobookshelf will assume the binary to exist in the system path.
• TONE_PATH (default: tone)
  • Path to the tone binary.
  • If no path is set, Audiobookshelf will assume the binary to exist in the system path.

Network

• HOST
  • The host Audiobookshelf binds to. Most commonly, this will be 127.0.0.1 if you want the service to listen to localhost only, or left unset if you want to listen to all interfaces (both IPv4 and IPv6).
• PORT
  • The TCP port Audiobookshelf will listen on.

Security

• TOKEN_SECRET
  • Secret used for generating the JSON Web Tokens.
  • If none is provided, a secure random token is generated automatically. That will usually be sufficient.

Other

• AUDIOBOOKSHELF_GID – deprecated
  • Numeric group identifier to which Audiobookshelf will assign some of its managed files.
  • If not specified, Audiobookshelf will simply write files using the default permissions of the user it runs as.
  • To use this, you must specify both uid and gid.
• AUDIOBOOKSHELF_UID – deprecated
  • Numeric user identifier to which Audiobookshelf will assign some of its managed files.
  • If not specified, Audiobookshelf will simply write files using the default permissions of the user it runs as.
  • To use this, you must specify both uid and gid.
• SOURCE
  • Installation source. Will be shown in the web client.
  • Usually set to docker, debian or rpm.

Where can I get help?

1. Join the community on Discord or Matrix.
2. Go to the Github repo and at the top left of the page you can search for your issue.

Why are multiple books showing as the same book?

There are 2 ways this can happen.

1. The audio or ebook files are inside the same sub-folder. Each audiobook/ebook must be inside its own folder UNLESS you are keeping them in the root folder.
2. You have an ebook or audio file inside a sub-folder. An ebook file can be a PDF, AZW3, MOBI, EPUB, CBR, CBZ. If any audio file or ebook file is found in a subfolder then it is assumed that sub-folder is the book.

What is the difference between a "Scan" and "Force Re-Scan"?

The only difference is a force re-scan will read the meta (ID) tags on every audio file again. A regular scan will not read the meta tags of audio files that have already been seen.

The only reason you would want to force re-scan is if you have modified the meta tags on your audio files. A regular scan will be enough to detect new/removed/renamed files. Force re-scan will greatly extend the scan time and is resource intensive so only use it when necessary.

How is metadata pulled in from scans?

Scans pull information from your folder names and audio file meta tags. Metadata is only pulled from external providers when using the "Match" or "Quick Match" features.

By default your folder names will take priority over your audio file meta tags unless you have enabled the "Prefer audio metadata" setting.

For example, if your audiobook is in a folder named "Enders Game (Annotated)" then by default the book title will be "Enders Game (Annotated)" regardless of your audio file meta tags.

Alternatively, if you had the "Prefer audio metadata" enabled and you have the title meta tag set on your audio files to "Enders Game" then the scanner would use "Enders Game" as the book title.

Scans will not overwrite metadata already pulled in.

A Force Re-Scan will only overwrite metadata on your items in Abs if you have the server setting "Prefer audio metadata" enabled because the meta tags from the audio files are being pulled again. If you don't have that server setting enabled then only the missing/empty details on your library items will be filled in from the scan.

Note: You can also use a desc.txt, reader.txt and .opf file to pull data into Abs. See here