Tune by Mozaiklabs

Plugin SDK — Entwicklerhandbuch

Tune Plugin SDK

Erweitern Sie Tune Server mit Ihren eigenen Plugins: Streaming-Konnektoren, Audioausgänge, Signalverarbeitung, Hausautomation-Integrationen.

Ein Plugin wird mit einem einzigen Befehl installiert (pip install tune-plugin-xxx) und aktiviert sich automatisch beim Start des Servers. Keine Änderung am Core-Code erforderlich.


Schnellstart (5 Minuten)

1. Erstellen Sie ein Python-Paket

my-tune-plugin/
  pyproject.toml
  my_tune_plugin/
    __init__.py

2. Schreiben Sie die Plugin-Klasse

from tune_server.plugins.api import PluginContext
import structlog
from fastapi import APIRouter

logger = structlog.get_logger()
router = APIRouter(tags=["my-plugin"])

@router.get("/my-endpoint")
async def my_endpoint():
    return {"status": "ok"}

class MyPlugin:
    name = "my_plugin"
    version = "0.1.0"
    description = "My first Tune plugin"

    async def setup(self, ctx: PluginContext) -> None:
        ctx.register_router(router)
        logger.info("my_plugin_loaded")

    async def teardown(self) -> None:
        logger.info("my_plugin_stopped")

    def config_schema(self):
        return None

3. Deklarieren Sie den Entry Point

[project.entry-points."tune_server.plugins"]
my_plugin = "my_tune_plugin:MyPlugin"

4. Installieren und starten

pip install -e ./my-tune-plugin
tune-server  # Plugin beim Start automatisch erkannt

Ihr Endpoint ist unter GET /api/v1/my-endpoint verfügbar.


Lebenszyklus eines Plugins

__init__()  →  setup(ctx)  →  [actif]  →  teardown()
  1. __init__() — Instanziierung. Tun Sie hier NICHTS (keine I/O, keine schweren Importe).
  2. setup(ctx: PluginContext) — Registrieren Sie Routen, Hooks, Event-Listener, Output-Typen.
  3. Aktiv — Ihre Routen antworten, Ihre Hooks werden für jede Zone ausgelöst.
  4. teardown() — Geben Sie Ressourcen frei (Verbindungen, Dateien, Subscriptions).

Wenn setup() eine Ausnahme auslöst, wird das Plugin übersprungen. Die anderen Plugins werden weiter geladen.


PluginContext — verfügbare API

AttributTypBeschreibung
event_busEventBusAsync Pub/Sub — Events abonnieren oder senden
api_appFastAPIFastAPI-Instanz des Servers
dbDatabaseAsync-Datenbank (SQLite oder PostgreSQL)
settingsSettingsServerkonfiguration (schreibgeschützt)

ctx.register_output_type(spec)

Registrieren Sie einen neuen Audioausgabetyp (Snapcast, Icecast, direkter USB-DAC…)

from tune_server.plugins.api import OutputTypeSpec
from tune_server.audio.formats import AudioCapabilities

spec = OutputTypeSpec(
    name="snapcast",
    factory=my_output_factory,
    capabilities=AudioCapabilities(
        formats=["pcm"],
        sample_rates=[44100, 48000, 96000],
        bit_depths=[16, 24],
    ),
    description="Snapcast multi-room output",
)
ctx.register_output_type(spec)

ctx.register_router(router, prefix="/api/v1")

Binden Sie einen FastAPI-Router ein. Alle Routen erhalten automatisch ein Präfix.

ctx.register_player_hook(event, fn)

Registrieren Sie einen Callback für Player-Events.

ctx.register_migrations(path)

Deklarieren Sie ein Alembic-Migrationsverzeichnis für die Tabellen des Plugins.


Player-Hooks

EventArgumenteAuslöser
BEFORE_TRACK(zone_id, track)Kurz vor dem Start der Wiedergabe
AFTER_TRACK(zone_id, track)Natürliches Ende eines Tracks
PLAY(zone_id,)Wiedergabe oder Fortsetzen
PAUSE(zone_id,)Pause
STOP(zone_id,)Stopp

Hooks werden für alle Zonen ausgelöst. Sync- und Async-Callbacks werden unterstützt.


EventBus

Abonnieren Sie die 40+ integrierten Events oder senden Sie Ihre eigenen benutzerdefinierten Events:

# Ein Core-Event abonnieren
unsub = ctx.event_bus.on(EventType.LIBRARY_SCAN_COMPLETED, on_scan)

# Benutzerdefiniertes Event (Konvention: plugin_name.event)
unsub = ctx.event_bus.on("snapcast.client_connected", handler)

# Senden
await ctx.event_bus.emit(Event(
    type="snapcast.client_connected",
    data={"client_id": "abc", "name": "Cuisine"},
    source="snapcast_plugin",
))

Configuration

Verwenden Sie pydantic-settings mit dem Präfix TUNE_<NAME>_*:

from pydantic_settings import BaseSettings

class MyPluginSettings(BaseSettings):
    host: str = "localhost"
    port: int = 1780
    model_config = {"env_prefix": "TUNE_MYPLUGIN_"}

Konfiguration über .env oder Umgebungsvariablen.


Packaging PyPI

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "tune-plugin-myplugin"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["tune-server>=0.7.0"]

[project.entry-points."tune_server.plugins"]
myplugin = "tune_plugin_myplugin:MyPlugin"

Namenskonventionen

  • PyPI-Paket: tune-plugin-<name>
  • Entry-Point-Schlüssel: <name>
  • Umgebungsvariablen: TUNE_<NAME>_*
  • DB-Tabellen: <name>_*

Plugin-Kategorien

KategorieBeispiele
StreamingBandcamp, SoundCloud, Idagio, JioSaavn, Anghami
AusgabeSnapcast, Squeezebox, Sonos, individueller USB-DAC
AudioRaumkorrektur, parametrischer EQ, MQA, crossfeed
BibliothekDiscogs, AllMusic, Genius Songtexte, Wikipedia
IntegrationHome Assistant, MQTT, Stream Deck, Matter
AnalyticsPrometheus, ListenBrainz, erweiterter Last.fm-Scrobbler

Best Practices

  • Nichts in __init__() — verschieben Sie alles nach setup()
  • Verwenden Sie structlog — konsistent mit dem Server
  • Präfix für DB-Tabellen und Env-Variablen — vermeiden Sie Kollisionen
  • In teardown() abmelden — keine verwaisten Listener
  • Fehler behandeln — bringen Sie niemals den Player zum Absturz
  • Isoliert testen — PluginContext ist mockbar (siehe pytest-Fixtures)

Ressourcen

Fragen? Nehmen Sie an der Diskussion im Forum teil.