m4b-cli

A zero-dependency command-line utility for automated audiobook merging, high-quality encoding, and precision metadata tagging.

Designed to operate securely and efficiently, this script acts as a bridge for web-scraped audiobook payloads. It seamlessly digests both raw directories and .zip exports (such as those generated by LibbyRip), handling extraction, cover art downloading, chapter mapping, and containerized audio processing autonomously.

Table of Contents

• Features
• How It Works
• Prerequisites
• Installation
• Usage
• Troubleshooting
• Acknowledgements
• License

Features

• Archive Support: Pass a .zip file directly; it is processed in ephemeral storage and stems are safely deleted afterward.
• Smart Chapter Mapping: Converts relative JSON spine offsets into absolute mp4chaps timestamps.
• Auto-Resolution Cover Art: Dynamically downloads cover images from CDNs if a local file is missing.
• High-Quality Audio: Utilizes libfdk_aac for optimal voice retention and transparent compression.
• Dynamic Bitrate Detection: Uses ffprobe to match the source bitrate and prevent audio degradation.
• Precision Tagging: Employs sandreas/tone to bypass shell limits for extensive descriptions and custom narrator tags.

How It Works

The utility coordinates a multi-stage pipeline to transform raw audio into a finished audiobook:

1. Metadata Parsing: Extracts titles, authors, and narrators from metadata.json and calculates absolute chapter timestamps based on the audio spine.
2. Resource Resolution: Locates or downloads the necessary cover art.
3. Audio Merging: Launches a Podman container running sandreas/m4b-tool to concatenate the source files into a single .m4b file using the detected source bitrate.
4. Metadata Tagging: Launches a second Podman container running sandreas/tone to inject high-fidelity metadata and the cover image directly into the container.

Prerequisites

This script relies entirely on standard Python 3 libraries. However, you must have the following system-level tools installed:

• Python 3.12+
• Podman (Required for secure, rootless container processing)
• FFmpeg (Requires ffprobe in your system PATH)

Installation

macOS (Homebrew)

brew tap alston808/m4b
brew install m4b

Debian / Ubuntu (APT)

Download the .deb release and install via:

sudo apt install ./m4b_1.0.0_all.deb

Manual Installation

git clone [https://github.com/alston808/m4b-cli.git](https://github.com/alston808/m4b-cli.git)
cd m4b-cli
chmod +x m4b
sudo cp m4b /usr/local/bin/m4b

Usage

You can target a pre-extracted folder or pass a .zip directly. By default, the output .m4b is saved to your current working directory.

# Process an exported ZIP archive directly
m4b ~/Downloads/Audiobook_Export.zip

# Process a raw directory
m4b ~/Audiobooks/RawStems/

# Specify a custom output directory
m4b ~/Downloads/book.zip -o ~/Media/Audiobooks/

Troubleshooting

• Podman Permission Errors: Ensure your user has permissions for rootless Podman. You may need to configure subuid and subgid if you encounter volume mounting issues.
• ffprobe Not Found: Ensure FFmpeg is installed and ffprobe is accessible in your system's PATH.
• M4B Generation Fails: Check your Podman logs. Failure is often due to corrupted source stems or insufficient temporary disk space during the merge process.

Acknowledgements

• m4b-tool by sandreas: For audio concatenation and FDK AAC encoding.
• tone by sandreas: For robust, containerized metadata injection.
• LibbyRip by PsychedelicPalimpsest: For the inspiration and structured JSON payload logic.

Author

Alston Alika Albarado

License

MIT License