Skip to content

FAQ

Jump to bottom
deucebucket edited this page Dec 12, 2025 · 2 revisions

FAQ

General

Is this free?

Yes! The app is free and open source. You just need an API key:

  • Gemini - Free, 14,400 calls/day
  • OpenRouter - Free tier available

Does it work with Audiobookshelf?

Yes! Enable Series Grouping in Settings for Audiobookshelf-compatible folder structure:

Author/Series/1 - Book Title/

Will it mess up my library?

The app is designed to be safe:

  • Drastic changes require manual approval
  • Every fix can be undone
  • Garbage matches are automatically rejected
  • You can review everything before applying

Does it move files or just rename folders?

Just renames folders. Files inside stay exactly where they are - only the folder path changes.

Technical

What APIs does it use?

  1. Audnexus (Audible data)
  2. OpenLibrary (Internet Archive)
  3. Google Books
  4. Hardcover

Why Gemini over GPT-4?

Gemini offers 14,400 free API calls per day, which is plenty for most libraries. GPT-4 would cost money for this volume.

Can I use a local LLM?

Not yet, but Ollama support is on the roadmap.

How does it know what's correct?

It cross-references multiple book databases, then uses AI to verify the best match. If there's uncertainty, it asks for human review.

Docker

Do I need Docker?

No, you can run directly with Python. Docker is just convenient for some setups (UnRaid, Synology, etc.)

Why can't I access my files in Docker?

Docker containers are isolated. You must mount your audiobook folder in docker-compose.yml:

volumes:
  - /your/path:/audiobooks

See Docker Setup for details.

Features

Can it handle multiple libraries?

Yes! Add multiple paths in Settings (one per line), or mount multiple volumes in Docker.

Does it preserve narrator versions?

Yes! Different narrators get their own folders: Book Title {Ray Porter}/ vs Book Title {Jim Dale}/

What about ebooks mixed with audiobooks?

The app detects ebook files and flags them but won't move them. You'll see a note in the issues.

Can I exclude certain folders?

Folders like metadata/, tmp/, cache/ are automatically skipped. For custom exclusions, you'd need to move them outside your library path for now.

What about YouTube rips with no metadata?

The app cleans up messy filenames automatically - strips "Audiobook", "Full Audiobook", "Complete", "Unabridged", years, quality markers, etc. Then searches based on the cleaned title.

Can I search by author or series?

Yes! The search covers titles, authors, series names, and years. Type "jordan" to find Robert Jordan, "2023" for books from that year, etc.

How do I know if a book has complete metadata?

Search results show a completeness percentage (0-100%). Hover to see which fields are missing. Green = complete, red = needs work.

Can I manually match a book?

Yes! Click the edit (pencil) button on any queue item to search the 50M+ book database manually and select the correct match.

Clone this wiki locally