therobbiedavis/listenarr repository overview

⁠Overview

Listenarr automates audiobook collection management — similar to Sonarr or Radarr, but for audiobooks.
It can search, download, and organize your library automatically using metadata from Audible and other sources.

Features

• Automated torrent and NZB searches
• Metadata lookup from Audible/Amazon
• Works with qBittorrent, Transmission, SABnzbd, NZBGet
• Web UI for desktop and mobile
• Real-time monitoring and progress tracking
• Configurable file naming and library organization

⁠Supported Architectures

• amd64
• arm64

⁠Usage Example

⁠Docker Compose

services:
  listenarr:
    image: therobbiedavis/listenarr:latest
    container_name: listenarr
    ports:
      - 5000:5000
    environment:
      - LISTENARR_PUBLIC_URL=https://your-domain.com //OPTIONAL: Used for the Discord Bot
    volumes:
      - ./config:/app/config
      - ./audiobooks:/audiobooks
      - ./downloads:/downloads
    restart: unless-stopped

⁠Docker CLI

docker run -d \
  --name=listenarr \
  -p 5000:5000 \
  -e LISTENARR_PUBLIC_URL=https://your-domain.com \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/audiobooks:/audiobooks \
  -v $(pwd)/downloads:/downloads \
  therobbiedavis/listenarr:latest

Web UI → http://localhost:5000⁠

Tags:
latest, stable, nightly, nightly-X.Y.Z, X.Y.Z

⁠Setup

1. Deploy container and access the web UI
2. Add library folders in Settings → Libraries
3. Configure your download clients
4. Add indexers and metadata sources
5. Let Listenarr automate the rest

⁠Discord bot (optional)

Listenarr includes a small reference Discord bot (in tools/discord-bot) that registers a slash command and forwards requests to the running Listenarr API. The bot is optional — the preferred integration is configuring the Discord settings from the Listenarr UI so the server manages the registration for you. Use the steps below for local development or to run the bot separately.

Quick start:

1. Create a Discord application and bot at https://discord.com/developers/applications⁠. Copy the Application (client) ID and the Bot Token.
2. Invite the bot to your guild with the following OAuth2 URL (replace <APP_ID>):

https://discord.com/oauth2/authorize?client_id=<APP_ID>&scope=bot%20applications.commands&permissions=27648

The permissions=27648 value requests the View Channels, Send Messages, Manage Messages, and Embed Links permissions which is the bare minimum permissions needed for the bot to function.

1. Configure Listenarr (recommended):

• Open the Listenarr web UI and go to Settings → Integrations → Discord (or the Discord section in Configuration).
• Set the Discord Application ID to the Application ID you copied.
• Set the Discord Bot Token to the bot token you copied.
• Optionally set Discord Guild ID and Discord Channel ID so the bot registers commands in a specific guild and limits responses to one channel.
• Enable the Discord integration and Save.

When the Listenarr server has the bot token and application ID saved, the server will register the slash command and manage the bot.

Notes and troubleshooting:

• The helper bot reads settings from the Listenarr API; configuring the settings in the Listenarr UI is the recommended path.
• If you see permissions errors when deleting messages, ensure the bot has Manage Messages in the configured channel or invite it again with the proper permissions.

⁠Auto-persist Listenarr URL

To make the helper easier to run, it will automatically persist the Listenarr base URL when first started interactively. Order of precedence:

1. LISTENARR_URL environment variable (explicit)
2. tools/discord-bot/.env file with LISTENARR_URL= (created automatically on first run)
3. Fallback http://localhost:5000

This means you can run the helper once and enter your public domain (for example https://listenarr.example.com) when prompted. The URL is saved to tools/discord-bot/.env so you don't need to export environment variables on subsequent runs.

⁠Support

• Discord: Join Server⁠
• GitHub: Issues & Wiki⁠

⁠Status

Beta software. Expect frequent updates and breaking changes.
Backup your configuration before upgrading.

⁠License

Licensed under AGPL-3.0
© 2024–2025 Robbie Davis

⁠Credits

Built with inspiration from Sonarr and Radarr.
Powered by the open-source community and modern .NET / Vue 3 stack.