tagIntroduction

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, series sequence, 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.

The source for this documentation can be found at the Audiobookshelf GitHub repository. Contributions to this documentation can be provided through a pull request.

tagDocker Compose

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
    environment:
      - TZ=America/Toronto
  • Remember to change the path to your actual directory and remove the <> symbols
  • Volume mappings should all be separate directories that are not contained in eachother

Volume mappings

  • /config will contain the database (users/books/libraries/settings). Beginning with 2.3.x, this needs to be on the same machine you are running ABS on.
  • /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)

Still confused about Docker? Check out this FAQ

💡 Prefer the CLI? This is our docker run command. YMMV

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 \
 -e TZ="America/Toronto" \
 ghcr.io/advplyr/audiobookshelf

⚠️ Windows users will need to remove the \ and run this as a single line

tagLinux (Debian, Ubuntu, …)

Only for amd64 architecture.

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
wget -O- https://advplyr.github.io/audiobookshelf-ppa/KEY.gpg | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/adb-archive-keyring.gpg
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

tagLinux (RHEL, CentOS, …)

  • This installation method is still in testing.
  • Only for amd64 architecture.
  • Supported operating systems are all Red Hat and CentOS Stream 8/9 variants.

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

tagLinux (NixOS)

Installation

Imperative installation:

nix-env -iA audiobookshelf

Declarative installation:

environment.systemPackages = with pkgs; [
  audiobookshelf
];

Configuration

You can configure Audiobookshelf using the parameters to the executable. It supports the same configuration options you would pass to the Docker container, the options below are the defaults if the option is missing.

audiobookshelf --metadata "$(pwd)/metadata" \
  --config "$(pwd)/config" \
  --port 8000 \
  --host 0.0.0.0

If you use a reverse proxy (you should!) listing on localhost only would be enough. In this case set --host 127.0.0.1 instead.

Start Audiobookshelf

You can create a simple systemd service in your configuration.nix to automatically start audiobookshelf:

services.audiobookshelf {
  enable = true;
  port = 8234;
};

For further options, see the NixOS options page.

To configure a reverse nginx proxy, add the following:

services.nginx = {
  enable = true;
  virtualHosts."your.hostname.org" = {
    locations."/" = {
      proxyPass = "http://localhost:8234/";
    };
  };
};

To check the current status of the service, run:

systemctl status audiobookshelf.service

tagReverse Proxy

See Github readme for user-contributed reverse proxy configs

Please join the discord or matrix server before reporting an issue with your reverse proxy setup on Github.

tagDeploy on Easypanel

Deploying audiobookshelf on Easypanel

Easypanel it's a modern server control panel. You can use it to deploy audiobookshelf on your own server.

Deploy to Easypanel

Instructions

  1. Create a VM that runs Ubuntu on your cloud provider.
  2. Install Easypanel using the instructions from the website.
  3. Create a new project.
  4. Install audiobookshelf using the dedicated template.

tagDocker

To upgrade the server to the newest version, you just need to pull the new docker image and restart the container. If you are using Portainer or Docker Desktop, you can just update the stack and pull the new image. If you are using a pinned version number, you will need to update that version number.

Still confused about Docker? Check out this FAQ

tagDocker Compose

If you used docker compose, you just need to make sure the tag is either the version you want or latest if you want the newest release. If you want to run a specific release, such as older version, change the tag to the desired version number.

Then, you can just run the following commands.

docker-compose pull
docker-compose down
docker-compose up --detach

Still confused about Docker? Check out this FAQ

tagConfiguration

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

  • SOURCE
    • Installation source. Will be shown in the web client.
    • Usually set to docker, debian or rpm.

tagDirectory Structure

Here is an example supported directory structure for Books

Terry Goodkind

 - 

Sword of Truth

 -  - 

Vol 1 - 1994 - Wizards First Rule {Sam Tsoutsouvas}

 -  -  -  audiotrack

Audio Track 1.mp3

 -  -  -  audiotrack

Audio Track 2.mp3

 -  -  -  crop_original

Cover.jpg

 -  - 

Vol 2 - 1995 - Stone of Tears

 -  -  -  audiotrack

Audiobook.m4b

 - 

Heart of Black Ice - Sister of Darkness

 -  -  audiotrack

Audio File.m4a

Steven Levy

 - 

Hackers - Heroes of the Computer Revolution {Mike Chamberlain}

 -  -  audiotrack

Audio File.m4a

1945 - Animal Farm

 -  audiotrack

Audiobook.mp3

audiotrack

Animal Farm.m4b

Books are designated by folders. Any audio files (or ebook files) within a folder will be grouped into that book, except in the root folder where each audio file will be treated as an individual book.

tagAuthor Folder Naming

Supports "Last, First" author naming as well as multiple authors separated by ",", ";", "&" or "and".

Valid author folder names:

Ichiro Kishimi

Kishimi, Ichiro

Ichiro Kishimi, Fumitake Koga

Kishimi, Ichiro, Koga, Fumitake

Ichiro Kishimi & Fumitake Koga

Kishimi, Ichiro & Koga, Fumitake

Terry Goodkind, Ichiro Kishimi and Fumitake Koga

tagTitle Folder Naming

In addition to the book title, the title folder can include the publish year, series sequence, the subtitle, and the narrator.

Here are a bunch of ways the same book could be named:

Wizards First Rule

Wizards First Rule {Sam Tsoutsouvas}

1994 - Wizards First Rule

Wizards First Rule - A Really Good Subtitle

1994 - Book 1 - Wizards First Rule

1994 - Volume 1. Wizards First Rule {Sam Tsoutsouvas}

Vol 1 - 1994 - Wizards First Rule

1994 - Wizards First Rule - Volume 1

Vol. 1 - 1994 - Wizards First Rule - A Really Good Subtitle {Sam Tsoutsouvas}

(1994) - Wizards First Rule - A Really Good Subtitle

1 - Wizards First Rule

1. Wizards First Rule

  • Subtitle: Parsing out subtitles into a separate field is optional and must be enabled in settings. Subtitle must be separated by " - ".
  • Series Sequence: Case insensitive & decimals supported.
    • The sequence can be placed anywhere in the folder name.
    • It must be followed by " - " or ". "
    • If it is not at the beginning of the folder name, it must be preceded by " - " and "Vol" "Vol." "Volume" or "Book"
  • Publish Year: The publish year must be the first part of the name OR directly after a series sequence, and separated by " - " on both sides.
  • Narrator: Must be wrapped in curly braces. e.g. {Sam Tsoutsouvas}.
  • Discs and Disc Numbers: You have to name each folder in the format of CD1, CD01, or CD001; Disk Folder support is not fully supported yet.

tagAudio Metadata

Audiobookshelf uses the ID3 metadata tags in audio files to populate data.

priority_high

Data parsed from the folder structure and filenames takes priority over ID3 tags unless you have enabled the scanner setting "Prefer Audio Metadata".

Metadata on audio files will be mapped as follows (second tag after "/" is a fallback):

ID3 Tag  (case-insensitive) Audiobookshelf Data
artist / album-artist Author
album / title Title
subtitle Subtitle
publisher Publisher
year Publish Year
composer Narrator
description Description
genre Genres *
series / mvnm Series
series-part / mvin Series Sequence
language / lang Language
isbn ISBN
asin / audible_asin ASIN
Overdrive MediaMarkers Chapters**

* Genre meta tag can include multiple genres separated by "/", "//", or ";". e.g. "Science Fiction/Fiction/Fantasy"

** Chapter extraction from Overdrive MediaMarkers must be enabled in your server settings

Embedded cover art will be extracted and used only if there are no images in the book folder.

tagAudio Tracks

An audiobook contains tracks. Tracks are audio files assigned a track number.
The track number is parsed from the audio filename and from the ID3 tags of the audio file.
Audiobooks that are made up of multiple discs or cd's will be ordered first by disc number then by track number.

Key ID3 Tags  (case-insensitive)
TrackNumber track, trck, trk
DiscNumber discnumber, disc, disk, tpos

The scanner will choose the more accurate track/disc number between the filename and ID3 tag numbers.

Tracks can be manually ordered and enabled/disabled by pressing the "Manage Tracks" button on the audiobook page.

tagAdditional Metadata

If you have a file named desc.txt in the library item folder it will be used as the description.

If you have a file named reader.txt in the library item folder it will be used as the narrator.

If you have an OPF file with extension .opf in the library item folder it will be parsed.
Details extracted from OPF:

title
author
narrator
publishYear
publisher
isbn
description
genres
language
series
volumeNumber

tagDirectory Structure

Here is an example supported directory structure for Podcasts

Lex Fridman Podcast

 -  audiotrack

#219 – Donald Knuth.mp3

 -  audiotrack

#252 – Elon Musk.mp3

 -  crop_original

Cover.jpg

Self-Hosted

 -  audiotrack

#69 - Get Off My Lawn.mp3