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()
- __init__() — Instanziierung. Tun Sie hier NICHTS (keine I/O, keine schweren Importe).
- setup(ctx: PluginContext) — Registrieren Sie Routen, Hooks, Event-Listener, Output-Typen.
- Aktiv — Ihre Routen antworten, Ihre Hooks werden für jede Zone ausgelöst.
- 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
| Attribut | Typ | Beschreibung |
|---|---|---|
event_bus | EventBus | Async Pub/Sub — Events abonnieren oder senden |
api_app | FastAPI | FastAPI-Instanz des Servers |
db | Database | Async-Datenbank (SQLite oder PostgreSQL) |
settings | Settings | Serverkonfiguration (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
| Event | Argumente | Auslö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
| Kategorie | Beispiele |
|---|---|
| Streaming | Bandcamp, SoundCloud, Idagio, JioSaavn, Anghami |
| Ausgabe | Snapcast, Squeezebox, Sonos, individueller USB-DAC |
| Audio | Raumkorrektur, parametrischer EQ, MQA, crossfeed |
| Bibliothek | Discogs, AllMusic, Genius Songtexte, Wikipedia |
| Integration | Home Assistant, MQTT, Stream Deck, Matter |
| Analytics | Prometheus, 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
- Vollständige Anleitung auf GitHub (detaillierte englische Version)
- Vollständiges Beispiel-Plugin
- API-Quellcode (Protocol + Context)
- Plugin Store — verfügbare Plugins durchsuchen
Fragen? Nehmen Sie an der Diskussion im Forum teil.