Plugin SDK — Guía del desarrollador
Tune Plugin SDK
Amplíe Tune Server con sus propios plugins: conectores de streaming, salidas de audio, procesamiento de señal, integraciones domóticas.
Un plugin se instala con un solo comando (pip install tune-plugin-xxx) y se activa automáticamente al arrancar el servidor. No requiere modificar el código core.
Inicio rápido (5 minutos)
1. Cree un paquete Python
my-tune-plugin/
pyproject.toml
my_tune_plugin/
__init__.py
2. Escriba la clase 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. Declare el entry point
[project.entry-points."tune_server.plugins"]
my_plugin = "my_tune_plugin:MyPlugin"
4. Instale y ejecute
pip install -e ./my-tune-plugin
tune-server # plugin descubierto automáticamente al arrancar
Su endpoint está disponible en GET /api/v1/my-endpoint.
Ciclo de vida de un plugin
__init__() → setup(ctx) → [actif] → teardown()
- __init__() — Instanciación. No haga NADA aquí (sin I/O, sin imports pesados).
- setup(ctx: PluginContext) — Registre rutas, hooks, event listeners, tipos de salida.
- Activo — Sus rutas responden, sus hooks se disparan en cada zona.
- teardown() — Libere los recursos (conexiones, archivos, subscriptions).
Si setup() lanza una excepción, el plugin se omite. Los demás plugins siguen cargándose.
PluginContext — API disponible
| Atributo | Tipo | Descripción |
|---|---|---|
event_bus | EventBus | Pub/sub async — suscribirse o emitir eventos |
api_app | FastAPI | Instancia FastAPI del servidor |
db | Database | Base de datos async (SQLite o PostgreSQL) |
settings | Settings | Configuración del servidor (solo lectura) |
ctx.register_output_type(spec)
Registrar un nuevo tipo de salida de audio (Snapcast, Icecast, DAC USB directo…)
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")
Montar un router FastAPI. Todas las rutas reciben un prefijo automáticamente.
ctx.register_player_hook(event, fn)
Registrar un callback en los eventos del player.
ctx.register_migrations(path)
Declarar un directorio de migraciones Alembic para las tablas del plugin.
Hooks del reproductor
| Evento | Argumentos | Disparador |
|---|---|---|
| BEFORE_TRACK | (zone_id, track) | Justo antes de iniciar la reproducción |
| AFTER_TRACK | (zone_id, track) | Fin natural de una pista |
| PLAY | (zone_id,) | Reproducir o reanudar |
| PAUSE | (zone_id,) | Pausar |
| STOP | (zone_id,) | Detener |
Los hooks se disparan en todas las zonas. Se admiten callbacks sync y async.
EventBus
Suscríbase a los más de 40 eventos integrados o emita sus propios eventos personalizados:
# Suscribirse a un evento core
unsub = ctx.event_bus.on(EventType.LIBRARY_SCAN_COMPLETED, on_scan)
# Evento personalizado (convención: plugin_name.event)
unsub = ctx.event_bus.on("snapcast.client_connected", handler)
# Emitir
await ctx.event_bus.emit(Event(
type="snapcast.client_connected",
data={"client_id": "abc", "name": "Cuisine"},
source="snapcast_plugin",
))
Configuration
Use pydantic-settings con el prefijo TUNE_<NAME>_*:
from pydantic_settings import BaseSettings
class MyPluginSettings(BaseSettings):
host: str = "localhost"
port: int = 1780
model_config = {"env_prefix": "TUNE_MYPLUGIN_"}
Configuración mediante .env o variables de entorno.
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"
Convenciones de nomenclatura
- Paquete PyPI:
tune-plugin-<name> - Clave del entry point:
<name> - Variables de entorno:
TUNE_<NAME>_* - Tablas de BD:
<name>_*
Categorías de plugins
| Categoría | Ejemplos |
|---|---|
| Streaming | Bandcamp, SoundCloud, Idagio, JioSaavn, Anghami |
| Salida | Snapcast, Squeezebox, Sonos, DAC USB personalizado |
| Audio | Corrección de sala, EQ paramétrico, MQA, crossfeed |
| Biblioteca | Discogs, AllMusic, letras de Genius, Wikipedia |
| Integración | Home Assistant, MQTT, Stream Deck, Matter |
| Analítica | Prometheus, ListenBrainz, scrobbler avanzado de Last.fm |
Buenas prácticas
- Nada en __init__() — aplace todo a setup()
- Use structlog — coherente con el servidor
- Añada prefijo a las tablas de BD y variables de entorno — evite colisiones
- Cancele la suscripción en teardown() — sin listeners huérfanos
- Gestione los errores — nunca haga que el player se bloquee
- Pruebe de forma aislada — PluginContext es mockeable (véanse las fixtures de pytest)
Recursos
- Guía completa en GitHub (versión inglesa detallada)
- Plugin de ejemplo completo
- Código fuente de la API (Protocol + Context)
- Plugin Store — explore los plugins disponibles
¿Preguntas? Únase a la conversación en el foro.