This page aims to answer common questions. Don't see your question? Come and join the community on Discord or Matrix (links below and above).

Jump to a specific section:

General FAQ

This section aims to answer common general questions.

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.

I have a feature request. How should I bring this up?

First, check the GitHub issues. There are two repositories, one for the server and web client, and one for the apps. You may need to try a few different search terms because someone else may have used different words to explain what they wanted.

If your feature request already exists, you can react with the "thumbs up" reaction to the top comment. Please don't bump posts by just saying "+1" or "I also want this" unless you have something to add to the feature request. You can also express support for an existing feature request in Discord/Matrix.

If your feature request does not exist, you can create a new Feature Request or talk about it on Discord/Matrix.

Server FAQ

This section aims to answer common questions related to the server and managing files.

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

NOTE: Force Re-Scan was incorporated into a normal scan and has been removed beginning in version 2.4.0.

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?

NOTE: Beginning in version 2.4.5, the scanner was rewritten to be more configurable. See here.

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.

A scan will only overwrite metadata on your items in Abs if you have the server setting "Prefer audio metadata" enabled. "Prefer audio metadata" will use the meta tags on your audio files. 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

Should I use mp3 or m4b (or something else)?

It's really up to you. If you're using other devices or software, you should check what file formats and codecs they support.

MP3 is supported by pretty much everything. A lot of books are obtained as a collection of mp3 files, especially from CDs, and some people prefer to keep the files as mp3 files so they have better support. Note that ABS has some outstanding issues with seeking within very long mp3 files.

M4B is convenient if you want to have 1 file per book. This file format is supported on a number of devices, but does not have as good of support as mp3. Most phones and web browsers shouldn't have any problems.

Note: Apple does not have good opus support, so if you're wanting to convert your media to opus, you will not be able to download the media to your Apple devices for offline playback. You will still be able to steram the media from the server on Apple devices because the server will transcode on the fly.

I'm still confused about what Docker and containers are and how they work?

This answer is not meant to replace other documentation (such as the official Docker documentation), but to provide a better introductory overview of Docker for ABS.

To run a Docker container, you first pull an image from the internet and then run a copy of the image as a container. You can run multiple containers from the same image, but changes to one container will not affect the image or other containers. When you want to update, you pull a new image down and then replace the container that's running. Pulling and running the new image is handled automatically by docker-compose or Portainer. Deleting the container deletes everything that was within the container, so if you want your data to persist (such as your library and users), you need to store the data outside of the container.

Data is stored externally using mounts (in red). Each mount consists of two parts, the path on your computer (in green) and the path within the Docker container (in blue). Both parts are separated by a colon.

Docker mounts illustration

The path on the computer can be anywhere the user running Docker has permissions to access. You can also have as many of these mounts as you want, so if you want multiple audiobook folders, you can just add more (see Library Creation Guide). If you don't provide mounts, the container cannot see anything outside of the container to store your data or see your books.

There are also volume mounts, but this only discusses bind mounts.


This section aims to answer common questions related to the app.

Something stopped working after an app update

Sometimes things behave weirdly after the app or server updates.

First, try clearing the app's cache, or uninstalling and reinstalling the app. This will require you to sign in to all servers again.

If your issue persists, feel free to ask in Discord/Matrix or look for an existing GH issue.

When will the apps be out of beta?

The apps will be out of beta when they are deemed to be stable enough and all of the desired features are added. There are still a number of features missing and other quirks that we want to figure out before leaving beta.

Android has more features than iOS, but all of these features are planned for iOS (with no estimate on when any given feature is implemented).

UPDATE: Due to the ever increasing requests to join the TestFlight, the iOS app will likely be released before all planned features are realized to at least allow people to use the app. There is still not an estimate on when this will happen. This full release will not have feature parity with the Android app, should not have show-stopping bugs, and will likely lag behind the releases within TestFlight.

A checklist tracking the main remaining bugs is located here. Please do not leave additional comments on this issue that are just requests to release the app, this has already been communicated in various GitHub and Discord discussions (see General FAQ).

How do I get an invite to Testflight/The iOS beta is full?

To join the iOS beta, you first need to have the TestFlight app installed on your device. From that same device, click on the "Download on the App Store" link on this site. The invite code is embedded in the link.

Apple has a hard limit on how many people can be a part of the beta. Users who are not keeping the iOS app up to date are periodically removed from the beta to make room for others.

Sometimes, there's a problem on Apple's end that prevents removing old accounts, so it may be some time before more spots are available.

Why can't I do X in the app?

Features are still being added and bugs are still being worked out.

The apps are designed to allow you to use the server, not manage the server. Some management functionality may eventually be added, but if you want to manage the server from your phone you will need to use the web browser. Note that some buttons may not show up in the mobile view and you will need to either switch to landscape or the Desktop view if a button is missing.