https://github.com/juanra/audiobook-forge/blob/main/README.md

Audiobook Forge 🎧

A blazing-fast CLI tool for converting audiobook directories to M4B format with chapters and metadata. Written in Rust for maximum performance and reliability.

📑 Table of Contents

• Why Audiobook Forge?
• Features
• Installation
• Quick Start
• Documentation
• Performance
• Contributing
• License

---

🎯 Why Audiobook Forge?

When downloading audiobooks, they often come as multiple separate MP3 files — one for each chapter or section. While this works fine with audiobook players, managing your library becomes significantly easier when each audiobook is consolidated into a single file.

Audiobook Forge takes those scattered audio files and merges them into a single M4B file (MPEG-4 Audiobook format), which is the standard for audiobook applications.

📚 Benefits of Single M4B Files

✅ Simplified Library Management - One file per audiobook instead of dozens

✅ Better Metadata & Chapter Support - Embedded chapter markers and complete metadata

✅ Improved Portability - Transfer entire audiobooks with a single file copy

✅ Enhanced Playback Experience - Resume exactly where you left off across devices

✅ Reduced Storage Overhead - Efficient compression while preserving quality

✅ Universal Compatibility - Works with Apple Books, Audiobookshelf, Plex, and most players

---

✨ Features

• 📁 Auto-Detect Current Directory: Run from inside audiobook folders without --root parameter
• ⚡ Parallel File Encoding: Encode files concurrently for 3.8x faster processing (121s → 32s)
• 🚀 Parallel Book Processing: Convert multiple audiobooks simultaneously
• 🎯 Smart Quality Detection: Automatically detects and preserves source audio quality
• 📖 Chapter Generation: Multiple sources (files, CUE sheets, auto-detection)
• 📝 Chapter Updates (v2.9.0): Replace generic chapter names with meaningful titles from Audnex API, text files, or EPUB
• 🎨 Metadata Management: Comprehensive metadata from multiple sources
• 🖼️ Auto-Extract Cover Art (v2.8.0): Automatically extracts embedded cover art as fallback
• 🎭 Interactive Metadata Matching (v2.3.0+): BEETS-inspired fuzzy matching with confidence scoring
• 🎧 Audible Integration (v2.2.0): Fetch comprehensive metadata from Audible's catalog
• 🔄 Batch Operations: Process entire libraries with a single command
• ⚡ Copy Mode: Ultra-fast concatenation without re-encoding when possible
• 🔗 M4B Merge (v2.9.1): Combine multiple M4B files into one without re-encoding
• 🔁 Error Recovery: Automatic retry with configurable settings
• 📊 Progress Tracking: Real-time progress with ETA calculation
• ⚙️ Configuration: Comprehensive YAML-based configuration with CLI overrides

---

💖 Support This Project

If you find audiobook-forge useful, please consider supporting its development!

Your sponsorship helps:

• 🚀 Active Development: Keep the project maintained and add new features
• 🐛 Bug Fixes: Respond quickly to issues and edge cases
• 📚 Documentation: Maintain comprehensive guides and examples
• 🆓 Free & Open Source: Keep audiobook-forge free for everyone

Every contribution, no matter the size, is deeply appreciated! 🙏

---

📦 Installation

Quick Install

cargo install audiobook-forge

Dependencies

Install required tools:

macOS:

brew install ffmpeg atomicparsley gpac

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg atomicparsley gpac

Fedora/RHEL:

sudo dnf install ffmpeg atomicparsley gpac

Verify Installation

audiobook-forge check

📖 Detailed installation guide: See docs/installation.md

---

🚀 Quick Start

Convert a Single Audiobook

# Auto-detect: Run from inside an audiobook folder
cd "/path/to/My Audiobook"
audiobook-forge build

# Or specify the path explicitly
audiobook-forge build --root "/path/to/My Audiobook"

Batch Process Multiple Audiobooks

audiobook-forge build --root "/path/to/audiobooks" --parallel 4

With Audible Metadata

# Rename folders with ASINs: "Book Title [B00G3L6JMS]"
audiobook-forge build --root /audiobooks --fetch-audible

Interactive Metadata Matching

# Match existing M4B files with Audible metadata
audiobook-forge match --file "Book.m4b"

# Batch match entire directory
audiobook-forge match --dir /path/to/m4b/files

Update M4B Chapters (v2.9.0) 🆕

Replace generic chapter names ("Chapter 1", "Chapter 2") with meaningful titles from multiple sources:

# Update chapters from Audnex API (Audible chapter data)
audiobook-forge metadata enrich --file "Book.m4b" \
  --chapters-asin B08V3XQ7LK

# Update from text file (simple, timestamped, or MP4Box format)
audiobook-forge metadata enrich --file "Book.m4b" \
  --chapters chapters.txt \
  --merge-strategy keep-timestamps

# Update from EPUB table of contents
audiobook-forge metadata enrich --file "Book.m4b" \
  --chapters book.epub

# Update chapters only (skip metadata enrichment)
audiobook-forge metadata enrich --file "Book.m4b" \
  --chapters chapters.txt \
  --update-chapters-only

Supported chapter sources:

• Audnex API: Fetch official Audible chapter data by ASIN
• Text files: Simple (one per line), timestamped (HH:MM:SS Title), MP4Box format
• EPUB files: Extract from table of contents

Merge strategies:

• keep-timestamps: Update names, preserve existing timestamps (default for text/EPUB)
• replace-all: Replace entire chapter list with new data
• skip-on-mismatch: Error if chapter counts don't match
• interactive: Prompt for each file (default)

📖 Complete usage guide: See docs/usage.md

M4B Merge (v2.9.1) 🆕

Combine multiple M4B files into a single file without re-encoding:

# Auto-detect sequential parts (Part 1, Part 2, Disc 1, etc.)
audiobook-forge build --root /path/to/book

# Force merge even without detected pattern
audiobook-forge build --root /path/to/book --merge-m4b

Supported naming patterns:

• Part patterns: Part 1, Part 2, Pt 1, Pt. 1
• Disc patterns: Disc 1, Disc1, CD1, CD 1, Disk 1
• Numeric suffix: Book 01.m4b, Book 02.m4b

Features:

• ⚡ Lossless audio concatenation - No re-encoding, preserves original quality
• 📖 Chapter preservation - All chapters merged with adjusted timestamps
• 📝 Metadata copying - Metadata from first source file is preserved
• 🔍 Smart detection - Automatically identifies related files by naming pattern

---

📚 Documentation

Comprehensive documentation is available in the /docs directory:

• Installation Guide - Setup and dependencies
• Usage Guide - Commands, examples, and workflows
• Configuration Guide - All configuration options
• Metadata Guide - Metadata management and Audible integration
• Troubleshooting Guide - Common issues and solutions

Quick Reference

Essential Commands:

audiobook-forge build                    # Convert audiobook (auto-detect)
audiobook-forge build --root /path       # Convert with explicit path
audiobook-forge organize --root /path    # Organize library
audiobook-forge match --file book.m4b    # Interactive matching
audiobook-forge metadata fetch --asin ID # Fetch Audible metadata
audiobook-forge config show              # Show configuration
audiobook-forge check                    # Verify dependencies

Key Configuration:

performance:
  enable_parallel_encoding: true  # 3.8x faster encoding
  max_concurrent_encodes: "auto"

metadata:
  auto_extract_cover: true  # Auto-extract embedded cover art (v2.8.0)
  audible:
    enabled: false
    region: "us"

See docs/configuration.md for complete options.

---

📊 Performance

Benchmarks

Parallel File Encoding (v2.1.0+):

Mode	Time	CPU Usage	Speedup
Serial encoding	121.5s	13%	Baseline
Parallel encoding	32.1s	590%	3.8x faster 🚀

Test: 10-file audiobook (~276MB) on 8-core CPU

Overall Performance vs Python:

Operation	Python	Rust v2.0	Rust v2.1+	Speedup
Startup	~500ms	~10ms	~10ms	50x
Single book (copy)	45s	12s	12s	3.8x
Single book (transcode)	180s	65s	17s	10.6x 🚀
Batch (10 books)	25m	8m	2.5m	10x 🚀
Memory	~250 MB	~25 MB	~25 MB	10x less

Performance Tips

1. Enable parallel encoding (default in v2.1.0+)
2. Use parallel workers: --parallel 4 or more
3. Enable copy mode: Automatic for M4A/AAC files
4. Use SSD storage: Faster I/O for large libraries
5. Apple Silicon: Hardware acceleration with aac_at encoder

---

🎯 Supported Formats

Input

• MP3 (.mp3) - MPEG Audio Layer III
• M4A (.m4a) - MPEG-4 Audio
• AAC (.aac) - Advanced Audio Coding

Output

• M4B (.m4b) - MPEG-4 Audiobook with embedded chapters and metadata

Metadata Sources

• Local: ID3 tags, M4A atoms, CUE sheets, filenames, folder names
• Auto-Extract: Embedded cover art from MP3/M4A files (v2.8.0)
• Audible: Comprehensive metadata from 10 regional stores (v2.2.0)
• Interactive: Fuzzy matching with confidence scoring (v2.3.0+)

---

⚙️ Configuration

Configuration file: ~/.config/audiobook-forge/config.yaml

# Initialize default configuration
audiobook-forge config init

# Show current configuration
audiobook-forge config show

# Edit configuration
audiobook-forge config edit

Example configuration:

performance:
  enable_parallel_encoding: true
  max_concurrent_encodes: "auto"

processing:
  parallel_workers: 4
  skip_existing: true

metadata:
  auto_extract_cover: true
  audible:
    enabled: false
    region: "us"
    download_covers: true

📖 Complete configuration reference: See docs/configuration.md

---

🔧 Common Issues

FFmpeg not found

brew install ffmpeg                    # macOS
sudo apt install ffmpeg                # Ubuntu/Debian

Permission denied

chmod -R u+rw /path/to/audiobooks

Out of memory

audiobook-forge build --root /path --parallel 1

📖 Complete troubleshooting guide: See docs/troubleshooting.md

---

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run tests: cargo test
5. Run linter: cargo clippy
6. Format code: cargo fmt
7. Commit: git commit -m "feat: add my feature"
8. Push and open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License Summary:

• ✅ Commercial use
• ✅ Modification
• ✅ Distribution
• ✅ Private use
• ⚠️ Liability and warranty disclaimer

---

🙏 Acknowledgments

• Original Python version: This Rust rewrite delivers 3-4x better performance
• FFmpeg: The backbone of audio processing
• Rust community: For excellent crates and tooling
• Contributors: Thanks to all who have contributed

Built With

• Rust - Systems programming language
• Tokio - Async runtime
• Clap - CLI framework
• FFmpeg - Audio/video processing
• AtomicParsley - Metadata embedding
• MP4Box/GPAC - MP4 container tools

---

📞 Support

• Documentation: docs/ folder
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ and 🦀 (Rust)