Tidarr Documentation

Tidarr is a self-hosted Tidal media downloader that supports high-quality audio (up to 24-bit 192.0 kHz).

Core Capabilities:

• Download tracks, albums, playlists, mixes, and music videos.
• Search by keywords or URLs (artist, album, playlist, track, mix).
• Sync playlists, mixes, favorites, and artists using cron.
• Support for linux/amd64 and linux/arm64 architectures.

Integrations:

• Media Management: Beets (tagging), Plex, Jellyfin, and Navidrome (library updates and search buttons).
• Notifications: Gotify, Ntfy, Apprise API, and Webhooks (e.g., Mattermost).
• Automation: Lidarr (BETA - use Tidarr as a Usenet indexer/provider) and a REST API for external tools.
• Post-Processing: Execute custom shell scripts during the post-processing pipeline (after download, before moving to library).

The integration follows this lifecycle:

1. Search: Lidarr queries the Tidarr Newznab indexer (/api/lidarr).
2. Results: Tidarr searches Tidal and returns albums in Newznab format.
3. Grab: Lidarr sends the selected album to the Tidarr SABnzbd download client (/api/sabnzbd).
4. Download: Tidarr downloads the files to a shared volume (e.g., /shared/nzb_downloads/{id}/).
5. Import: Lidarr detects the completed download in the shared volume and imports it from the corresponding path (e.g., /downloads/{id}/).
6. Organize: Lidarr renames and moves the files to your final music library.

Tidarr uses two different processing pipelines depending on how the download is initiated to avoid conflicts with Lidarr's import logic.

Lidarr-triggered downloads

Used when Lidarr initiates the download via the Newznab endpoints. This uses a minimal post-processing pipeline:

1. Download via Tiddl to /shared/nzb_downloads/{id}/
2. ReplayGain applied (if enabled in Tidarr settings)
3. Status marked as completed (files stay in place)
4. Lidarr import handles tagging, renaming, and moving to /music.

Tidarr UI downloads

Used when you trigger a download directly from the Tidarr interface. This uses the full pipeline:

• Download to /shared/.processing/{id}/
• Beets tagging, permissions, and custom scripts
• Move to /music
• Plex/Jellyfin scan and notifications.

Tidarr follows a specific sequence when processing downloads. Custom scripts are injected at two specific points in this lifecycle:

1. Download
2. Beets
3. ReplayGain
4. Permissions
5. custom-script.sh (Pre-move processing)
6. Move to Library
7. custom-post-script.sh (Post-move processing)
8. Plex/Jellyfin/Navidrome Scan
9. Notifications

If you have not provided a tiddl.json file, you must authorize your device. You can do this via the UI token dialog or by running one of the following commands in your terminal:

Using Docker Compose:

docker compose exec -it -e tidarr tiddl auth login

Using Docker CLI:

docker exec -it -e tidarr tiddl auth

Tidarr is configured primarily via environment variables in your Docker setup. Common system-level variables include:

• PUID: User ID for file permissions.
• PGID: Group ID for file permissions.
• UMASK: File mode creation mask.
• PORT: The listening port (defaults to 8484).
• ADMIN_PASSWORD: Sets a password for app access. If not set, no password is required.

environment:
  - PUID=1234
  - PGID=123
  - UMASK=0022
  - PORT=9999
  - ADMIN_PASSWORD=your_secure_password

For interactive sessions or web UI-like behavior, you can use JWT tokens.

1. Login: POST your password to /api/auth to receive a token.
2. Use Token: Include the token in the Authorization header as a Bearer token.

# 1. Login
curl -X POST http://localhost:8484/api/auth \
  -H 'Content-Type: application/json' \
  -d '{"password": "your_password"}'

# 2. Use the token from the response
curl http://localhost:8484/api/settings \
  -H "Authorization: Bearer your-jwt-token"

The recommended method for automation is using a 64-character API key.

How to get your API key:

• Via Docker: Run docker exec tidarr cat /shared/.tidarr-api-key.
• Via Web UI: Navigate to Settings → Authentication → API Key.

How to use it: Pass the key in the X-Api-Key header (recommended) or as a apikey query parameter in your requests.

# Via header (recommended)
curl http://localhost:8484/api/settings \
  -H "X-Api-Key: your-api-key"

# Via query parameter
curl "http://localhost:8484/api/settings?apikey=your-api-key"

Tidarr uses /shared/.processing/ as a temporary folder during downloads. If your configuration drive is small, you should remap the processing folder to a larger media drive to prevent disk space exhaustion during large downloads (e.g., discographies).

volumes:
  - ...
  - /path/to/media-drive/processing:/shared/.processing  # Separate drive for temp downloads

Run Tidarr directly using the docker run command. This command maps port 8484 and sets up the necessary volume mounts for configuration and the music library.

docker run  \ 
	\t--rm \ 
	\t--name tidarr \ 
	\t-p 8484:8484 \ 
	\t-v /any/folder/to/tidarr/config:/shared \ 
	\t-v /any/folder/to/library:/music \ 
    cstaelen/tidarr:latest