Ultimate Python CLI to handle audiobooks.

Built to be used with audiobookshelf.

---

Features

• 📦 Build M4B audiobook from MP3/M4A files (can be multi-part or one)
• 🎧 Fetch metadata and cover from Audible with ASIN code
• 📤 Extract chapters from M4B audiobook and convert to M4A/MP3
• 🔖 Parse M4B audiobook to convert tags to YAML file

Roadmap

• Fix M4A handle
• Test for one audiobook
• Confirm for override metadata/cover
• Confirm after Audible fetch
• Refact. args
• Refact clear flag
• Review logging
• GitHub tests
• README
• Remove part 1 from name if only one part
• Fix Error Referenced QT chapter track not found
• Fix Error submitting packet to decoder: Invalid data found when processing input / Header missing
• Fix chapter name "Les Montagnes de la Folie : Les Montagnes hallucinées (1931)"

Why?

I have been using audiobookshelf for a long time, and to manage my audiobooks, I used Audiobook Builder (which is a paid program). While this software is very useful for managing audiobooks, when you need to create several in a row, it is time-consuming and tedious, lacking flexibility.

I also needed to create audiobooks in several parts (to help with streaming) but without splitting the chapters into two parts (which is unpleasant). I also needed a CLI capable of reading metadata from a YAML file in order to apply the corresponding tags to the audiobook.

In addition, when I retrieve metadata from Audible, it is rather tedious, and I wanted to be able to do it automatically.

The whole thing needed to be flexible and resilient, offering high-quality audiobooks that could be used directly by audiobookshelf.

Usage

Audible

audible command will fetch metadata from Audible website (web scraping with playwright) to create metadata.yml file and cover.jpg file. You need ASIN code available in Audible URL and shortcut for any audiobook, like ASIN code B0G5SMXT5S for https://www.audible.com/pd/B0G5SMXT5S?ipRedirectOverride=true with Assassin’s Apprentice (The Farseer Trilogy, Book 1) audiobook.

Tip

An ASIN code only works on one Audible domain, and the same book has a different ASIN code between the .com and .fr domains, for example.

audiobook-tool audible <ASIN_CODE>

Flag	Alias	Description	Type	Default
--locale	-l	Audible domain to use	str	None

If you not set --locale flag, CLI will parse all Audible domains to find ASIN audiobook. You can set the --locale flag (can be com, co.uk, fr, de) to speed up the process.

Build

build command is main command of this CLI. This command will create an .m4b audiobook from .mp3 or .m4a source files.

audiobook-tool build /path/to/source_files

Flag	Alias	Description	Type	Default
--clear	-c	Clear covers from source files	bool	False
--asin	-a	ASIN code to fetch Audible metadata before build	str	None
--locale	-l	Audible domain to use	str	None
--output-path	-o	Path where put audiobook files (default is source directory)	str	None
--single	-s	Create only one audiobook (not splitted)	bool	False
--part-size	-p	Size of each part* in MB (default use .env)	int	None

*: ABOUT SPLIT

Metadata & cover

Tip

audible command or build command with --asin flag will create metadata.yml and cover.jpg automtically if ASIN is valid.

Metadata

You can create metadata.yml file in /path/to/source_files to specify tags to use for M4B audiobook, you can use metadata.template.yml as example. These metadata are based on audiobookshelf's Audio Metadata.

• title: used as title and album
• authors: used as artist and album_artist
• narrators: used as composer
• description: used as description and synopsis
• lyrics: used as lyrics
• copyright: used as copyright
• genres: used as genre
• series: used as series
• volume: used as series-part
• language: used as language
• year: used as date
• publisher: used as publisher
• subtitle: used as subtitle and comment
• isbn: used as isbn
• asin: used as asin

title: "The Fellowship of the Ring"
authors: "J.R.R. Tolkien & Christopher Tolkien"
narrators: "Rob Inglis & Andy Serkis"
description: "Sauron, the Dark Lord, has gathered to him all the Rings of Power..."
lyrics: "With a masterful performance by Andy Serkis, who plays Gollum in Peter Jackson's films."
copyright: "©1954 The Tolkien Estate Limited (P)2025 HarperCollins Publishers Limited"
genres: "Fantasy/Fiction"
series: "The Lord of the Rings"
volume: 1.0
language: "English"
year: 2005
publisher: "HarperCollins Publishers Limited"
subtitle: "One Ring To Rule Them All"
isbn: 9780007123827
asin: 0008487278

Cover

For cover, just put cover.jpg into /path/to/source_files and build command will attach it to M4B audiobook.

Docker

Docker compose (recommanded)

docker compose up -d

Docker run

docker build -t audiobook-tool .

docker run -it \
  -v "$(pwd):/app/data" \
  --env-file .env \
  audiobook-tool

Using as CLI

With uv

uv sync

Or with pip

pip install -e .

Use audiobook-tool CLI

audiobook-tool build ./path/to/mp3_directory

Test

Run tests:

pytest

To know more about tests, check docs/tests.md

FAQ

How to convert AAX into M4B?

AAX files are proprietary Audible files protected by DRM. audiobook-tool is not designed to remove this DRM.

To do so, we recommend using tools such as audible-tools.github.io (the quickest and easiest) or Libation (the most comprehensive).

How to download my audiobooks from Audible?

audiobook-tool is not designed to downlod audiobooks from Audible, this tool will simply parse the metadata from Audible if necessary.

To do so, we recommend using tools such as audible-cli.

License

MIT License