Tune by Mozaiklabs

Plugin SDK — Guida per sviluppatori

Tune Plugin SDK

Estendi Tune Server con i tuoi plugin: connettori di streaming, uscite audio, elaborazione del segnale, integrazioni domotiche.

Un plugin si installa con un solo comando (pip install tune-plugin-xxx) e si attiva automaticamente all'avvio del server. Nessuna modifica al codice core richiesta.


Avvio rapido (5 minuti)

1. Crea un pacchetto Python

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

2. Scrivi la classe del 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. Dichiara l'entry point

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

4. Installa ed esegui

pip install -e ./my-tune-plugin
tune-server  # plugin rilevato automaticamente all'avvio

Il tuo endpoint è disponibile su GET /api/v1/my-endpoint.


Ciclo di vita di un plugin

__init__()  →  setup(ctx)  →  [actif]  →  teardown()
  1. __init__() — Istanziazione. Non fare NULLA qui (niente I/O, niente import pesanti).
  2. setup(ctx: PluginContext) — Registra route, hook, event listener, tipi di output.
  3. Attivo — Le tue route rispondono, i tuoi hook si attivano su ogni zona.
  4. teardown() — Rilascia le risorse (connessioni, file, subscription).

Se setup() solleva un'eccezione, il plugin viene ignorato. Gli altri plugin continuano a caricarsi.


PluginContext — API disponibile

AttributoTipoDescrizione
event_busEventBusPub/sub async — iscriversi o emettere eventi
api_appFastAPIIstanza FastAPI del server
dbDatabaseDatabase async (SQLite o PostgreSQL)
settingsSettingsConfigurazione del server (sola lettura)

ctx.register_output_type(spec)

Registrare un nuovo tipo di uscita audio (Snapcast, Icecast, DAC USB diretto…)

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")

Montare un router FastAPI. Tutte le route ricevono automaticamente un prefisso.

ctx.register_player_hook(event, fn)

Registrare un callback sugli eventi del player.

ctx.register_migrations(path)

Dichiarare una directory di migrazioni Alembic per le tabelle del plugin.


Hook del player

EventoArgomentiAttivazione
BEFORE_TRACK(zone_id, track)Subito prima dell'inizio della riproduzione
AFTER_TRACK(zone_id, track)Fine naturale di un brano
PLAY(zone_id,)Riproduci o riprendi
PAUSE(zone_id,)Pausa
STOP(zone_id,)Interrompi

Gli hook si attivano per tutte le zone. Sono supportati callback sync e async.


EventBus

Iscriviti agli oltre 40 eventi integrati o emetti i tuoi eventi personalizzati:

# Iscriversi a un evento core
unsub = ctx.event_bus.on(EventType.LIBRARY_SCAN_COMPLETED, on_scan)

# Evento personalizzato (convenzione: plugin_name.event)
unsub = ctx.event_bus.on("snapcast.client_connected", handler)

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

Configuration

Usa pydantic-settings con il prefisso TUNE_<NAME>_*:

from pydantic_settings import BaseSettings

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

Configurazione tramite .env o variabili d'ambiente.


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"

Convenzioni di denominazione

  • Pacchetto PyPI: tune-plugin-<name>
  • Chiave dell'entry point: <name>
  • Variabili d'ambiente: TUNE_<NAME>_*
  • Tabelle DB: <name>_*

Categorie di plugin

CategoriaEsempi
StreamingBandcamp, SoundCloud, Idagio, JioSaavn, Anghami
UscitaSnapcast, Squeezebox, Sonos, DAC USB personalizzato
AudioCorrezione ambientale, EQ parametrico, MQA, crossfeed
LibreriaDiscogs, AllMusic, testi di Genius, Wikipedia
IntegrazioneHome Assistant, MQTT, Stream Deck, Matter
AnalyticsPrometheus, ListenBrainz, scrobbler Last.fm avanzato

Buone pratiche

  • Niente in __init__() — rimanda tutto a setup()
  • Usa structlog — coerente con il server
  • Aggiungi un prefisso a tabelle DB e variabili d'ambiente — evita le collisioni
  • Annulla l'iscrizione in teardown() — nessun listener orfano
  • Gestisci gli errori — non mandare mai in crash il player
  • Testa in isolamento — PluginContext è mockabile (vedi le fixture di pytest)

Risorse

Domande? Partecipa alla discussione sul forum.