Subtidal

Warning

This project is in an beta state! Breaking changes might occur.

Subtidal exposes your Tidal library through the OpenSubsonic API, so you can use any Subsonic-compatible client to browse, search, and stream Tidal's catalog as if it were your own self-hosted music server.

Some highlighted features are:

• Allows you to search and play of the whole Tidal catalogue
• Gives you access to your liked songs, artists, and albums
• Allows to play, create, edit and delete your playlists
• Play Tidal mixes (Daily Mix, My Mix, Discovery) as read-only playlists
• Artist and track radio behind getSimilarSongs, and Tidal's catalogue behind genre browsing
• Recently and most played album lists, with the play queue and bookmarks kept across restarts
• Scrobbles to either last.fm or listenbrainz
• Show AI labels on AI-generated music
• Optional Word-by-word synced provided by Radiant Lyrics

Getting Started

Important

A paid Tidal account is required! This project is not affiliated with Tidal.

Prerequisites: Docker with Compose support.

1. Copy docker-compose.yml and settings.toml
2. Edit settings.toml
   • Choose a username and password
   • Optionally set up either last.fm or listenbrainz scrobbling
3. Run docker compose up -d.
4. Authorize the services once: open http://localhost:8000/setup in a browser and sign in with the username and password from step 2. The page logs into Tidal first, then adds a Last.fm step when you configured scrobbling.
5. Point a Subsonic client at http://localhost:8000 and log in with the username and password chosen in step 2.

The server reads ./settings.toml through the Compose mount. Edit the file and run docker compose restart, or map any other file:

- /path/to/your/settings.toml:/config/subtidal/settings.toml:ro

Adjust the log level with RUST_LOG=subtidal=debug docker compose up -d.

To run the published image directly:

docker run -d -p 8000:8000 \
  -e APP_USERNAME=admin -e APP_PASSWORD=admin -e APP_PORT=8000 \
  -v subtidal-data:/data \
  ghcr.io/frostplexx/subtidal:latest

APP_* env vars are the settings for this path; nested sections use a double underscore, e.g. APP_LISTENBRAINZ__TOKEN=... or APP_TRANSCODE__ENABLED=false. The image stores the Tidal token at /data/tokens.json.

Local development

Prerequisites: a recent Rust nightly toolchain (edition 2024). The Nix flake provides one via rustup, pinned in rust-toolchain.toml: nix develop.

1. Run just dev or cargo run.
2. Authorize on first start: run cargo run login in a terminal, or open http://localhost:8000/setup in a browser and follow the page. When you configured Last.fm, the page asks for it after Tidal.
3. Connect with admin / admin from settings.toml.