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 poetry:

poetry 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 differences in how music services structure metadata. This applies to albums, tracks, and playlists.

  • Case-insensitive: "The Beatles" matches "the beatles"
  • Artist variations: "Artist A & Artist B" matches "Artist A, Artist B"
  • Featured artists: Handles different ways services list collaborations
  • Soundtrack suffixes: "Album Title (Original Soundtrack)" matches "Album Title"
  • Remaster handling: Keeps remasters separate from originals by default

Adjust matching strictness with --similarity (default 0.8):

# Stricter matching (90% similar)
pushtunes push tracks --from subsonic --to spotify --similarity=0.9

# More lenient (70% similar)
pushtunes push albums --from csv --csv-file=albums.csv --to ytm --similarity=0.7

Filtering

Filter albums/tracks using regex patterns with --include and --exclude:

# Include only specific artists
pushtunes push albums \
  --include="artist:'Taylor Swift'" \
  --include="artist:'Opeth'" \
  --from=csv --csv-file=albums.csv --to=spotify

# Exclude specific items
pushtunes push tracks \
  --exclude="artist:'Volkor X'" \
  --exclude="track:'.*Live.*'" \
  --from=subsonic --to=spotify

# Load patterns from a file
pushtunes push albums \
  --patterns-from=filters.txt \
  --from=subsonic --to=spotify

Supported fields:

  • Albums: artist, album
  • Tracks: artist, track, album

Multiple --include patterns use OR logic. Multiple --exclude patterns also use OR logic. Excludes override includes.

Playlists

Push playlists with flexible conflict handling:

  • abort (default): Show differences and exit
  • replace: Replace entire playlist
  • append: Add missing tracks
  • sync: Full synchronization
pushtunes push playlist \
  --from subsonic \
  --playlist-name=myplaylist \
  --to spotify \
  --on-conflict=sync

For cross-service playlist migration, see Cross-Service 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.

Playlists from Subsonic/Jellyfin

Push, back up and sync your playlists from your self-hosted services to one of the streaming services:

  • Subsonic/Jellyfin/CSV → Spotify/YouTube Music
  • Spotify/YouTube Music → CSV

See Playlists for more.

Cross-Service Playlists

Migrate playlists between Spotify and YouTube Music:

  • Spotify → YouTube Music
  • YouTube Music → Spotify
  • Handle service-specific limitations

See Cross-Service Playlists 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.

Music Sources

Subsonic/Navidrome

Set credentials via environment variables:

export SUBSONIC_URL="https://music.example.com"
export SUBSONIC_USER="your_username"
export SUBSONIC_PASS="correct horse battery staple"

Then use --from subsonic in commands.

Jellyfin

Set credentials via environment variables:

export JELLYFIN_URL="https://jellyfin.example.com"
export JELLYFIN_USER="your_username"
export JELLYFIN_PASS="correct horse battery staple"

Then use --from jellyfin in commands.

CSV Files

Use --from csv --csv-file=path/to/file.csv to read tracks and albums from CSV.

See Getting Started for the exact format and more information.

Music Services

Spotify

Requires OAuth authentication. On first run, Pushtunes will: 1. Open your browser for Spotify login 2. Ask you to authorize the application 3. Save credentials for future use

Set your Spotify app credentials:

export SPOTIPY_CLIENT_ID="your_client_id"
export SPOTIPY_CLIENT_SECRET="your_client_secret"
export SPOTIPY_REDIRECT_URI="http://localhost:8888/callback"

Get credentials from Spotify Developer Dashboard

YouTube Music

Requires browser authentication headers. Use ytmusicapi setup instructions:

ytmusicapi browser

This creates browser.json with authentication headers. If you want to store this elsewhere, you can specify a different path to this file with `--ytm-auth`` whenever you use YouTube Music. But be warned that YTM authentication seems to expire anywhere from 30 minutes to 24 hours after you log in, so you're not going to use this file for long anyway.

Tidal

Tidal authentication works out of the box - no API credentials needed! On first run, Pushtunes will:

  1. Display an OAuth URL in your terminal (e.g., https://link.tidal.com/XXXXX)
  2. Attempt to open your web browser automatically
  3. Ask you to log in to your Tidal account and authorize
  4. Save the session to tidal-session.json for future use

The session file is reused for subsequent runs, so you only need to authenticate once (until the session expires).

Optionally specify a custom session file location: 

export TIDAL_SESSION_FILE="/path/to/tidal-session.json"

Help & Support

For help:

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

Report issues: Codeberg 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.