audiobook-organizer

Audiobook Organizer

A full-stack audiobook management application — Go backend with an embedded React/TypeScript frontend — for scanning, organizing, and enriching your audiobook collection.

Ship it as a single binary or a Docker container. Open http://localhost:8484 and manage everything from your browser.

Quick Start

Docker Compose (recommended)

cp .env.example .env          # edit values as needed
# set AUDIOBOOK_ROOT_DIR in .env to your library path
docker compose up -d --build

The app is available at http://localhost:8484.

From Source

git clone https://github.com/falkcorp/audiobook-organizer.git
cd audiobook-organizer
make build   # builds frontend + backend into a single binary
./audiobook-organizer serve --dir /path/to/audiobooks --host 0.0.0.0

On first run with auth enabled, create the initial admin account from the login screen.

CLI-Only Usage

# Scan a directory for audiobooks
./audiobook-organizer scan --dir /path/to/audiobooks

# Generate iTunes-compatible playlists
./audiobook-organizer playlist

# Update audio file tags with series information
./audiobook-organizer tag

# Run the full pipeline (scan → process → playlists → tag)
./audiobook-organizer organize --dir /path/to/audiobooks

# Inspect metadata for a single file
./audiobook-organizer inspect-metadata /path/to/book.m4b

# Run diagnostics
./audiobook-organizer diagnostics

Features

Library Management

• Scan & Import: Discover audiobooks from import paths and organize them into your library with proper folder structure and naming
• Non-destructive organization: Copy-first approach with SHA256 verification, automatic backups, and rollback support
• Import paths: Configure multiple watched directories (Downloads, NAS mounts, etc.) that are scanned for new content
• File relocation: Move book files between directories from the UI
• Soft delete & restore: Remove books without losing data; purge when ready
• Duplicate detection: Identify duplicate audiobooks across your library
• Blocked hashes: Prevent re-importing unwanted files by hash

Metadata & Enrichment

• Automatic metadata extraction: Reads tags from MP3, M4A, M4B, AAC, FLAC, OGG, and WMA files
• Open Library integration: Fetch and apply metadata from Open Library, including bulk fetch for your entire collection
• Open Library dump import: Download or upload Open Library data dumps for fast offline lookups
• AI-powered parsing (optional): Use OpenAI to intelligently parse filenames and audiobook context into structured metadata
• Metadata editing: Inline editing, batch updates, validation rules, and export/import
• Metadata history: Full change log per field with undo support
• Field-level overrides & locks: Override fetched metadata and lock fields to prevent future overwrites
• Copy-on-write versioning: Track metadata versions with prune support
• Write-back: Push metadata changes back into audio file tags (native TagLib with CLI tool fallback)
• iTunes library import: Validate, map, import, and sync from an iTunes Library XML; write back changes to iTunes-managed files

Organization & Discovery

• Works: Group multiple editions/formats of the same title under a logical "Work" entity
• Version management: Link audiobook versions (abridged, unabridged, different narrators) and set a primary
• Author deduplication: Detect and merge duplicate author entries
• Smart series detection: Pattern matching and fuzzy logic to identify book series from filenames and metadata
• Narrators: Track narrators per audiobook with full CRUD
• Search & filtering: Full-text search across audiobooks, authors, narrators, and series with counts

Web Interface (React + Material-UI)

• Dashboard: Library statistics and at-a-glance status
• Library browser: Grid and list views for your audiobook collection
• Book detail view: Full metadata display, cover art, segment listing, and track info extraction
• File manager: Directory tree browser with import path management
• File browser: Server-side file system navigation
• Operations panel: Monitor active/stale operations with real-time progress via SSE
• Settings page: Configuration management, iTunes import, Open Library dump management, blocked hashes
• System page: Storage quotas, system info, and searchable application logs
• Login & auth: Session-based authentication with admin setup wizard
• Welcome wizard: First-run setup experience
• Keyboard shortcuts: Power-user keyboard navigation
• Announcement banner: Surface system-wide notices
• Toast notifications: Non-blocking feedback for user actions

Backend & Infrastructure