Audiobookshelf Documentation

This repository contains the old version of the Audiobookshelf documentation website (audiobookshelf.org).

Note: The new documentation has moved to a dedicated repository: audiobookshelf-docs.

This site is built using:

• Nuxt.js: Static site framework.
• TailwindCss: For styling.
• PrismJs: For syntax highlighting.

The mobile applications for Android and iOS are open source. You can find the source code, report bugs, or suggest features on the official GitHub repository.

https://github.com/advplyr/audiobookshelf-app

ABS tracks media progress (listen state) only for files physically present on the server.

• Tracking: If you listen to or mark an episode as played, progress is saved just like an audiobook.
• Data Loss: If you delete the episode file from the server, the associated listen state/progress is lost.
• Workaround: If you wish to delete files but maintain a record of what you have heard, you must use an external utility to track progress.

Audiobookshelf uses three primary user roles to manage server access and capabilities:

• Admin: Can modify server settings and has full permissions to update, delete, and upload items by default.
• User: Can access content but cannot modify server settings. They cannot modify library items unless explicitly granted permission.
• Guest: Similar to a 'User', but cannot change their own password.

It is recommended to create a distinct user for every individual using the server.

Audiobookshelf (ABS) is primarily designed to serve local media files. For podcasts, ABS functions by automatically downloading new episodes from an RSS feed to your server for archival and listening.

Key distinction: ABS is not a discovery browser for searching the internet for individual episodes. It is a management and playback system for feeds you have explicitly added to a podcast library. If you require a tool for searching and discovering new podcasts online without downloading them to a server, a standard podcast app is recommended instead.

Collections and Playlists are used to organize books and podcast episodes. While they share features like reordering, descriptions, and user-specific listening progress, they serve different purposes:

Collections

• Visibility: Public (any user with library access can see them).
• Content: Can only contain books.

Playlists

• Visibility: Private (only the creator can see them).
• Content: Can contain both books and podcast episodes.

Shared Features

• Library-specific.
• Listening progress is tracked per user (not shared across users).
• Supports a description field.
• Items can be reordered.
• Cannot contain nested groups (e.g., you cannot put a collection inside another collection).
• Includes a "Play" button at the top for "Play All" functionality.

When using Media Item Shares, be aware of the following technical constraints:

• No Authentication: Anyone with the link can access the media if the server is reachable.
• No Progress Syncing: Playback progress is stored in a client-side cookie, not on the server. Progress will not sync between different devices or browsers.
• No Transcoding: The server performs direct playback only. The client device must natively support the file format and codec used by the media file, otherwise, it will not play.
• Current Scope: Currently, only books can be shared (podcast episode sharing is on the roadmap).

A single library item can contain both an audiobook and one or more ebook files if they are kept in the same folder.

• Primary Ebook: The main ebook file associated with the item. It is identified by a green checkmark in the UI. When you click the "Read" button at the top of the item view, the primary ebook is opened.
• Supplementary Ebooks: Additional ebook files in the same folder. These are used for alternative formats or versions.

Scanner Behavior: When scanning a folder, the scanner prefers EPUB files to be set as the primary ebook. If multiple ebook files exist, the others are automatically designated as supplementary.

Manual Management: You can manually toggle an ebook file between 'primary' and 'supplementary' status in the UI. Note that if all ebook files in a folder are set to 'supplementary', the "Read" button will be hidden from the item view.

API Keys in Audiobookshelf are standalone authentication tokens designed specifically for server-to-server communication and automation scripts. They are part of the JWT authentication system (introduced in v2.26.0).

Key Characteristics:

• User Association: Each key acts on behalf of a specific user and inherits that user's permissions.
• Configurable Expiration: You can set optional expiration dates for security.
• Revocability: Keys can be deactivated or deleted independently without affecting other user sessions.

Important Distinction:

• Use API Keys for scripts and automation.
• Use the standard JWT authentication flow for third-party applications.

Audiobookshelf distinguishes between scanning local files and matching them with online metadata:

• Scanning: An automated process where the server reads local files to extract metadata based on the Library Scanner precedence. This can be triggered by the File Watcher (watching for file changes) or Periodic Scans configured in library settings.
• Matching: A manual operation (or triggered via the server API) where the server takes the metadata found during a scan and attempts to match it against an online metadata provider using the Match or Quick Match features.

Note: Scanning does not automatically fetch data from the internet; you must initiate a Match to get external metadata.

Developers are encouraged to build third-party clients using the Audiobookshelf API. Third-party clients do not need to be open source or free. However, you must adhere to these rules:

• Branding: Do not use the Audiobookshelf name or logo in a way that suggests official affiliation without permission.
• Naming Conventions: The name should be written as audiobookshelf (all lowercase), Audiobookshelf (first letter capitalized), or ABS (all caps).
• No Piracy: Do not use the Audiobookshelf name or logo in any context that promotes or encourages piracy.