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

tagDocker

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
  • 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
  • Windows users will need to remove the \ and run this as a single line

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)

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
  • 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)
  • /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)

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

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)

  • This installation method is still in testing.
  • Only in the nixos-unstable channel for now

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 after a reboot.

{
  users = {
    groups.audiobookshelf.members = [ "audiobookshelf" ];
    users.audiobookshelf.isSystemUser = true;
  };

  systemd.services.audiobookshelf = with pkgs; {
    enable = true;
    description = "Self-hosted audiobook server for managing and playing audiobooks";
    serviceConfig = {
      Type = "simple";
      WorkingDirectory = "/usr/share/audiobookshelf";
      ExecStart = "${audiobookshelf}/bin/audiobookshelf --host 127.0.0.1 --port 8000"
      ExecReload = "${util-linux}/bin/kill -HUP $MAINPID";
      Restart = "always";
      User = "audiobookshelf";
      Group = "audiobookshelf";
    };
    wantedBy = [ "multi-user.target" ];
    requires = [ "network.target" ];
  };
}

You can create a simple SystemD service to automatically start audiobookshelf after a reboot. Write a file audiobookshelf.service to /etc/systemd/system/ with the following contents:

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

tagWindows

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!

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.

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

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

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

* Audio files in the root of the folder will each be treated as books.

tagAuthor Folder Naming

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

Valid author folder names:

Ichiro Kishimi

Kishimi, Ichiro

Ichiro Kishimi, Fumitake Koga

Kishimi, Ichiro, Koga, Fumitake

Ichiro Kishimi & Fumitake Koga

Kishimi, Ichiro & Koga, Fumitake

tagTitle Folder Naming

In addition to the book title, the title folder can include the publish year, volume number, 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 " - ".
  • Volume Number: Case insensitive & decimals supported.
    • The volume number 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 volume number, and separated by " - " on both sides.
  • 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 Series
series-part Volume Number
language / lang Language
isbn ISBN
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

tagFAQ

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