mirror of
https://github.com/PeacefulBeastGames/audible-util.git
synced 2026-02-04 07:49:03 +00:00
feat: improve output-path handling and error messages
- If --output-path is a directory, output file uses default naming in that directory - If --output-path is a file, use as-is - Improved directory existence/writability checks and error messages - Updated CLI help and documentation to describe new behavior - Cleaned up unused imports and resolved all warnings - Ensured ffmpeg failures are clearly reported to the user
This commit is contained in:
181
README.md
Normal file
181
README.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# 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, or FLAC.
|
||||
- Uses voucher files from `audible-cli` for decryption.
|
||||
- Automatically infers voucher file if not specified.
|
||||
- Extensible output format system (easy to add new formats).
|
||||
- Planned support for splitting output into chapters/segments.
|
||||
- Progress indication and detailed logging.
|
||||
- Helpful error messages and validation.
|
||||
|
||||
---
|
||||
|
||||
## 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 --aaxc-path /path/to/book.aaxc --voucher-path /path/to/book.voucher
|
||||
```
|
||||
|
||||
If `--voucher-path` 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` | | Path | No | Path to the voucher file (from audible-cli). Inferred if not provided. |
|
||||
| `--output-path` | | Path | No | Output file path. Defaults to `<album>.<ext>` in current directory. |
|
||||
| `--split` | `-s` | Flag | No | (Planned) Split output into chapters/segments. Currently not implemented. |
|
||||
| `--output-type` | | mp3/wav/flac | No | Output file type. Defaults to `mp3`. |
|
||||
|
||||
#### Example: Convert to FLAC with custom output path
|
||||
|
||||
```sh
|
||||
audible-util --aaxc-path book.aaxc --voucher-path book.voucher --output-type flac --output-path mybook.flac
|
||||
```
|
||||
|
||||
#### Example: Use default voucher and output
|
||||
|
||||
```sh
|
||||
audible-util --aaxc-path book.aaxc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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): `--output-type mp3`
|
||||
- **WAV**: `--output-type wav`
|
||||
- **FLAC**: `--output-type flac`
|
||||
|
||||
The output format system is extensible. To add a new format, implement the `OutputFormat` trait in [`src/cli.rs`](src/cli.rs:30).
|
||||
|
||||
---
|
||||
|
||||
## Splitting Functionality
|
||||
|
||||
- The `--split` flag is present but **not yet implemented**.
|
||||
- Planned: Split output into chapters or segments using metadata.
|
||||
- To extend: Implement logic to parse chapter metadata and invoke ffmpeg for each segment, using the `OutputFormat` trait for extensibility. See code comments in [`src/main.rs`](src/main.rs:108) for guidance.
|
||||
|
||||
---
|
||||
|
||||
## 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`.
|
||||
|
||||
- **"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 --aaxc-path 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`.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License.
|
||||
Reference in New Issue
Block a user