Tune by Mozaiklabs

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()
  1. __init__() — Instanciation. Ne faites RIEN ici (pas d'I/O, pas d'import lourd).
  2. setup(ctx: PluginContext) — Enregistrez routes, hooks, event listeners, output types.
  3. Actif — Vos routes répondent, vos hooks se déclenchent sur chaque zone.
  4. 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

AttributTypeDescription
event_busEventBusPub/sub async — s'abonner ou émettre des événements
api_appFastAPIInstance FastAPI du serveur
dbDatabaseBase de données async (SQLite ou PostgreSQL)
settingsSettingsConfiguration 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

EventArgumentsDé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égorieExemples
StreamingBandcamp, SoundCloud, Idagio, JioSaavn, Anghami
OutputSnapcast, Squeezebox, Sonos, custom DAC USB
AudioRoom correction, EQ paramétrique, MQA, crossfeed
LibraryDiscogs, AllMusic, Genius lyrics, Wikipedia
IntegrationHome Assistant, MQTT, Stream Deck, Matter
AnalyticsPrometheus, 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

Questions ? Rejoignez la discussion sur le forum.