Book Library Structure

Books are defined as a folder. Single file books can be in the root folder of the library, but otherwise every book must be in its own folder.

Audiobookshelf supports several metadata sources for audiobooks, one of which is the folder structure. If using the folder structure for metadata, the format is {Author}/{Series}/{Book} or {Author}/{Book}.

Directory Structure

Here is an example supported directory structure for Books:

-- Single file books at library root

🎵 Ender's Game.m4b
🎵 Human Action.m4b

-- Author with a standalone book and series of multiple books

📁 Terry Goodkind
  📁 Heart of Black Ice - Sister of Darkness
    🎵 Audio File.m4a
  📁 Sword of Truth
    📁 Vol 1 - 1994 - Wizards First Rule {Sam Tsoutsouvas}
      🎵 Audio Track 1.mp3
      🎵 Audio Track 2.mp3
      🖼️ Cover.jpg
    📁 Vol 2 - 1995 - Stone of Tears
      🎵 Audiobook.m4b

-- Author with a single book

📁 Steven Levy
  📁 Hackers - Heroes of the Computer Revolution {Mike Chamberlain}
    🎵 Audio File.m4a

-- Book folder in library root

📁 1945 - Animal Farm
  🎵 Audiobook.mp3

Book Grouping

If your books are being grouped together as a single book in Audiobookshelf, your directory structure is likely wrong. The following example will group all of the books as a single Sword of Truth Vol 2 book. This incorrect grouping can also happen if you temporarily move a book to an unsupported location when reorganizing files. If books are grouped incorrectly, you will need to remove the book from your library using the Audiobookshelf interface, and then rescan the library to add them back in to the library. This will remove progress for the readded books.

📁 Terry Goodkind
  🎵 Sword of Truth Vol 2.mp3 <-- PROBLEM
  📁 Heart of Black Ice - Sister of Darkness
    🎵 Audio File.m4a
  📁 Sword of Truth
    📁 Vol 1 - 1994 - Wizards First Rule {Sam Tsoutsouvas}
      🎵 Audiobook.m4b

Author Folder Naming

Author names can be extracted from the folder name. Authors can be named as First Last or Last, First. Multiple authors can be included in the folder name, separating each author by ,, ;, & or and.

Some examples of supported author names are shown below.

📁 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

Book Folder Naming

Book folders can include some metadata for the book.

• Series Sequence: Case insensitive & decimals supported.
  • The sequence can be placed anywhere in the folder name.
  • It must be followed by a dash with a space on both sides, or a period followed by a space. For example, 1 - Title or 1. Title.
  • If it is not at the beginning of the folder name, it must be preceded by a dash with a space and Vol, Vol., Volume, or Book. For example, [Text] - Vol. #.
• Publish Year: The publish year must be the first part of the name OR directly after a series sequence and separated by a dash with spaces " - " on both sides. For example, 1994 - [text] or [text] - 1994 - [text].
• Narrator: The narrator must be curly braces. For example, {Sam Tsoutsouvas}.
• Disc Numbers: The title folder can contain subfolders for discs as long as they are named Disc, CD, or Disk with a number following (case insensitive). For example, Disc 1, CD 2, Disk 3, Disc 004, or no space between like Disc1.
• Subtitle: Subtitle parsing must be enabled in the settings. Subtitles must be separated by dash with spaces. For example, [text] - My Subtitle.

Additional examples combining these rules is shown below.

📁 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

File Metadata

Audiobookshelf uses the ID3 metadata tags in audio files to populate data. The server will extract the first cover image from the file metadata if an image file does not already exist in the book folder.

note

Ensure your settings for the metadata priority settings matches your file structure.

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

Audiobook Tracks

An audiobook is made up of tracks, where each audio file is a track. Each track is 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)	Audio Filename
DiscNumber	discnumber, disc, disk, tpos	Number following "Disc" or "CD" (example: "Atlas Shrugged CD 01 - 1.mp3")
TrackNumber	track, trck, trk	First number after removing title, publish year, series, author, disc number

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 with Audiobookshelf by using the Manage Tracks button on the audiobook details page.

Additional Metadata Files

Audiobookshelf supports several other metadata sources from your file system.

The server can read the description from desc.txt and the narrator from reader.txt if these files exist in the library item folder.

Audiobookshelf can also read the following fields from OPF and NFO files:

• title
• author
• narrator
• publishYear
• publisher
• isbn
• description
• genres
• language
• series
• volumeNumber