Make sure you read all setting descriptions and usage.
Change the variables in the script section User config according to your needs.
All the parameters MUST have a value set (there is only basic validation).
You can avoid to change settings in the script itself by creating a file named myconfig and put all the settings in it. The script will load this file if it exists, otherwise it will use default values from script itself.
myconfig file takes precedence over internal settings.
- Script main settings
- Download settings
- Metadata related settings
- Conversion settings
- File move settings
- Debug settings
This variable holds the profile name created with audible-cli.
It should match one of the existing JSON file in ~/audible/
Example config (
~/audible/myprofile.json):
AUDIBLECLI_PROFILE=myprofile
Location of the downloaded library history files. Those files are TSV files containing your entire list of Audiobooks (and Podcasts) and delta TSV files.
Snapshot of what it looks:
2024-02-01_library_full.tsv 2024-02-01_library_new.tsv 2024-03-01_library_full.tsv 2024-03-01_library_new.tsv 2024-04-01_library_full.tsv
Example config:
HIST_LIB_DIR=$HOME/Audible/lib_history
This flag allows to download the full history TSV file of your Audible library each time the script is run. If you run the script every day I recommend disabling it. If you run every week or month then you can keep it to 'true'.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
HIST_FULL_LIB=true
Note: This setting is ignored when using the container. You MUST use volume mapping instead.
This is the full path and filename where the script stores the two last execution times. The next run will use the last execution time to download only new audiobooks. If you want to force a full sync, delete the file and run again.
The status file stores the complete date of the script's last execution (the date is formulated as +%Y-%m-%d).
Example config:
STATUS_FILE=$HOME/Audible/audible_last_sync
Note: This setting is ignored when using the container. You MUST use volume mapping instead.
This is the file location where is stored all information about the audiobooks moved to your personal library.
Example config:
LOCAL_DB=$HOME/Audible/personal_library.tsv
This flag tells the script to skip any kind of processing (download / metadata / conversion & file move) if the Audiobook is found in personal library.
Example config:
SKIP_IFIN_LOCAL_DB=true
This flag allows downloading companion PDF file for each audiobook (if there is any).
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DOWNLOAD_PDF=true
This flag allows downloading annotations (bookmarks) for each audiobook (if there is any).
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DOWNLOAD_ANNOT=true
This flag allows downloading art covers for each audiobook.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DOWNLOAD_COVERS=true
This parameter allows to specify the cover sizes to download for each audiobook. Multiple values are allowed. 500 seems the default size for every Audible audiobooks.
Allowed values, any mix of the following:
252 315 360 408 500 558 570 882 900 1215
Example config:
DOWNLOAD_COVERS_SIZE=(500 1215)
This flag allows to download your Audible account wishlist.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DOWNLOAD_WISHLIST=false
This setting is the concurrency level during Audiobook download. At this moment it doesn't do much because all audiobooks are not downloaded in parallel because of an issue with audible-cli (mkb79/audible-cli#218)
It sets the parallel level inside audible-cli (for example it parallelizes download of covers, AXX, annotations for a single audiobook).
Example config:
DOWNLOAD_JOBS=2
Numbers of retries if a download fails. Careful of not hammering Amazon servers by keeping this setting low as there is no cooldown in the script.
Example config:
DOWNLOAD_RETRIES=3
AAX & AAXC Audible files will be downloaded here
Example config:
DOWNLOAD_DIR=$HOME/Audible/MyDownloads
Note: This setting is ignored when using the container. You MUST use volume mapping instead.
This setting allow to force the download option during audiobook download.
Allowed values:
| Value | Description |
|---|---|
| --aax-fallback | Download book in aax format and fallback to aaxc, if former is not supported. |
| --aax | Download book in aax format. |
| --aaxc | Download book in aaxc format incl. voucher file. |
Example config:
DOWNLOAD_AAX_OPTS=--aax-fallback
Parallelization setting for metadata processing. This parameter allows the user to specify the number of jobs for metadata extraction.
Allowed values: any number >= 1
Example config:
METADATA_PARALLEL=3
This setting allow to specify the source of metadata. It can be aax, meaning that only metadata from AAX/AAXC files will be considered, or all which means metadata will be fetched from original AAX/AAXC files, but also from mediainfo tool extraction, and finally also from library file.
Allowed values:
- 'aax'
- 'all'
Example config:
METADATA_SOURCE=all
Use Tika for language detection if title description/comments is long enough.
(slow) For local java execution, the jar file must be in the same directory of this script.
(faster) For remote execution, just put the URL of your Tika server.
Allowed values:
- Full path of jar file name
- HTTP URL of Tika server
Example config:
METADATA_TIKA=tika-app-2.9.2.jar
Example config:
METADATA_TIKA=http://mytikahost:9998
I noticed that author/narrators metadata was not always clean, so I added a pattern matching. If you want to remove all authors that match this regex, set it here.
The script first split author between ',' and then remove all authors that match this regex (this is a non-case-sensitive regex match).
Basically any authors/narrators matching any of the regex words will be removed from the list.
This applies also to narrators.
Allowed values: regex string
- '*' => keep all authors
- 'traducteur|traductrice|editeur|editrice' => remove all authors matching any of these words
Example config:
METADATA_CLEAN_AUTHOR_PATTERN='traducteur|traductrice|editeur|editrice|editor|illustrateur|éditeur|éditrice'
If an audiobook has multiple authors, this flag allows the script to discard all authors that are identified by a single word name (like pseudo/nicknames/etc.).
This setting is ignored if there is only a single author.
This applies also to narrators.
Note: This was a dirty workaround to bad AudioBookShelf metadata parser. But it gets fixed.
Allowed values:
- 'true' or anything else => Keep single name authors
- 'false' => Discard single name authors
Example config:
METADATA_SINGLENAME_AUTHORS=false
This flag allows the script to skip current metadata processing if the final metadata final is already present.
Allowed values:
- 'true'
- 'false'
Example config (default value):
METADATA_SKIP_IFEXISTS=false
Behavior of the script while processing audiobook chapters.
Possible values are:
- 'keep' => do not modify chapters, keep the chapters defined in the AAX/AAXC files
- 'updatetitles' => only try to update chapter titles with the python helper script
- 'rebuild' => fully rebuild all the chapters based on Audible chapters.json file
Example config (default value):
METADATA_CHAPTERS=rebuild
This parameter allow the user to select the output format of the converted audiobooks.
Allowed values:
- OGG => Convert audiobooks to OGA files
- MP4 => Convert audiobooks to M4B files
Example config:
CONVERT_CONTAINER=OGG
This parameter sets the target bit rate of the converted file. Lower bit rates mean smaller sizes but also lower quality.
Allowed values: any string that can be parsed by ffmpeg (ex: 96k, 128k, etc.)
Example config:
CONVERT_BITRATE=96k
This setting delegates to the script the calculation of the target bitrates of all converted files.
Allowed values:
- 'false' => disable this feature and use only fixed bitrate
- or a ratio like 1/2, 1/3, 2/3 etc....
Example config:
CONVERT_BITRATE_RATIO=2/3
This parameter allow the user to select VBR or CBR for the final encoding. OGG and MP4 containers accepts different values.
Allowed values:
For OGG container:
| Allowed value | Description |
|---|---|
| cbr | Constant bitrate encoding |
| vbr | Variable bitrate encoding |
For MP4 container:
| Allowed value | Description |
|---|---|
| cbr | Constant bitrate encoding |
| any decimal value between 0.1 and 2 | Variable bitrate encoding (higher value means higher quality) |
Example config (for OGG container):
CONVERT_CBRVBR=vbr
Example config (for MP4 container):
CONVERT_CBRVBR=cbr
Parallelization setting for file conversion. This parameter allows the user to specify the number of jobs for audiobook conversion. This is entirely independent of METADATA_PARALLEL.
Optimal setting depends on how many cores and memory you have. Usually ffmpeg takes 1 to 2 threads and ~800 MB of memory per encoding process.
Allowed values: any number >= 1
Example config:
CONVERT_PARALLEL=3
If an audiobook was previously converted to OGA but not moved to target library, it may be still present in download directory, this flag tells the script to skip conversion of such Audiobooks.
This setting is only valid when you select OGG as container.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
CONVERT_SKIP_IFOGAEXISTS=false
If an audiobook was previously converted to M4B but not moved to target library, it may be still present in download directory, this flag tells the script to skip conversion of such Audiobooks.
This setting is only valid when you select MP4 as container.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
CONVERT_SKIP_IFM4BEXISTS=false
This flag allows only decrypt AAX/AAXC when using MP4 container, it also overrides all bitrate options.
It also requires CONVERT_CONTAINER=MP4.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
CONVERT_DECRYPTONLY=false
When using CONVERT_DECRYPTONLY option, this parameter tells the script to add full metadata in the decrypted file.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
CONVERT_DECRYPTONLY_WITHMETA=true
| Key | Description |
|---|---|
| title | audiobook title |
| album | audiobook title |
| subtitle | audiobook subtitle |
| year | publish year |
| lang | language country code (e.g.: en, de, fr, etc.) |
| language | language country code (e.g.: en, de, fr, etc.) |
| genre | genre list (should not be used in any scheme) |
| artist | author |
| album_artist | author |
| composer | narrator |
| asin | ASIN |
| audible_asin | ASIN |
| copyright | Copyright text (should not be used in any scheme) |
| publisher | publisher (not relevant in any naming scheme) |
| comment | long description of the audiobooks (should not be used in any scheme) |
| series | Series name |
| mvnm | Series name |
| series-part | Series volume |
| mvin | Series volume |
It is recommended to stick with the following ones:
- title
- subtitle
- lang
- artist
- asin
- series
- series-part
In short the script will produce dynamic directory names based on metadata and aggregated based on user settings.
Directory as follows:
DEST_BASE_DIR + DEST_DIR_NAMING_SCHEME_AUDIOBOOK + DEST_BOOKDIR_NAMING_SCHEME_AUDIOBOOK
Audiobook filename:
DEST_BOOK_NAMING_SCHEME_AUDIOBOOK
These settings can be confusing pay attention to the parameter names!
Base directory for converted files (will be created if it doesn't exist). If you want your converted files in a different location, change this setting.
Example config:
DEST_BASE_DIR=$HOME/AudioBookShelf/audiobooks
Note: This setting is ignored when using the container. You MUST use volume mapping instead.
Directory path for audiobooks, it will be created under DEST_BASE_DIR.
Example: (artist series) will produce /Isaac Asimov/Foundation.
Keep the keys inside parentheses. If a key is non-existent for an audiobook then it's ignored.
To have only one directory per audiobook then use empty value like () and look for next parameter to configure the naming scheme of the audiobook directory.
Allowed values:
- any combination of the available keys
- or empty ()
Example config will produce /artists/series directory:
DEST_DIR_NAMING_SCHEME_AUDIOBOOK=(artist series)
Audiobook DIRECTORY naming scheme (cannot be empty).
This is the directory where the audiobook will be moved, it is created under DEST_DIR_NAMING_SCHEME_AUDIOBOOK.
Use "%string" to insert custom text in the file name example: (series-part "% - " title) will produce a directory named 1 - audiobook_title.
Custom string parameters are ignored if they are in the start of the naming scheme, in previous example (series-part "% - " title) if 'series-part' is not defined for an audiobook then only 'title' will be used.
Keep the keys inside parentheses.
Allowed values:
- any combination of the available keys
- and custom user strings starting with '%' (example: '% - ')
Example config:
DEST_BOOKDIR_NAMING_SCHEME_AUDIOBOOK=(series-part "% - " title)
Audiobook FILE naming scheme (cannot be empty).
Use "%string" to insert custom text in the file name example: (series-part "% - " title).
The same rules apply here as in DEST_BOOKDIR_NAMING_SCHEME_AUDIOBOOK.
Allowed values:
- any combination of the available keys
- and custom user strings starting with '%' (example: '% - ')
Example config:
DEST_BOOK_NAMING_SCHEME_AUDIOBOOK=(title)
Destination directory overwrite mode (cannot be empty)
Allowed values:
- 'true' or 'ignore': If audiobook destination directory exists then overwrite files in it, other files in directory are preserved
- 'remove': If audiobook destination directory exists then remove it and recreate it (all existing files in it will be deleted)
- 'keep': If audiobook destination directory exists then create a new one with an incremental suffix
- 'false' or any other value: If audiobook destination directory exists then skip processing to next audiobook
Example config:
DEST_DIR_OVERWRITE=true
This flag allows the user to specify if cover image should be copied to audiobook destination directory. If the flag is set then a copy of the largest cover will be created in the audiobook destination directory. Does nothing if no covers are found.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DEST_COPY_COVER=true
This flag allows the user to specify if PDF should be copied to audiobook destination directory. Does nothing if no PDF exists.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DEST_COPY_PDF=true
This flag allows the user to specify if JSON chapters file should be copied to audiobook destination directory. Does nothing if no PDF exists.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DEST_COPY_CHAPTERS_FILE=true
This flag allows the user to specify if JSON annotations/bookmarks file should be copied to audiobook destination directory. Does nothing if no PDF exists.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DEST_COPY_ANNOT_FILE=true
Delete logs generated during the current run (old ones are kept) It is safe to keep to 'true'
Allowed values:
- 'true'
- 'false' or anything else
Example config:
CLEAN_TMPLOGS=true
This flag allows the script to delete downloaded files once they are converted and pushed to final target directory.
Only converted files may be deleted, not converted audiobook remaining are not deleted.
Allowed values:
- 'true' or anything else => Keep downloaded files.
- 'false' => Deleted only files that have been converted
Example config:
KEEP_DOWNLOADS=true
Parameters below are for debugging purposes (default for all boolean parameters is 'false').
Keep all settings below to false for normal behavior.
Global debug flag, also change behavior while moving files to target directory, instead files are copied.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DEBUG=false
This flag is used to repeat the last run without updating the STATUS_FILE.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DEBUG_REPEAT_LAST_RUN=false
### DEBUG_DONT_UPDATE_LASTRUN
Flag to tell if the script should update the STATUS_FILE. This is handy if you want to run a script multiple times for debugging purposes.
Allowed values:
- 'true'
- 'false' or anything else
Example config:
DEBUG_DONT_UPDATE_LASTRUN=false
When DEBUG is enabled and STATUS_FILE contains an old date, this setting only increments the STATUS_FILE date with the specified period of time. This allows manual stepped runs over specified time periods. Requires STATUS_FILE exists and populated.
Allowed values:
- '1 month'
- '2 week'
- '4 days'
- any time period understood by 'date' console command
Example config:
DEBUG_STEP="1 month"
This flag disables all Audible downloads for the current run. If other parts of the scripts are enabled then the scripts expect to find the correct download folder with all the required files in it.
Allowed values:
- 'true' => Disable ALL downloads
- 'false' or any other value => normal behavior
Example config:
DEBUG_SKIPDOWNLOADS=false
This flag disables all audiobook conversions for the current run. If other parts of the scripts are enabled then the scripts expect to find the correct download folder with all the required files in it.
Allowed values:
- 'true' => disable audiobook conversion
- 'false' or any other value => normal behavior
Example config:
DEBUG_SKIPBOOKCONVERT=false
This flag disables all audiobook metadata gathering for the current run. If other parts of the scripts are enabled then the scripts expect to find the correct download folder with all the required files in it.
Allowed values:
- 'true' => disable metadata gathering for audiobooks
- 'false' or any other value => normal behavior
Example config:
DEBUG_SKIPBOOKMETADATA=false
This flag disables the last part of the script and no file will be moved to destination directory for the current run.
Allowed values:
- 'true' => disable moving audiobooks
- 'false' or any other value => normal behavior
Example config:
DEBUG_SKIPMOVEBOOKS=false
This flag, if enabled, prevents the art cover file to be embedded in the converted audiobook. It does not prevent the copy of the cover JPG file into destination directory (use this instead DEST_COPY_COVER).
Allowed values:
- 'true' => disable moving audiobooks
- 'false' or any other value => normal behavior
Example config:
DEBUG_DONTEMBEDCOVER=false
This flag allows more detailed debug output of metadata to be print during script execution.
It also allows you to create a debug file with all the metadata extracted by ffprobe for each converted file.
Allowed values:
- 'true' => disable moving audiobooks
- 'false' or any other value => normal behavior
Example config:
DEBUG_METADATA=false
Debug samples are small AAX and AAXC files that will be used during audiobook conversions instead of using big original files. The metadata is still fetched from the original files and inserted in converted samples.
It is recommended to take the smallest AAX and the smallest AAXC files + voucher.
Full path and file name of the AAX sample file. The file must come from your own Audible account or the script will not be able to process it.
Allowed values:
sample.aax=> file name (must be in BALD directory)- 'false' => normal behavior
Example config:
DEBUG_USEAAXSAMPLE=sample.aax
Note: This setting is ignored when using the container. You MUST use volume mapping instead.
File name of the AAXC sample file. The file must come from your own Audible account or the script will not be able to process it. Do not forget to put aside the voucher file for it.
Allowed values:
sample.aaxc=> file name (must be in BALD directory)- 'false' => normal behavior
Example config:
DEBUG_USEAAXCSAMPLE=sample.aaxc
Note: This setting is ignored when using the container. You MUST use volume mapping instead.