37 lines (25 loc) · 1.49 KB

Implementation Notes

This file captures implementation details that are useful for maintainers but are not necessary for basic setup and usage.

Storage

SQLite schema is defined in schema.sql.

Tables:

filter_playlists
artist_cache
audio_feature_cache

Notable columns:

filter_playlists.filter_name stores the YAML filter name used to look up or reuse a derived playlist
artist_cache.artist_name stores the latest fetched Spotify artist name for easier inspection

By default, the database is created as spotify_builder.sqlite3 in the project root.

Runtime Behavior

Source playlist pagination is handled automatically.
Tracks are deduplicated by Spotify track ID.
Audio features are fetched in batches of 100 tracks only when at least one configured filter uses an audio.* field.
Artist metadata is fetched in batches of 50 artists.
Tracks are added to Spotify playlists in batches of 100.
Local or unavailable tracks are skipped.
Filter failures are isolated so one broken filter does not stop the full run.
Playlist creation and playlist rename/update requests use minimal metadata payloads because Spotify currently rejects some optional fields with HTTP 400 for some apps.

Spotify Limitations

Spotify does not support placing playlists into folders via the API.
Popularity is intentionally not supported as a filter field in v1.
Some Spotify apps, especially development-mode apps, may not be allowed to access audio-feature endpoints.