audible-util is a command-line utility for converting Audible .aaxc audiobook files into standard audio formats (MP3, WAV, FLAC) using a voucher file generated by audible-cli. It leverages ffmpeg and ffprobe for decoding and metadata extraction, providing a robust and extensible tool for audiobook enthusiasts and archivists.

Features

Converts Audible .aaxc files to MP3, WAV, FLAC, OGG, or M4A.
Uses voucher files from audible-cli for decryption.
Automatically infers voucher file if not specified.
Chapter splitting - Split audiobooks into individual chapter files.
Hierarchical chapter organization - Organize chapters into folders based on book structure.
Smart chapter merging - Merge short chapters to prevent audio gaps.
Flexible naming formats - Customize how chapter files are named.
Duration filtering - Filter out chapters below a minimum duration.
Extensible output format system (easy to add new formats).
Enhanced progress reporting - Real-time progress bars with ETA, speed, bitrate, and file size information.
Verbose progress mode - Detailed logging and additional progress metrics for long conversions.
Machine-readable output - JSON progress events perfect for integration with Python, shell scripts, and automation tools.
Multi-core processing - Configurable FFmpeg threading for optimal CPU utilization and faster conversions.
Helpful error messages and validation.
Short CLI options - Use -s, -v, -o, etc. for faster command entry.

Installation

Prerequisites

Rust (edition 2021 or later): Install Rust
ffmpeg and ffprobe: Must be installed and available in your PATH.
- The tool checks for these dependencies before any processing and will provide a clear error if they are missing.
- On Ubuntu/Debian:
```
sudo apt-get install ffmpeg
```
- On macOS (Homebrew):
```
brew install ffmpeg
```
- On Windows: Download from ffmpeg.org and add to your PATH.

Build from Source

Clone the repository and build with Cargo:

git clone https://github.com/yourusername/audible-util.git
cd audible-util
cargo build --release

The binary will be in target/release/audible-util.

Usage

All user-provided arguments and files are validated before any processing begins. The tool will check:

That the input .aaxc file exists, is readable, and has the correct extension.
That the voucher file exists and is readable (if provided or inferred).
That the output directory exists and is writable (if a custom output path is provided).
That ffmpeg and ffprobe are installed and available in your PATH.

If any of these checks fail, you will receive a clear, actionable error message.

Basic Command

audible-util -a /path/to/book.aaxc -v /path/to/book.voucher

If -v is omitted, the tool will look for a voucher file named <book>.voucher in the same directory as the .aaxc file.

CLI Options

Option	Short	Type	Required	Description
`--aaxc-path`	`-a`	Path	Yes	Path to the input `.aaxc` file
`--voucher-path`	`-v`	Path	No	Path to the voucher file (from audible-cli). Inferred if not provided.
`--output-path`	`-o`	Path	No	Output file or directory. Defaults to `<album>.<ext>` in current directory.
`--split`	`-s`	Flag	No	Split output into chapters/segments. Requires chapters.json file.
`--min-chapter-duration`	`-d`	Seconds	No	Minimum chapter duration in seconds. Default: 0 (no minimum).
`--chapter-naming-format`	`-f`	Format	No	Chapter naming format. Default: `chapter-number-title`.
`--split-structure`	`-t`	Structure	No	Output structure: `flat` or `hierarchical`. Default: `flat`.
`--merge-short-chapters`	`-m`	Flag	No	Merge short chapters with next chapter instead of filtering them out.
`--output-type`	`-T`	Format	No	Output file type. Default: `mp3`. Supports: mp3, wav, flac, ogg, m4a.
`--verbose-progress`	`-P`	Flag	No	Enable verbose progress reporting with detailed metrics.
`--machine-readable`	`-M`	Flag	No	Enable machine-readable JSON output mode for programmatic parsing.
`--threads`		String	No	Number of threads for FFmpeg processing. Default: `0` (auto-detect all cores).

Example: Convert to FLAC with custom output path

audible-util -a book.aaxc -v book.voucher -T flac -o mybook.flac

Example: Use default voucher and output

audible-util -a book.aaxc

Example: Split into chapters with hierarchical structure

audible-util -a book.aaxc -v book.voucher -s -t hierarchical -o chapters/

Example: Split with short chapter merging and custom naming

audible-util -a book.aaxc -v book.voucher -s -d 10 -m -f number-title -o chapters/

Example: Full featured command with verbose progress

audible-util -a book.aaxc -v book.voucher -s -d 5 -f chapter-number-title -t hierarchical -m -T flac -P -o output_dir/

Example: Convert with verbose progress reporting

audible-util -a book.aaxc -P

Example: Convert with machine-readable JSON output

audible-util -a book.aaxc -M

Example: Use specific number of threads for FFmpeg

audible-util -a book.aaxc --threads 4

Example: Let FFmpeg auto-detect optimal thread count (default)

audible-util -a book.aaxc --threads 0
# or simply
audible-util -a book.aaxc

Voucher File Requirements

The voucher file must be a JSON file generated by audible-cli.
The file is validated for required fields and structure.
If invalid or missing, the tool will display a detailed error message.

Output Formats

MP3 (default): -T mp3
WAV: -T wav
FLAC: -T flac
OGG: -T ogg
M4A: -T m4a

The output format system is extensible. To add a new format, implement the OutputFormat trait in src/cli.rs.

Chapter Splitting

The tool can split audiobooks into individual chapter files using chapter metadata from a chapters.json file.

Chapter File Requirements

The chapter file must be named <book>-chapters.json and placed in the same directory as the .aaxc file.
The file must contain valid JSON with chapter timing information.
The tool will automatically infer the chapter file path if not explicitly provided.

Chapter Naming Formats

chapter-number-title (default): Chapter01_Title.mp3
number-title: 01_Title.mp3
title-only: Title.mp3

Output Structures

flat (default): All chapters in a single directory
hierarchical: Organize chapters into folders based on book structure (e.g., Part_One/Chapter01.mp3)

Chapter Processing Options

Minimum Duration: Filter out chapters shorter than specified duration (-d seconds)
Merge Short Chapters: Merge short chapters with the next chapter to prevent audio gaps (-m)
Smart Filtering: Automatically handles chapters with no content or very short durations

Machine-Readable Output

The --machine-readable flag enables structured JSON output that's perfect for integration with Python programs, shell scripts, and automation tools.

JSON Event Types

`conversion_started`

{
  "type": "conversion_started",
  "total_chapters": 5,
  "output_format": "mp3",
  "output_path": "/path/to/output"
}

`chapter_started`

{
  "type": "chapter_started",
  "chapter_number": 1,
  "total_chapters": 5,
  "chapter_title": "Chapter 1: Introduction",
  "duration_seconds": 120.5
}

`chapter_progress`

{
  "type": "chapter_progress",
  "chapter_number": 1,
  "total_chapters": 5,
  "chapter_title": "Chapter 1: Introduction",
  "progress_percentage": 45.2,
  "current_time": 54.5,
  "total_duration": 120.5,
  "speed": 1.2,
  "bitrate": 128000.0,
  "file_size": 2048576,
  "fps": 25.0,
  "eta_seconds": 55.0
}

`chapter_completed`

{
  "type": "chapter_completed",
  "chapter_number": 1,
  "total_chapters": 5,
  "chapter_title": "Chapter 1: Introduction",
  "output_file": "/path/to/output/Chapter01_Introduction.mp3",
  "duration_seconds": 120.5
}

`conversion_completed`

{
  "type": "conversion_completed",
  "total_chapters": 5,
  "total_duration_seconds": 600.0,
  "success": true
}

`error`

{
  "type": "error",
  "message": "ffmpeg failed to convert chapter",
  "chapter_number": 3
}

Python Integration Examples

Simple JSON Parser

import json
import subprocess

# Run audible-util with machine-readable output
process = subprocess.Popen(
    ["audible-util", "-a", "book.aaxc", "-M"],
    stdout=subprocess.PIPE,
    text=True
)

# Parse each JSON event
for line in process.stdout:
    if line.strip():
        event = json.loads(line)
        print(f"Event: {event['type']}")
        if event['type'] == 'chapter_progress':
            print(f"Progress: {event['progress_percentage']:.1f}%")

Advanced Progress Parser

See examples/python_parser.py for a complete example with progress bars, file size formatting, and error handling.

Usage Examples

Basic Machine-Readable Output

audible-util -a book.aaxc -M

Chapter Splitting with Machine-Readable Output

audible-util -a book.aaxc -s -M -o chapters/

Integration with Python

python3 examples/python_parser.py -a book.aaxc -v book.voucher -s

Advanced Features

Progress Tracking

The tool provides comprehensive progress information during conversion:

Standard Progress Mode

Real-time progress bars for each chapter and overall conversion
ETA (Estimated Time of Arrival) calculations
Conversion speed (e.g., 1.2x real-time)
Current bitrate and file size information
Chapter-by-chapter conversion status

Verbose Progress Mode (`-V` or `--verbose-progress`)

All standard progress information plus:
Detailed time tracking (current/total time)
FPS (Frames Per Second) information
Enhanced logging with detailed progress metrics
More comprehensive progress bar information

Multi-Chapter Conversions

Overall progress tracking across all chapters
Individual chapter progress with detailed metrics
Hierarchical progress display for complex chapter structures
Smart progress estimation based on chapter durations

Machine-Readable Output (`-M` or `--machine-readable`)

JSON Progress Events: Structured JSON output for easy parsing
Event Types: conversion_started, chapter_started, chapter_progress, chapter_completed, conversion_completed, error
Python Integration: Ready-to-use Python examples for parsing
Automation Friendly: Perfect for shell scripts, CI/CD pipelines, and monitoring tools
No Progress Bars: Clean JSON output without visual progress indicators

Error Handling

Comprehensive error handling with clear, actionable messages:

Input file validation (existence, readability, format)
Voucher file validation and parsing
Chapter file validation and parsing
Output directory creation and permission checks
External tool availability checks

Troubleshooting & Common Errors

"Input file does not exist" The path provided to --aaxc-path does not point to a file. Check the file path and try again.
"Input file does not have a .aaxc extension" The input file must have a .aaxc extension.
"Input file is not readable" Check file permissions for the input file.
"Voucher file does not exist" / "Voucher file is not readable" Check the voucher file path and permissions.
"Output directory does not exist" / "Output directory is not writable" Ensure the output directory exists and is writable, or specify a different output path.
"Required external tool 'ffmpeg'/'ffprobe' is not installed or not found in your PATH" Install the missing tool and ensure it is available in your system PATH. See Prerequisites above.
"Could not get file stem from the input file path" Ensure the --aaxc-path points to a valid .aaxc file.
"Failed to open voucher file" Check that the voucher file exists and is readable.
"Failed to parse voucher file" The voucher file must be valid JSON generated by audible-cli.
"Chapter file does not exist" The tool requires a chapters.json file when using -s. Place it in the same directory as the .aaxc file.
"Failed to parse chapter file" The chapter file must be valid JSON with proper chapter timing information.
"No chapters found after filtering" All chapters were filtered out due to minimum duration requirements. Try reducing -d or using -m to merge short chapters.
"Failed to start ffmpeg/ffprobe" Ensure ffmpeg and ffprobe are installed and available in your PATH.
"ffmpeg/ffprobe failed with error" The input file may be corrupt or not a valid Audible AAXC file.
For verbose logs, set the RUST_LOG environment variable:
```
RUST_LOG=info audible-util -a book.aaxc
```

Contribution Guidelines

Contributions are welcome! To contribute:

Fork the repository.
Create a new branch for your feature or bugfix.
Write clear, well-documented code and update/add tests if applicable.
Submit a pull request with a detailed description.

For major changes or questions, please open an issue first to discuss your proposal.

Contact

For questions, issues, or suggestions, please open an issue on the GitHub repository or contact the maintainer at your.email@example.com.

Quick Reference

Most Common Commands

# Basic conversion
audible-util -a book.aaxc

# Convert with custom output
audible-util -a book.aaxc -v book.voucher -o output.mp3

# Split into chapters (flat structure)
audible-util -a book.aaxc -s -o chapters/

# Split with hierarchical structure
audible-util -a book.aaxc -s -t hierarchical -o chapters/

# Split with short chapter merging
audible-util -a book.aaxc -s -d 10 -m -o chapters/

# Full featured command
audible-util -a book.aaxc -v book.voucher -s -d 5 -f chapter-number-title -t hierarchical -m -T flac -o output_dir/

Short Options Summary

-a = --aaxc-path (required)
-v = --voucher-path
-o = --output-path
-s = --split
-d = --min-chapter-duration
-f = --chapter-naming-format
-t = --split-structure
-m = --merge-short-chapters
-T = --output-type
-V = --verbose-progress
-M = --machine-readable

License

This project is licensed under the MIT License.

README.md

audible-util