Deleting Items from Music Services¶

Pushtunes provides two ways to delete items from your streaming library:

Standalone delete command: Delete based on filters (no source comparison)
push --delete option: Delete items not in source (with source comparison, useful to remove stuff from a streaming service that isn't your local library)

Standalone Delete Command¶

The delete command removes albums or tracks from a service based on filter criteria, without needing a source. This is useful for targeted cleanups.

Basic Usage¶

# Delete all albums by a specific artist
pushtunes delete albums --from spotify --include="artist:'Volkor X'"

# Delete all live albums
pushtunes delete albums --from spotify --include="album:'.*Live.*'"
pushtunes delete albums --from tidal --include="album:'.*Live.*'"

# Delete all tracks by an artist
pushtunes delete tracks --from spotify --include="artist:'Carpenter Brut'"
pushtunes delete tracks --from tidal --include="artist:'Carpenter Brut'"

# Delete all live tracks
pushtunes delete tracks --from spotify --include="track:'.*Live.*'"
pushtunes delete tracks --from ytm --include="track:'.*Live.*'"

Key Features¶

Filter required: You must specify --include, --exclude, or --patterns-from
Preview before deletion: Shows what will be deleted
Automatic backup: Creates CSV backup before deletion
Confirmation required: Type 'yes' to proceed
Supports Spotify, YouTube Music, and Tidal

Filter Examples¶

# Include specific artists (delete only these)
pushtunes delete albums --from spotify --include="artist:'Volkor X'" --include="artist:'Perturbator'"

# Exclude patterns (delete everything except these)
pushtunes delete albums --from spotify --exclude="artist:'Favorite Band'"

# Use patterns file
pushtunes delete albums --from spotify --patterns-from=delete_filters.txt

Example delete_filters.txt:

# Delete all albums by these artists
+ artist:'Old Band'
+ artist:'Demo Project'

# But exclude their main releases
- album:'.*Greatest Hits.*'

Push with Delete Option¶

The --delete option on push commands performs something like a sync operation: pushes items from source, then deletes items from target that aren't in source. It's not a full-fledged sync but it comes close.

Basic Usage¶

# Delete albums from Spotify that aren't in Subsonic
pushtunes push albums --from subsonic --to spotify --delete

# Delete albums from Tidal that aren't in Subsonic
pushtunes push albums --from subsonic --to tidal --delete

# Delete tracks from YouTube Music that aren't in your CSV file
pushtunes push tracks --from csv --csv-file=my_library.csv --to ytm --delete

How It Works¶

When you use --delete, Pushtunes performs the following workflow:

1. Normal Push Operation¶

First, it performs the standard push operation to add any missing items from source to target.

2. Deletion Analysis¶

After the push completes, Pushtunes:

Fetches all items from the target library
Compares them with items in the source using the same similarity matching algorithm
Identifies which items would be deleted (items in target but not in source)

3. Deletion Preview¶

Before any deletion occurs, you'll see a detailed preview showing:

╭─────────────────── Deletion Preview ───────────────────╮
│ Total albums in target library: 200                     │
│ Albums that will be DELETED: 5                          │
│ Albums that will be PRESERVED: 195                      │
╰─────────────────────────────────────────────────────────╯

Items that will be DELETED (not found in source with similarity >= 0.8):

┌──────────────┬────────────────────┐
│ Artist       │ Title              │
├──────────────┼────────────────────┤
│ Old Band     │ Removed Album      │
│ Test Artist  │ Demo Album         │
└──────────────┴────────────────────┘

This preview shows you exactly what will be deleted so you can review before confirming.

4. Automatic Backup¶

Before showing the confirmation prompt, Pushtunes automatically creates a CSV backup of all items to be deleted:

Backup location:

Linux: ~/.local/share/pushtunes/backups/
macOS: ~/Library/Application Support/pushtunes/backups/
Windows: C:\Users\<username>\AppData\Local\pushtunes\pushtunes\backups\

Backup filename format:

Albums: albums_deletion_backup_YYYYMMDD_HHMMSS.csv
Tracks: tracks_deletion_backup_YYYYMMDD_HHMMSS.csv

Important: These backups include service IDs (spotify_id, ytm_id) which allows for exact restoration without fuzzy matching.

5. Confirmation Prompt¶

After the preview and backup, you must explicitly confirm:

Backup saved to: /home/user/.local/share/pushtunes/backups/albums_deletion_backup_20251115_120000.csv
You can restore deleted items using: pushtunes push albums --from=csv --csv-file=/home/user/.local/share/pushtunes/backups/albums_deletion_backup_20251115_120000.csv

Are you sure you want to delete 5 albums?
This action will remove them from your target library.

Type 'yes' to confirm deletion, or anything else to cancel:

Only typing exactly yes will proceed with deletion. Any other input cancels.

6. Deletion Execution¶

If confirmed, Pushtunes:

Removes each item from the target library
Logs each deletion
Reports final statistics including deletion count

Safety Features¶

The --delete option includes multiple safety mechanisms:

1. Preview Before Deletion¶

You always see exactly what will be deleted before any action is taken.

2. Automatic CSV Backups¶

Every item to be deleted is backed up to CSV with service IDs for exact restoration.

3. Explicit Confirmation Required¶

You must type yes to proceed. No accidental deletions from typos or enter key.

4. Service ID Preservation¶

Backups include exact service IDs, so restoration adds the exact same items (no fuzzy matching).

5. Not Supported for CSV Target¶

You cannot use --delete when pushing to CSV. Maybe at one point we'll have support to delete just the respective lines from CSV.

Restoring Deleted Items¶

If you accidentally delete items or change your mind, you can restore them using the backup CSV:

# Restore deleted albums
pushtunes push albums --from csv \
  --csv-file ~/.local/share/pushtunes/backups/albums_deletion_backup_20251115_120000.csv \
  --to spotify

# Restore deleted tracks
pushtunes push tracks --from csv \
  --csv-file ~/.local/share/pushtunes/backups/tracks_deletion_backup_20251115_120000.csv \
  --to ytm

Because the backup includes service IDs, restoration is:

Fast: No search required, direct addition by ID
Accurate: Exact same items are added back
Reliable: No false matches from similarity algorithm

Use Cases¶

Sync Library After Cleanup¶

You've cleaned up your local music collection and want Spotify to match:

pushtunes push albums --from subsonic --to spotify --delete

Remove Albums from Failed Artists¶

You exported albums with --export-csv, manually removed some rows, and want to delete them from Spotify:

# Original library
pushtunes push albums --from spotify --to csv --csv-file original.csv

# Edit original.csv to remove unwanted albums

# Sync Spotify with edited CSV
pushtunes push albums --from csv --csv-file original.csv --to spotify --delete

Keep Two Services in Sync¶

You want YouTube Music to mirror your Spotify library:

# First, add everything from Spotify to YTM
pushtunes push albums --from spotify --to ytm

# Then, remove from YTM what's not in Spotify
pushtunes push albums --from spotify --to ytm --delete

Similarity Threshold Considerations¶

The --similarity option affects which items are considered "found" in the source:

Higher Similarity (e.g., 0.9)¶

More deletions: Stricter matching means fewer items match, more get deleted
Use when: Your source metadata is very accurate
Risk: Might delete valid items due to minor metadata differences

Lower Similarity (e.g., 0.7)¶

Fewer deletions: Looser matching means more items match, fewer get deleted
Use when: Your source metadata is inconsistent or has variations
Risk: Might keep items you wanted deleted due to false matches

Recommendation¶

Start with the default (0.8) and review the deletion preview carefully. If you notice valid items being marked for deletion due to metadata differences, consider adjusting the similarity threshold.

# Use a lower threshold if metadata varies
pushtunes push albums --from subsonic --to spotify --similarity 0.75 --delete

Working with Filters¶

You can combine --delete with filters (--include, --exclude, --patterns-from) to limit which items are considered. Filters are applied BEFORE deletion matching, which means filtered-out items are completely ignored during the deletion process.

Note: This section focuses on how filters interact with --delete. For complete filter syntax and examples, see Filtering Documentation.

How Filters Work with Delete¶

Filters affect the operation in two critical ways:

Push Phase: Only items matching the filter are pushed to the target
Delete Phase: Only items matching the filter are considered as "present in source"

This means when you filter by artist, you're essentially saying "only consider these artists for the entire sync operation, including deletion."

Include Filter Examples¶

Include filters specify which items to keep in scope. Everything else is ignored.

# Sync only Volkor X albums - delete everything else from target
pushtunes push albums --from subsonic --to spotify \
  --include="artist:'Volkor X'" --delete

What happens: - Source has: Volkor X (10 albums), Perturbator (5 albums), Carpenter Brut (3 albums) - After filtering source has: Volkor X (10 albums only) - Target has: All of the above plus Dance with the Dead (2 albums) - Push phase: Adds any missing Volkor X albums - Delete phase: Compares target against filtered source (Volkor X only) - Result: Perturbator, Carpenter Brut, and Dance with the Dead are ALL deleted - Perturbator and Carpenter Brut are ignored (filtered out) - Dance with the Dead isn't in the filtered source

Multiple include patterns use OR logic:

# Include multiple artists
pushtunes push albums --from subsonic --to spotify \
  --include="artist:'Volkor X'" \
  --include="artist:'Perturbator'" \
  --delete

Exclude Filter Examples¶

Exclude filters specify which items to ignore. Everything else stays in scope.

# Sync everything EXCEPT Volkor X
pushtunes push albums --from subsonic --to spotify \
  --exclude="artist:'Volkor X'" --delete

What happens: - Source has: Volkor X (10 albums), Perturbator (5 albums), Carpenter Brut (3 albums) - After filtering source has: Perturbator (5 albums), Carpenter Brut (3 albums) - Target has: All of the above - Push phase: Adds any missing Perturbator and Carpenter Brut albums - Delete phase: Compares target against filtered source (no Volkor X) - Result: All Volkor X albums are deleted from target (not in filtered source)

# Exclude multiple artists
pushtunes push albums --from subsonic --to spotify \
  --exclude="artist:'Volkor X'" \
  --exclude="artist:'Perturbator'" \
  --delete

Combining Include and Exclude¶

When both are present, exclude takes precedence:

# Include Black Mountain and Black Hills, but exclude Carpenter Brut
pushtunes push albums --from subsonic --to spotify \
  --include="artist:'Black.*'" \
  --exclude="artist:'Carpenter Brut'" \
  --delete

Using Patterns Files¶

For complex filtering scenarios, use a patterns file with + for include and - for exclude:

# Create a patterns file
cat > my_filters.txt <<EOF
# Include specific artists
+ artist:'Volkor X'
+ artist:'Perturbator'
+ artist:'Carpenter Brut'

# But exclude demo albums
- album:'.*Demo.*'
EOF

# Use it with delete
pushtunes push albums --from subsonic --to spotify \
  --patterns-from=my_filters.txt --delete

See Filtering for complete documentation on filter syntax and behavior.

Filter Behavior Summary¶

Key principle: Filters are processed BEFORE mappings and BEFORE deletion matching.

Scenario	Source (after filter)	Target	What Gets Deleted
No filter	All items	All items	Items only in target
`--include="artist:'X'"`	Only artist X	All items	Everything except artist X
`--exclude="artist:'X'"`	All except X	All items	Artist X
`--include="artist:'X'" --exclude="album:'Demo'"`	Artist X, no demos	All items	Everything except (X minus demos)

Important Notes¶

Filtered items are completely ignored: If an artist is excluded or not included, it won't be considered during deletion matching AT ALL. This means:
Its albums in the target WILL be deleted (not in filtered source)
Its mappings won't be processed
It won't appear in any logs or statistics
Filters apply to source, not target: The filter determines which source items to consider. The target library is always fetched in full, then compared against the filtered source.
Deletion preview shows the impact: The deletion preview will clearly show which items will be deleted based on the filtered source comparison.

Statistics¶

After completion, you'll see updated statistics including deletion count:

==================================================
Statistics
==================================================
Total albums processed: 150
Successfully added: 20
Deleted from target: 5
Skipped (already in library): 125
...
==================================================

Limitations¶

CSV target not supported: --delete only works with Spotify, YouTube Music, and Tidal targets
No undo within Pushtunes itself: Once deleted, items must be restored via the backup CSV