selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

tunesynctool logo

Self-host tunesynctool

v1.2.2

Self-hosted music library sync across streaming services

BetaOpen SourceGPL-2.0
Updated4 months ago
LanguagePython
Setup difficultyAdvanced
Stars
158
Ports
8000 (API backend), 80 (Frontend web UI)
Requires
MySQL, Redis
Install with Docker

What is tunesynctool?

tunesynctool is a Python-based self-hosted web application for managing music libraries across multiple streaming services. It provides a web UI and REST API to search, transfer, and synchronize playlists and tracks between Spotify, Deezer (read-only), YouTube Music, and any Subsonic-compatible service such as Navidrome or Airsonic. The project includes a Docker Compose setup with a React frontend, FastAPI backend, MySQL database, and Redis cache. It uses JWT-based authentication for user accounts and OAuth2 flows for connecting to music providers. The software is licensed under GPL-2.0 and is under active development with a 1.2.2 release as of June 2026.

Should you self-host tunesynctool?

tunesynctool scores 41/100 on selfhost.directory (how scoring works) and ranks #43 of 59 in Music Streaming. It has 158 GitHub stars.

It shipped 1 stable release in the past year. The latest, v1.2.2, came out on 6 June 2026.

Setup is advanced: plan for several services and some ongoing maintenance. It is GPL-2.0-licensed and written mostly in Python.

Its closest alternative on selfhost.directory is koel (75/100, 17 320 stars). It scores higher overall, so compare the two before you pick. See tunesynctool vs koel side by side.

Features

  • Deezer ARL cookie authenticationRead-only, experimental
  • Multi-user support with admin roles
  • OAuth2 provider linking
  • Playlist synchronizationMarked as work in progress in README
  • Playlist transfer between services
  • REST API with OpenAPI schema
  • Subsonic credential authentication
  • Track matching via ISRC and MusicBrainzBeing rebuilt from scratch according to FAQ
  • Track search across providers

tunesynctool README

How to install tunesynctool

Install tunesynctool with Docker

Docker

FROM python:3.13-slim

Set working directory

WORKDIR /app

Copy requirements file

COPY requirements.txt .

Install dependencies

RUN pip install --no-cache-dir -r requirements.txt

Copy the entire project structure to maintain proper module paths

COPY . .

Remove webui/frontend directory to save space

RUN rm -rf ./webui/frontend

Install the tunesynctool package in development mode to make it available as a CLI command

RUN pip install -e .

Make sure the Python path includes the API package location

ENV PYTHONPATH=/app/webui:/app

Expose port (API will run on port 8000)

EXPOSE 8000

The API expects to run from inside the webui/api directory for relative imports/static paths

WORKDIR /app/webui/api

Default command runs the API

To run the CLI instead, override with: docker run tunesynctool tunesynctool [args]

CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8000"]

Builds the API container; frontend must be built separately

How to configure tunesynctool

  • ADMIN_PASSWORDPassword for the admin/default user

    Password for the admin/default user

  • APP_HOSTFull base URL of the API

    Full base URL of the API

  • APP_SECRETAPI secret used for signing JWTs

    API secret used for signing JWTs

  • DB_HOSTMySQL database host

    MySQL database host

  • DB_NAMEMySQL database name

    MySQL database name

  • DB_PASSWORDMySQL database password

    MySQL database password

  • DB_PORTMySQL database port

    MySQL database port

  • DB_USERMySQL database username

    MySQL database username

  • DEEZER_ARLARL token to authenticate with Deezer account

    ARL token to authenticate with Deezer account

  • ENCRYPTION_KEYUsed to encrypt authentication data for providers

    Used to encrypt authentication data for providers

  • ENCRYPTION_SALTUsed to encrypt authentication data for providers

    Used to encrypt authentication data for providers

  • GOOGLE_CLIENT_IDGoogle client ID for YouTube Music

    Google client ID for YouTube Music

  • GOOGLE_CLIENT_SECRETGoogle client secret for YouTube Music

    Google client secret for YouTube Music

  • REDIS_HOSTConnection host for Redis

    Connection host for Redis

  • REDIS_PORTConnection port for Redis

    Connection port for Redis

  • SIGNUPS_ALLOWEDtrueWhether user signups are allowed

    Whether user signups are allowed

    values: true,false

  • SPOTIFY_CLIENT_IDSpotify Client ID

    Spotify Client ID

  • SPOTIFY_CLIENT_SECRETSpotify Client secret

    Spotify Client secret

  • SPOTIFY_REDIRECT_URIhttp://localhost:8888/callbackCallback URL of the Spotify app

    Callback URL of the Spotify app

  • SUBSONIC_BASE_URLSubsonic provider's base URL

    Subsonic provider's base URL

  • SUBSONIC_LEGACY_AUTHWhether to use legacy authentication with the Subsonic provider

    Whether to use legacy authentication with the Subsonic provider

  • SUBSONIC_PASSWORDPassword to authenticate with Subsonic compatible service

    Password to authenticate with Subsonic compatible service

  • SUBSONIC_PORTSubsonic provider's port

    Subsonic provider's port

  • SUBSONIC_USERNAMEUsername to authenticate with Subsonic compatible service

    Username to authenticate with Subsonic compatible service

  • YOUTUBE_REQUEST_HEADERSRaw request headers from an authenticated request to music.youtube.com

    Raw request headers from an authenticated request to music.youtube.com

tunesynctool releases & version history

FAQ

How does matching work?

Track matching is currently being entirely rebuilt from scratch.

Does tunesynctool offer functionality to download or stream music?

No, it does not download or stream music. Use official clients' offline listening features or source music in other ways.

Why aren't there any updates to the CLI or Python package, even though the repository is active?

The maintainer decided to focus on developing a self-hostable application instead of the CLI/Python package.

More in File Transfer & Sync

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…