Libby Downloader

Fork of pdugan20/libby-downloader with expanded CLI functionality and improved chapter handling.

Download audiobooks from Libby to your computer for offline listening.

What's Different in This Fork

• Accurate chapter splitting: The extension now extracts the full table of contents (TOC) from Libby's BIF object, including chapter titles and their exact time offsets within each audio part. The split command uses these timestamps to cut the downloaded parts into individual chapter files — no re-encoding.
• Better metadata: metadata.json now includes a toc array with all real chapter titles and positions, not just one entry per audio file.
• libby split: New command to split downloaded multi-chapter audio parts into individual chapter MP3s. Each output file is named by chapter title (e.g. 001-Finding-Me.mp3) and tagged with full ID3 metadata in one step.
• libby rename: New command to rename hash-based filenames (from older downloads) to sequential chapter-NNN.mp3 names.
• Compatibility with older downloads: The CLI can now discover and process books downloaded by other tools, including books with download.json metadata and hash-named MP3 files.

Features

• One-Click Downloads: Download audiobooks with a single click from your browser
• Full TOC extraction: Captures all real chapter titles and timestamps from Libby
• Chapter splitting: Split multi-chapter audio parts into individual files at exact timestamps
• Interactive CLI: Add book title, author, narrator, and cover art to MP3 files
• M4B Audiobook Creation: Merge chapters into a single M4B audiobook file with correct chapter markers

Quick Start

Extension Only (Download Audiobooks)

git clone https://github.com/YOUR_USERNAME/libby-downloader.git
cd libby-downloader
npm install
npm run build:extension

Then load the extension:

1. Open Chrome and navigate to chrome://extensions/
2. Enable "Developer mode" (top-right toggle)
3. Click "Load unpacked"
4. Select the chrome-extension folder from this project

Download audiobooks:

1. Open an audiobook in Libby using Chrome
2. Click the download button in the top-right navigation bar
3. Downloads save to ~/Downloads/libby-downloads/[Book Title]/

Extension + CLI (Add Metadata to MP3s)

If you also want to tag your MP3 files with metadata:

# Build CLI (in addition to extension)
npm run build

# Install CLI globally
npm link

# Run interactive menu
libby

# Select "Tag MP3 files" and choose your book

CLI Commands

CLI requires installation via npm run build && npm link (see above).

Interactive Menu

libby

Options:

• Split parts into chapters (uses TOC)
• Rename chapters (fix hash filenames)
• Tag MP3 files (add metadata)
• Merge chapters into M4B audiobook
• List all downloaded books
• View book details

Split Command

Splits downloaded audio parts into individual chapter MP3s using the TOC timestamps in metadata.json. Each file is named by chapter title and tagged with full ID3 metadata in one step.

# Interactive (shows list of books)
libby split

# Split specific folder
libby split "Book Title"
libby split ~/Downloads/libby-downloads/BookTitle/

Output files are named NNN-Chapter-Title.mp3 (e.g. 001-Finding-Me.mp3, 004-Chapter-1-Running.mp3). Original part files are moved to a parts/ subfolder for safety.

Requires a metadata.json with a toc array — download with the updated extension first.

Rename Command

Renames hash-based filenames (e.g. a3f8c2...mp3) to sequential chapter-NNN.mp3 names. Useful for books downloaded with older versions of the extension.

libby rename
libby rename "Book Title"

Tag Command

# Interactive (shows list of books)
libby tag

# Tag specific folder
libby tag ~/Downloads/libby-downloads/BookTitle/

# With manual overrides
libby tag ~/path/to/folder/ --title "Title" --author "Author"

Embedded metadata: title, author, narrator, track number, cover art, description

Merge Command

# Interactive (shows list of books)
libby merge

# Merge specific folder
libby merge ~/Downloads/libby-downloads/BookTitle/

Merges individual chapter MP3 files into a single M4B audiobook with:

• Chapter markers at correct timestamps (uses TOC if available, otherwise one per file)
• Embedded metadata (title, author, narrator, cover art)
• 64kbps AAC mono audio (optimized for voice)
• M4B output file saved in the same directory

Requires FFmpeg (bundled automatically).

List Command

libby list

Shows all downloaded books with tagging status.

Architecture

Built with TypeScript and Vite:

• Chrome Extension: Manifest V3 with background service worker, content scripts, and iframe injectors
• CLI Tool: Service-layer architecture with separate business logic, UI presenters, and commands
• Type Safety: Strict TypeScript throughout

For detailed architecture documentation, see ARCHITECTURE.md.

Project Structure

libby-downloader/
├── src/                     # TypeScript source
│   ├── commands/            # CLI command handlers
│   ├── services/            # Business logic (BookService, MetadataService)
│   ├── ui/                  # Presenters and prompts
│   ├── background/          # Extension service worker
│   ├── content/             # Extension content script
│   ├── iframe/              # Extension iframe scripts
│   ├── shared/              # Shared utilities
│   └── types/               # TypeScript definitions
├── chrome-extension/        # Built extension output
└── package.json

Troubleshooting

Extension button doesn't appear

• Must be on audiobook player page (URL contains /open/loan/)
• Refresh the page or check extension is enabled at chrome://extensions/

Downloads fail

• Check chrome://downloads/ for errors
• Chrome will retry automatically

Tagging fails

• Ensure metadata.json exists in book folder
• Re-download if metadata is missing

"Command not found: libby"

CLI requires building before linking:

npm run build    # Builds CLI to dist/cli.js
npm link         # Creates global symlink

Development

# Build
npm run build                # Build both CLI and extension
npm run build:cli            # Build CLI only
npm run build:extension      # Build extension only

# Test
npm run check-all            # Run all checks (typecheck, lint, format, test)
npm test                     # Run tests

# Development
npm run dev -- list          # Run CLI without building
npm run dev:extension        # Watch mode for extension

See ARCHITECTURE.md for detailed documentation.

Disclaimer

This tool is for educational purposes only. Users are responsible for complying with their library's terms of service and respecting copyright agreements.