Skip to content

Architecture

Pushtunes uses a provider-based architecture where each music platform (Subsonic, Spotify, etc.) is represented by a single MusicProvider subclass. Providers are auto-discovered via a registry.

Provider Model

A provider unifies both reading (source) and writing (service) operations into one class. Each provider declares what it can do via a set of Capability values.

Capability Enum

Capability Meaning
READ Can fetch albums/tracks/playlists from a library
WRITE Can add/remove albums/tracks to a library
PLAYLISTS Can create/modify/read playlists
SEARCH Has API-based search (vs local fuzzy matching)

Self-hosted providers like Subsonic declare only {READ, PLAYLISTS} — write operations are automatically stubbed by the base class with a "not supported" warning. Streaming providers like Spotify declare all four.

Base Class: MusicProvider

Located in pushtunes/providers/base.py. Provides default implementations for common operations so subclasses only need to implement what's unique to their platform.

Default implementations (inherited for free)

  • get_albums() / get_tracks() — load from CacheManager
  • search_albums() / search_tracks() — local fuzzy matching against cache
  • is_album_in_library() / is_track_in_library() — check by service_id then fuzzy match
  • get_playlist() — look up by name or ID, fetch tracks
  • add_album(), add_track(), remove_album(), remove_track() — "not supported" stubs
  • get_user_playlists(), create_playlist(), get_playlist_tracks(), replace_playlist_tracks() — stubs
  • has_capability(cap) — check if a capability is declared

Example: What Each Provider Overrides

Provider Capabilities Overrides
CSV READ, WRITE, PLAYLISTS _fetch_*, _convert_*, add_album/track, playlist ops
Subsonic READ, PLAYLISTS _fetch_*, _convert_*, playlist ops
Jellyfin READ, PLAYLISTS _fetch_*, _convert_*, playlist ops
Tidal READ, WRITE, PLAYLISTS, SEARCH _fetch_*, _convert_*, search_*, write ops, playlist ops
YTM READ, WRITE, PLAYLISTS, SEARCH _fetch_*, _convert_*, search_*, write ops, playlist ops
Spotify READ, WRITE, PLAYLISTS, SEARCH _fetch_*, _convert_*, search_*, write ops, playlist ops

Adding a New Provider

For implementation details (registry, auto-discovery, subclass requirements, and a step-by-step guide with code examples), see Provider Development Guide.