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()
- __init__() — Istanziazione. Non fare NULLA qui (niente I/O, niente import pesanti).
- setup(ctx: PluginContext) — Registra route, hook, event listener, tipi di output.
- Attivo — Le tue route rispondono, i tuoi hook si attivano su ogni zona.
- 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
| Attributo | Tipo | Descrizione |
|---|---|---|
event_bus | EventBus | Pub/sub async — iscriversi o emettere eventi |
api_app | FastAPI | Istanza FastAPI del server |
db | Database | Database async (SQLite o PostgreSQL) |
settings | Settings | Configurazione 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
| Evento | Argomenti | Attivazione |
|---|---|---|
| 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
| Categoria | Esempi |
|---|---|
| Streaming | Bandcamp, SoundCloud, Idagio, JioSaavn, Anghami |
| Uscita | Snapcast, Squeezebox, Sonos, DAC USB personalizzato |
| Audio | Correzione ambientale, EQ parametrico, MQA, crossfeed |
| Libreria | Discogs, AllMusic, testi di Genius, Wikipedia |
| Integrazione | Home Assistant, MQTT, Stream Deck, Matter |
| Analytics | Prometheus, 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
- Guida completa su GitHub (versione inglese dettagliata)
- Plugin di esempio completo
- Codice sorgente dell'API (Protocol + Context)
- Plugin Store — esplora i plugin disponibili
Domande? Partecipa alla discussione sul forum.