Skip to content

Pushtunes Documentation

Pushtunes is a tool to push your music from local sources (Subsonic-compatible server/Navidrome, Jellyfin, CSV files) to music streaming services like Spotify, YouTube Music, and Tidal.

Features

  • Multiple Sources: Subsonic/Navidrome, Jellyfin, or CSV files
  • Multiple Targets: Spotify, YouTube Music, and Tidal
  • Smart Matching: Fuzzy similarity matching handles metadata differences
  • Playlists: Push playlists between services with conflict resolution
  • Filtering: Filter albums/tracks using regex patterns
  • Mappings: Manual override for difficult-to-match items
  • Safe Deletion: Sync libraries by safely removing items with automatic backups
  • Export: Export push results to CSV for analysis or retry

Quick Start

Install from PyPI:

source .venv/bin/activate
pip install pushtunes

Or from this source directory, with uv:

uv run pushtunes

Basic Usage

# Push albums from Subsonic to Spotify
pushtunes push albums --from subsonic --to spotify

# Push tracks from Subsonic to YouTube Music
pushtunes push tracks --from subsonic --to ytm

# Push playlists
pushtunes push playlist --from subsonic --playlist-name=myplaylist --to spotify

# Push from CSV file
pushtunes push tracks --from csv --csv-file=tracks.csv --to spotify

# Use a profile for reusable configurations
pushtunes push albums --profile=myprofile.toml

For detailed installation and setup instructions, see Getting Started.

To save frequently-used options in configuration files, see Profiles.

Core Concepts

Similarity Matching

Pushtunes uses fuzzy matching to handle metadata differences. Adjust with --similarity (default 0.8). See details in Getting Started.

Filtering

Filter items using regex patterns with --include, --exclude, and --patterns-from. See Filters for full documentation.

Playlists

Push, back up and sync playlists between any supported services:

  • Subsonic/Jellyfin ↔ Spotify/YouTube Music/Tidal
  • Spotify/YouTube Music ↔ Subsonic/Jellyfin
  • Spotify ↔ YouTube Music (cross-service)

Supports --require-all-tracks strict matching, --on-conflict handling (abort/replace/append/sync), and manual mappings. See Playlists.

Advanced Features

Profiles

Save commonly-used configuration options in reusable profile files. Useful for:

  • Regular backup workflows
  • Complex filtering configurations
  • Shared configurations
  • Multiple sync scenarios

See Profiles for more.

Mappings

Manually map difficult items that can't be matched automatically. Useful when:

  • Artists changed names
  • Regional differences in artist names
  • Metadata is inconsistent or incomplete

See Mappings for more.

Export & CSV

Export push results to CSV for:

  • Retrying only failed items
  • Creating mappings files
  • Diagnosing issues
  • Keeping records

See Export-CSV for more.

Deleting Items

Safely remove items from target library that don't exist in source:

  • Preview what will be deleted
  • Automatic backups with service IDs
  • Explicit confirmation required
  • Easy restoration from backups

See Deleting Items for more.

Providers

Pushtunes uses a unified provider model where each platform is implemented as a single class. See Architecture for details on the provider model.

See Getting Started for detailed setup instructions.

Source Providers

Provider Command
Subsonic/Navidrome --from subsonic
Jellyfin --from jellyfin
CSV --from csv --csv-file=path/to/file.csv

Target Providers

Provider Auth Method
Spotify OAuth (set SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET)
YouTube Music Browser headers (ytmusicapi browser)
Tidal OAuth (works out of the box)

Help & Support

For help:

pushtunes --help
pushtunes push albums --help
pushtunes push tracks --help
pushtunes push playlist --help

Report issues: code.psy-q.ch Issue Tracker

Project Background

I know Spotify and friends are very problematic services, but I wanted some software that can back up my music there anyway. See Philosophy.

License

Pushtunes is licensed under AGPL-3.0-or-later.