Providers

Since Downmixer is made to be as platform-agnostic as possible, it works with a provider system. Providers communicate with various music services and implement one or more capability protocols to indicate what features they support.

Architecture

Providers are built on two main concepts:

Connections

Connections handle the lifecycle of connecting to a music service, including initialization and authentication. They also include the client, which is usually a third-party library that directly talks to the service's API (like spotipy for Spotify, ytmusicapi for YouTubeMusic, etc.). There are two base connection types:

• Connection: Base class for services that don't require user authentication
• AuthenticatedConnection: Extended class for services requiring user login

Connections are passed to providers when they're instantiated:

provider = YourProvider(connection=YourConnection)

But they can also be changed at any point in their lifetime using Base.Provider.change_connection(). Beware of implementation details with clients, they might not like having their tokens and whatnot suddenly changing.

Protocols

Protocols define the capabilities a provider can offer. A provider can implement multiple protocols:

Protocol	Description
SupportsMetadata	Search and fetch metadata for songs, albums, artists, playlists, and users
SupportsLibrary	Access user's saved library (playlists, albums, songs, artists)

Protocols that depend on application-level types (such as SupportsAudioDownload returning LocalFile, or SupportsLyrics) should be defined in the consuming application.

Creating Custom Providers

Providers must be packages with:

1. A class derived from BaseProvider in their __init__.py
2. A get_provider() function returning the provider class
3. A library.py file with adapter classes for converting API data to internal models
4. One or more Connection subclasses for service connectivity

See the reference for complete API documentation.