mirror of
https://github.com/PeacefulBeastGames/audible-util.git
synced 2026-02-04 07:49:03 +00:00
Ondra-Kavan
9165c0e95d
- Add comprehensive chapter splitting functionality - Support hierarchical and flat output structures - Add smart chapter merging to prevent audio gaps - Implement flexible chapter naming formats - Add duration filtering for chapters - Add short CLI options for all flags (-v, -d, -f, -t, -m, -T) - Update README with complete documentation - Add support for OGG and M4A output formats - Improve error handling and validation
297 lines
10 KiB
Markdown
297 lines
10 KiB
Markdown
# 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 `<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
|
|
|
|
```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 `<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:
|
|
```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. |