priority_high

Help needed writing documentation! This website is on github. Join the discussion, report an issue or contact me directly at advplyr@protonmail.com.

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.

tagDocker

Multi-architecture image for amd64, arm64 and arm/v7


docker pull ghcr.io/advplyr/audiobookshelf

docker run -d \
  -e AUDIOBOOKSHELF_UID=99 \
  -e AUDIOBOOKSHELF_GID=100 \
  -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

Note: Remember to change the path to your actual directory and remove the <> symbols

Note: Volume mappings should all be separate directories that are not contained in eachother

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

Multi-architecture image for amd64, arm64 and arm/v7

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

Note: Remember to change the path to your actual directory and remove the <> symbols

Note: 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)

tagDocker

To update your Docker container to the latest version run the following commands

    docker stop audiobookshelf
docker rm audiobookshelf
docker image prune -a
docker pull ghcr.io/advplyr/audiobookshelf:latest
# then use initial run command again
    

tagBook Directory Structure

Here is an example supported directory structure

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.

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

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

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

tagAdditional Metadata Files

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

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.

tagPodcast Directory Structure

Here is an example supported directory structure

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