Filtering

Pushtunes supports flexible filtering to control what gets pushed to your target service.

• Include patterns (+): Only items matching these patterns will be included
• Exclude patterns (-): Items matching these patterns will be excluded
• Multiple fields in one pattern: Use AND logic (all must match)
• Multiple patterns: Include patterns are checked first, then exclude patterns are applied

Command-Line Options

--include and --exclude

Use these options directly on the command line to specify patterns:

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

# Exclude specific patterns
pushtunes push albums --exclude="artist:'Black.*'" --exclude="album:'.*Live.*'" --from=subsonic --to=spotify

# Combine include and exclude
pushtunes push albums \
  --include="artist:'Opeth'" \
  --exclude="album:'Still Life'" \
  --from=subsonic --to=spotify

--patterns-from

For complex filtering rules, create a file with one pattern per line, prefixed with + (include) or - (exclude):

pushtunes push albums --patterns-from=my-filters.txt --from=subsonic --to=spotify

Example my-filters.txt:

# Include only these artists
+ artist:'Taylor Swift'
+ artist:'Opeth'

# But exclude specific albums
- artist:'Opeth' album:'Still Life'

# Exclude all live albums
- album:'.*Live.*'

Pattern Syntax

Patterns use the format field:'regex' where: - field is one of: artist, album (for albums) or artist, track, album (for tracks) - regex is a regular expression pattern (case-insensitive)

Multiple fields in one pattern use AND logic:

+ artist:'Opeth' album:'Morningrise'

This matches albums by Opeth AND with title containing "Morningrise".

Filtering Logic

The filtering logic works as follows:

1. If you have include patterns: Only items matching at least one include pattern will be considered, then exclude patterns are applied
2. If you have only exclude patterns: All items are considered, except those matching any exclude pattern

Examples:

# Only include Taylor Swift, but exclude live albums
pushtunes push albums \
  --include="artist:'Taylor Swift'" \
  --exclude="album:'.*Live.*'" \
  --from=subsonic --to=spotify

# Exclude everything from certain artists
pushtunes push albums \
  --exclude="artist:'Black.*'" \
  --exclude="artist:'Volkor X'" \
  --from=subsonic --to=spotify

For Albums

Supported fields: artist, album

# Include only specific artist
pushtunes push albums --include="artist:'Opeth'" --from=subsonic --to=spotify

# Exclude specific album by specific artist (AND logic)
pushtunes push albums --exclude="artist:'Opeth' album:'Still Life'" --from=subsonic --to=spotify

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

Example album-filters.txt:

# Include specific artists
+ artist:'Taylor Swift'
+ artist:'Opeth'

# But exclude specific albums
- artist:'Opeth' album:'Still Life'
- album:'.*Deluxe Edition.*'

For Tracks

Supported fields: artist, track, album

# Exclude live tracks
pushtunes push tracks --exclude="track:'.*Live.*'" --from=subsonic --to=spotify

# Include only specific artist, exclude specific tracks
pushtunes push tracks \
  --include="artist:'Opeth'" \
  --exclude="track:'Deliverance'" \
  --from=subsonic --to=spotify

# Using a patterns file
pushtunes push tracks --patterns-from=track-filters.txt --from=subsonic --to=spotify

Example track-filters.txt:

# Include only these artists
+ artist:'Taylor Swift'
+ artist:'Opeth'

# Exclude specific tracks
- artist:'Opeth' track:'Deliverance'
- track:'.*Live at.*'

Important Notes

• Patterns are case-insensitive
• Regular expressions use Python regex syntax
• Empty lines and lines starting with # in pattern files are ignored