Export CSV¶

Overview¶

Important: This feature is for exporting the results of push operations (e.g., to retry failed items or generate mappings), not for exporting library data itself.

To export library data from a source, use --to=csv
To export push operation results, use --export-csv (this feature)

Both use the same CSV format, so files created with --export-csv can be used as input with --from=csv.

Purpose¶

The --export-csv option allows you to export items from a push operation based on their result status. This is useful for:

Retrying failed items: Export items that couldn't be matched and try again with different settings
Generating mappings: Export items with low similarity or not found to create manual mappings
Analysis: Review what succeeded, what failed, and why. Note that for this purpose, you can also get pretty output in your console with the --report option

Usage¶

Basic Syntax¶

pushtunes push albums --from <source> --to <target> \
  --export-csv=<status1>,<status2>,... \
  [--export-csv-file=<filename>]

pushtunes push tracks --from <source> --to <target> \
  --export-csv=<status1>,<status2>,... \
  [--export-csv-file=<filename>]

Options¶

--export-csv: Comma-separated list of statuses to export
--export-csv-file: Optional output filename (defaults to albums_export_<statuses>.csv or tracks_export_<statuses>.csv)

Available Statuses¶

Status	Description
`not_found`	No search results found for the item
`similarity_too_low`	Search results found but similarity below threshold
`filtered`	Item was filtered out by `--include`, `--exclude`, or `--patterns-from`
`already_in_library`	Item already exists in target library
`added`	Item successfully added (includes items added via `--mappings`)
`error`	Error occurred while adding the item
`mappings-file`	Special mode: Export `not_found` and `similarity_too_low` items in mappings format (see below)

Special Status: mappings-file¶

The mappings-file status is a convenience feature that exports items with status not_found or similarity_too_low in the mappings CSV format instead of the regular CSV format. This gives you a ready-to-fill template for creating manual mappings.

How it works:

Automatically filters for items with status not_found or similarity_too_low
Exports in mappings format with empty target fields
Default filename: albums_mappings_template.csv or tracks_mappings_template.csv
Can be used directly with --mappings-file after filling in target information

Example:

# Export failed items as a mappings template
pushtunes push albums --from subsonic --to spotify \
  --export-csv=mappings-file

# This creates: albums_mappings_template.csv
# Format:
# type,artist,title,spotify_id,ytm_id,tidal_id,spotify_artist,spotify_title,ytm_artist,ytm_title,tidal_artist,tidal_title
# album,"Artist Name","Album Title","","","","","","","","",""

# Fill in the target fields, then use it:
pushtunes push albums --from subsonic --to spotify \
  --mappings-file=albums_mappings_template.csv

Examples¶

Retry Failed Items¶

Export albums that weren't found or had similarity too low, then retry just the failed items with adjusted similarity:

# Initial push
pushtunes push albums --from subsonic --to spotify \
  --export-csv=not_found,similarity_too_low \
  --export-csv-file=failed_albums.csv

# Review the failures
cat failed_albums.csv

# Retry with lower similarity threshold
pushtunes push albums --from csv --csv-file=failed_albums.csv --to spotify \
  --similarity=0.7

This way you don't have to risk messing up your library by pushing the whole thing again with lower similarity. You just lower it for the few problematic items in the CSV.

Create Mappings File Automatically¶

Use the mappings-file status to automatically generate a template:

# Push and generate mappings template for items not found
pushtunes push albums --from subsonic --to spotify \
  --export-csv=mappings-file

# Output:
# Exported 15 albums to mappings template: albums_mappings_template.csv
#   Fill in the target fields and use with --mappings-file=albums_mappings_template.csv

# Edit the file and fill in target information:
# type,artist,title,spotify_id,ytm_id,tidal_id,spotify_artist,spotify_title,ytm_artist,ytm_title,tidal_artist,tidal_title
# album,"Volkor X","This Means War","","","","Volkor X","This Really Means War (2025)","","","",""
# album,"Mitch Murder","Current Events","","","","Mitchell","Current Events","","","",""

# Retry with the filled-in mappings
pushtunes push albums --from subsonic --to spotify \
  --mappings-file=albums_mappings_template.csv

See Mappings.md for more on the mappings feature.

Export Multiple Statuses¶

Export all items that weren't successfully added:

pushtunes push albums --from subsonic --to spotify \
  --export-csv=not_found,similarity_too_low,error,filtered

This creates albums_export_not_found_similarity_too_low_error_filtered.csv.

Export Successful Additions¶

Track what was successfully added for record-keeping or perhaps to feed into a --from=csv that you use with another music service to add just those extra items there as well:

pushtunes push albums --from csv --csv-file=new_releases.csv --to spotify \
  --export-csv=added \
  --export-csv-file=successfully_added.csv

Combine with Reporting¶

Use both --report and --export-csv for visual feedback and CSV export:

pushtunes push tracks --from subsonic --to spotify \
  --report=not_found,similarity_too_low \
  --export-csv=not_found,similarity_too_low \
  --export-csv-file=review_these.csv

This gives you pretty, colorful (if desired) output on your console but also a CSV record of what happened, and it's probably easier to read than logs.

CSV Format¶

The exported CSV files use the same format as the --from=csv and --to=csv options.

Albums¶

artist,album,year
"Artist Name","Album Title","2023"
"Another Artist","Another Album","2024"

Tracks¶

artist,track,album,year
"Artist Name","Track Title","Album Name","2023"
"Another Artist","Another Track","Album Name","2024"

Note: Multi-artist tracks are exported with artists joined by & (e.g., "Artist A & Artist B").

Workflow Examples¶

Incremental Library Sync¶

# Initial sync with mappings template generation
pushtunes push albums --from subsonic --to spotify \
  --export-csv=mappings-file \
  --export-csv-file=need_mappings.csv

# Edit the mappings template to add target information
# (Fill in spotify_artist and spotify_title columns)
vim need_mappings.csv

# Retry with mappings
pushtunes push albums --from subsonic --to spotify \
  --mappings-file=need_mappings.csv \
  --export-csv=not_found,error \
  --export-csv-file=still_failing.csv

# Manual investigation of remaining failures
cat still_failing.csv

Filtered Export for Specific Artists¶

# Push only albums from specific artists, export what succeeded
pushtunes push albums --from subsonic --to ytm \
  --include="artist:'Pink Floyd'" \
  --include="artist:'Led Zeppelin'" \
  --export-csv=added \
  --export-csv-file=classic_rock_added.csv

Cross-Service Playlist Export¶

When pushing playlists between streaming services (Spotify ↔ YouTube Music), use --export-csv to generate mappings for tracks that couldn't be matched:

# Try to push playlist from Spotify to YTM with strict matching
pushtunes push playlist --from spotify --playlist-name "Synthwave Mix" --to ytm \
  --require-all-tracks \
  --export-csv=mappings-file \
  --export-csv-file=playlist_mappings.csv

# This creates a mappings template for tracks with not_found or similarity_too_low status
# Edit the file to provide manual matches, then retry:

pushtunes push playlist --from spotify --playlist-name "Synthwave Mix" --to ytm \
  --require-all-tracks \
  --mappings-file=playlist_mappings.csv

See Cross-Service-Playlists.md for more details on cross-service playlist pushing.

Notes¶

If no items match the specified statuses, the CSV file will not be created and you'll see: No albums matched the specified statuses for export
The exported CSV contains the original item data from the source, not the matched item from the target
Items successfully added via --mappings have status added (not a separate mapped status; the album was added fine thanks to your mapping, no need to split this up any further in the CSV)
You can export the same results with both --report (for terminal display) and --export-csv (for file output)
The mappings-file status is special:
- It automatically exports items with status not_found or similarity_too_low
- Output format is the mappings CSV format (not the regular CSV format)
- All target fields are left empty for you to fill in
- Cannot be combined with other statuses in the same --export-csv call

Comparison: --to=csv vs --export-csv¶

Feature	`--to=csv`	`--export-csv`
Purpose	Export source library data to CSV	Export push operation results to CSV
When to use	Backup, migration, sharing library data	Retry failures, create mappings, analysis
Output content	All items from source (optionally filtered)	Only items matching specified statuses
Matching behavior	No matching performed	Full matching performed, results filtered
Can be used with `--from=csv`	Yes	Yes
Requires target service	No (writes directly to file)	Yes (performs matching first)

Example Comparison¶

# Export all albums from Subsonic to CSV (no matching)
pushtunes push albums --from subsonic --to csv --csv-file=all_albums.csv

# Push to Spotify and export CSV of the failures (performs matching, exports failures)
pushtunes push albums --from subsonic --to spotify \
  --export-csv=not_found,similarity_too_low \
  --export-csv-file=failed_albums.csv