Ruleplay

Ruleplay is a headless Spotify playlist builder that reads one or more source playlists, applies YAML-defined filter rules, and rebuilds derived playlists from scratch.

Warning

This project was generated with AI assistance. Review the code, configuration, Spotify permissions, and generated playlists before relying on it.

What Works

• Reads tracks from one or more Spotify source playlists
• Deduplicates tracks by Spotify track ID
• Supports boolean rule composition with all, any, and not
• Supports filtering on:
  • track.id
  • track.name
  • track.explicit
  • artists.ids
  • artists.names
  • artists.genres
  • album.release_date
  • album.release_year
• Supports these operators:
  • eq
  • neq
  • gt
  • gte
  • lt
  • lte
  • contains
  • in
• Caches artist metadata in SQLite, including artist_name
• Provides auth, dry-run, and rebuild commands

Current Limitations

• Spotify currently blocks audio-feature access for many development-mode apps, so audio.* filters are not dependable in practice.
• The code still has audio-field support, but if Spotify denies that endpoint, audio-based rules will not be usable.
• Generated playlist identity is keyed by filter name in the database. Renaming a filter in filters.yaml makes Ruleplay treat it like a new playlist unless you also update the DB row in filter_playlists.
• Spotify currently rejects some optional playlist metadata fields for this app, so playlist create/update requests use minimal payloads.

Requirements

• Python 3.11+
• A Spotify developer app
• Spotify app credentials:
  • SPOTIFY_CLIENT_ID
  • SPOTIFY_CLIENT_SECRET
  • SPOTIFY_REDIRECT_URI

For local auth, use this redirect URI in your Spotify app settings:

http://127.0.0.1:8888/callback

Setup

1. Create .env from .env.example and fill in your Spotify credentials:

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback
SPOTIFY_TOKEN_CACHE=.spotify_token_cache

2. Create the virtual environment and install dependencies:

uv venv --python 3.11 .venv
uv pip install -r requirements.txt

3. Copy filters.example.yaml to filters.yaml and edit it.

Configuration

filters.yaml must contain:

• source_playlists: a non-empty list of Spotify playlist IDs
• filters: a non-empty list of named rule definitions

Example:

source_playlists:
  - PLAYLIST_ID_1
  - PLAYLIST_ID_2

filters:
  - name: Punk
    rules:
      field: artists.genres
      op: contains
      value: punk

  - name: 90s
    rules:
      all:
        - field: album.release_year
          op: gte
          value: 1990
        - field: album.release_year
          op: lte
          value: 1999

To get a playlist ID from Spotify, copy it from a URL like:

https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M

The playlist ID is the last path segment:

37i9dQZF1DXcBWIGoYBM5M

Usage

Authenticate and cache the refresh token:

.\.venv\Scripts\python.exe main.py auth

Preview matches without modifying Spotify playlists:

.\.venv\Scripts\python.exe main.py dry-run

Rebuild all derived playlists:

.\.venv\Scripts\python.exe main.py rebuild

Each run prints:

• tracks scanned
• unique tracks
• warnings
• match count per filter
• playlist IDs created or updated
• per-filter failures

Renaming Playlists

Generated playlist names come directly from each filter's name.

If you change a filter name in filters.yaml, Ruleplay will use that new playlist name, but the database will treat it as a different filter unless you also update the row in filter_playlists.

Example:

UPDATE filter_playlists
SET filter_name = 'Punk'
WHERE filter_name = 'Only punk';

Database Notes

By default, Ruleplay creates spotify_builder.sqlite3 in the project root.

Tables:

• filter_playlists
• artist_cache
• audio_feature_cache

Example query for artist inspection:

SELECT artist_id, artist_name, genres_json
FROM artist_cache
ORDER BY artist_name;

More implementation details are in docs/implementation.md.