Integrations Guide

soundspan works standalone, but these integrations unlock additional discovery and playback workflows.

For environment and secret setup, see CONFIGURATION_AND_SECURITY.md.

Lidarr

Connect soundspan to Lidarr to request/download new music and trigger imports.

What you get

Setup

  1. Open Settings in soundspan
  2. Go to the Lidarr section
  3. Set Lidarr URL (for example http://localhost:8686)
  4. Set Lidarr API key (Lidarr -> Settings -> General)
  5. Test and save

Networking note

Lidarr must reach the soundspan callback URL.

environment:
  - SOUNDSPAN_CALLBACK_URL=http://YOUR_SOUNDSPAN_IP:3030

Audiobookshelf

Connect your Audiobookshelf instance for audiobook playback in soundspan.

Setup

  1. Open Settings -> Audiobookshelf
  2. Set URL (for example http://localhost:13378)
  3. Set API token (Audiobookshelf user settings)
  4. Test and save

Soulseek

soundspan can connect directly to Soulseek for discovery/download flows.

Disclaimer: You are responsible for legal use in your jurisdiction.

Setup

  1. Open Settings -> Soulseek
  2. Enter Soulseek username/password
  3. Save

Notes

YouTube Music

Stream unowned tracks via per-user YouTube Music OAuth.

Disclaimer: Uses unofficial libraries (ytmusicapi, yt-dlp) and requires YouTube Music Premium.

Requirements

Admin setup

  1. Create OAuth client in Google Cloud Console
  2. Open soundspan Settings -> YouTube Music
  3. Enable and set client ID/secret
  4. Save

Per-user setup

  1. Open Settings -> YouTube Music
  2. Click Link YouTube Music Account
  3. Enter device code at Google authorization page
  4. Choose quality and save

Quality settings

Setting Approximate bitrate
Low ~64 kbps
Medium ~128 kbps
High ~256 kbps
Lossless Best available

API access modes

All routes below still require soundspan authentication and ytMusicEnabled=true.

Mode Endpoints
OAuth-free browse/search/stream GET /api/browse/ytmusic/charts, GET /api/browse/ytmusic/categories, GET /api/browse/ytmusic/playlist/:id, POST /api/ytmusic/search, POST /api/ytmusic/match, POST /api/ytmusic/match-batch, GET /api/ytmusic/stream-info-public/:videoId, GET /api/ytmusic/stream-public/:videoId
Per-user OAuth required GET /api/ytmusic/album/:browseId, GET /api/ytmusic/artist/:channelId, GET /api/ytmusic/song/:videoId, GET /api/ytmusic/stream-info/:videoId, GET /api/ytmusic/stream/:videoId, GET /api/ytmusic/library/songs, GET /api/ytmusic/library/albums

Track Mapping and Playlist Import APIs

soundspan also exposes provider mapping and playlist import routes for cross-provider workflows:

Endpoint Purpose
POST /api/browse/playlists/parse Parse Spotify/Deezer playlist URLs before import
GET /api/track-mappings/album/:albumId Read provider mappings for an album's local tracks
POST /api/track-mappings/batch Persist multiple mapping links in one request
POST /api/import/preview Resolve playlist tracks (local/YT/TIDAL) without creating a playlist
POST /api/import/execute Create a playlist from a resolved import

TIDAL Streaming

Stream unowned tracks via per-user TIDAL OAuth.

Disclaimer: Requires TIDAL subscription and uses tiddl library.

Requirements

Per-user setup

  1. Open Settings -> TIDAL Streaming
  2. Click Link TIDAL Account
  3. Enter device code at TIDAL authorization page
  4. Choose quality and save

Streaming auth is separate from admin download auth.

Quality settings

Setting Format
Low AAC 96 kbps
High AAC 320 kbps
Lossless FLAC 16-bit / 44.1 kHz
Max / Hi-Res FLAC 24-bit / 192 kHz

TIDAL Downloads

Use TIDAL as a download source for tracks/albums.

Disclaimer: Intended for personal use with your own subscription.

Setup

  1. Ensure tidal-downloader service is running
  2. Open Settings -> TIDAL
  3. Authenticate via device-code flow
  4. Choose download quality and naming template
  5. Save

File naming template examples

# Default
{album.artist}/{album.title}/{item.number:02d}. {item.title}

# Disc-track format
{album.artist}/{album.title}/{item.volume}-{item.number:02d} {item.title}

# With year
{album.artist}/{album.title} ({album.date:%Y})/{item.number:02d}. {item.title}

Default template:

{album.artist}/{album.title}/{item.number:02d}. {item.title}

TIDAL sidecar environment values

Variable Default Description
TIDAL_TRACK_DELAY 3 Delay between track downloads
MUSIC_PATH /music Path for downloaded music
TIDDL_PATH /data/.tiddl Sidecar cache/config path
DEBUG (unset) Enable debug logging

Main-channel image:

docker pull ghcr.io/soundspan/soundspan-tidal-downloader:main

OpenSubsonic API Compatibility

soundspan exposes a Subsonic/OpenSubsonic-compatible /rest surface.

Local smoke check:

cd backend
npm run test:smoke:subsonic-proxy

See also

Edit on GitHub Back to top