Plugin SDK — Guide Développeur
Tune Plugin SDK
Étendez Tune Server avec vos propres plugins : connecteurs streaming, sorties audio, traitement du signal, intégrations domotique.
Un plugin s'installe en une commande (pip install tune-plugin-xxx) et s'active automatiquement au démarrage du serveur. Aucune modification du code core nécessaire.
Quick Start (5 minutes)
1. Créez un package Python
my-tune-plugin/
pyproject.toml
my_tune_plugin/
__init__.py
2. Écrivez la classe plugin
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. Déclarez l'entry point
[project.entry-points."tune_server.plugins"]
my_plugin = "my_tune_plugin:MyPlugin"
4. Installez et lancez
pip install -e ./my-tune-plugin
tune-server # plugin auto-découvert au démarrage
Votre endpoint est disponible à GET /api/v1/my-endpoint.
Cycle de vie d'un plugin
__init__() → setup(ctx) → [actif] → teardown()
- __init__() — Instanciation. Ne faites RIEN ici (pas d'I/O, pas d'import lourd).
- setup(ctx: PluginContext) — Enregistrez routes, hooks, event listeners, output types.
- Actif — Vos routes répondent, vos hooks se déclenchent sur chaque zone.
- teardown() — Libérez les ressources (connexions, fichiers, subscriptions).
Si setup() lève une exception, le plugin est ignoré. Les autres plugins continuent de charger.
PluginContext — API disponible
| Attribut | Type | Description |
|---|---|---|
event_bus | EventBus | Pub/sub async — s'abonner ou émettre des événements |
api_app | FastAPI | Instance FastAPI du serveur |
db | Database | Base de données async (SQLite ou PostgreSQL) |
settings | Settings | Configuration serveur (lecture seule) |
ctx.register_output_type(spec)
Enregistrer un nouveau type de sortie audio (Snapcast, Icecast, DAC USB direct…)
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")
Monter un router FastAPI. Toutes les routes sont préfixées automatiquement.
ctx.register_player_hook(event, fn)
Enregistrer un callback sur les événements du player.
ctx.register_migrations(path)
Déclarer un répertoire de migrations Alembic pour les tables du plugin.
Hooks Player
| Event | Arguments | Déclenchement |
|---|---|---|
| BEFORE_TRACK | (zone_id, track) | Juste avant le début de lecture |
| AFTER_TRACK | (zone_id, track) | Fin naturelle d'une piste |
| PLAY | (zone_id,) | Play ou Resume |
| PAUSE | (zone_id,) | Pause |
| STOP | (zone_id,) | Stop |
Les hooks se déclenchent pour toutes les zones. Callbacks sync et async supportés.
EventBus
Abonnez-vous aux 40+ événements built-in ou émettez vos propres événements custom :
# S'abonner à un événement core
unsub = ctx.event_bus.on(EventType.LIBRARY_SCAN_COMPLETED, on_scan)
# Événement custom (convention: plugin_name.event)
unsub = ctx.event_bus.on("snapcast.client_connected", handler)
# Émettre
await ctx.event_bus.emit(Event(
type="snapcast.client_connected",
data={"client_id": "abc", "name": "Cuisine"},
source="snapcast_plugin",
))
Configuration
Utilisez pydantic-settings avec le préfixe TUNE_<NAME>_* :
from pydantic_settings import BaseSettings
class MyPluginSettings(BaseSettings):
host: str = "localhost"
port: int = 1780
model_config = {"env_prefix": "TUNE_MYPLUGIN_"}
Configuration via .env ou variables d'environnement.
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"
Conventions de nommage
- Package PyPI :
tune-plugin-<name> - Entry point key :
<name> - Variables env :
TUNE_<NAME>_* - Tables DB :
<name>_*
Catégories de plugins
| Catégorie | Exemples |
|---|---|
| Streaming | Bandcamp, SoundCloud, Idagio, JioSaavn, Anghami |
| Output | Snapcast, Squeezebox, Sonos, custom DAC USB |
| Audio | Room correction, EQ paramétrique, MQA, crossfeed |
| Library | Discogs, AllMusic, Genius lyrics, Wikipedia |
| Integration | Home Assistant, MQTT, Stream Deck, Matter |
| Analytics | Prometheus, ListenBrainz, Last.fm scrobbler avancé |
Bonnes pratiques
- Rien dans __init__() — différez tout vers setup()
- Utilisez structlog — cohérent avec le serveur
- Préfixez tables DB et env vars — évitez les collisions
- Désabonnez dans teardown() — pas de listeners orphelins
- Gérez les erreurs — ne crashez jamais le player
- Testez isolément — PluginContext mockable (voir pytest fixtures)
Ressources
- Guide complet sur GitHub (version anglaise détaillée)
- Plugin d'exemple complet
- Code source API (Protocol + Context)
- Plugin Store — parcourir les plugins disponibles
Questions ? Rejoignez la discussion sur le forum.