audible-util

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).
• Progress indication and detailed logging.
• 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.

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

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

---

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

---

Advanced Features

Progress Tracking

The tool provides detailed progress information during conversion:

• Real-time ffmpeg progress for each chapter
• Chapter-by-chapter conversion status
• File counting and validation
• Detailed logging with RUST_LOG=info

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:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Write clear, well-documented code and update/add tests if applicable.
4. 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

---

License

This project is licensed under the MIT License.