downmixer 1.0.1

Bridge streaming services easily with advanced matching

<style> .logo { filter: invert(100%); } @media (prefers-color-scheme: dark) { .logo { filter: invert(0%); } } </style>

downmixer is a library to support connecting between streaming services. It can match any song, from any streaming service (or any arbitrary library of files), with the same song or as close as possible when it straight up isn't available.

It's flexible, and provides a comprehensive API that can be extended for almost any use case. Making your own **provider ** (the bridge between services and downmixer) is as easy as...

import ... from ...


# Every provider needs a separate connection object
class MyProviderConnection(Connection):
    def initialize(self) -> bool:
        # Implement your APIs here
        pass

    # [...]


class MyProvider(BaseProvider):
    def fetch_song(self, id: str) -> Song:
        # Implement your APIs here
        pass

    def fetch_album(self, id: str) -> Album:
        # Implement your APIs here
        pass

    # [...]

Providers inherit from a base class, which has only the basic skeleton of a downmixer Provider; the actual interface the class will have is determined by the Protocols it implements.

You can make your classes inherit all the protocols it uses, but duck typing is recommended.

With your own providers, you can then automate tasks easily with any other service:

from downmixer.matching import match
from downmixer.types.library import ResourceType

# Initialize your providers
conn_a = MyProviderConnection()
conn_a.initialize()
provider_a = MyProvider(conn_a)

conn_b = AnotherProviderConnection()
conn_b.initialize()
provider_b = AnotherProvider(conn_b)

# Fetch a song from one provider and find it on another
song = provider_a.fetch_song("some-id")
results = provider_b.search(song.name, [ResourceType.SONG])
best = match(song, results[0].result)
print(best.quality, best.sum)

The documentation is comprehensive and has a few guides to get you started.

Installation

# uv
uv add git+https://git.gay/neufter/downmixer.git

# pip
pip install git+https://git.gay/neufter/downmixer.git

Development

Work on dev (or a feature branch/fork) and open a PR into main. main branch is protected to keep it clean, and keep commits mostly 1:1 with releases.

Releasing

We use the Release workflow on Forgejo to trigger an automatic release which does all the checks, bumps the version if needed, and commits to main.

Building

Uses uv package manager. To build from source:

git clone https://git.gay/neufter/downmixer
cd downmixer
uv build