# 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](https://github.com/audible-tools/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](https://www.rust-lang.org/tools/install) - **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: ```sh sudo apt-get install ffmpeg ``` - On macOS (Homebrew): ```sh brew install ffmpeg ``` - On Windows: Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to your `PATH`. ### Build from Source Clone the repository and build with Cargo: ```sh 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 ```sh 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 `.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 `.` 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 ```sh audible-util -a book.aaxc -v book.voucher -T flac -o mybook.flac ``` #### Example: Use default voucher and output ```sh audible-util -a book.aaxc ``` #### Example: Split into chapters with hierarchical structure ```sh audible-util -a book.aaxc -v book.voucher -s -t hierarchical -o chapters/ ``` #### Example: Split with short chapter merging and custom naming ```sh audible-util -a book.aaxc -v book.voucher -s -d 10 -m -f number-title -o chapters/ ``` #### Example: Full featured command ```sh 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](https://github.com/audible-tools/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`](src/cli.rs:30). ## 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 `-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: ```sh 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](https://github.com/yourusername/audible-util) or contact the maintainer at `your.email@example.com`. --- ## Quick Reference ### Most Common Commands ```sh # 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.