Tune by Mozaiklabs

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()
  1. __init__() — Instanciación. No haga NADA aquí (sin I/O, sin imports pesados).
  2. setup(ctx: PluginContext) — Registre rutas, hooks, event listeners, tipos de salida.
  3. Activo — Sus rutas responden, sus hooks se disparan en cada zona.
  4. 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

AtributoTipoDescripción
event_busEventBusPub/sub async — suscribirse o emitir eventos
api_appFastAPIInstancia FastAPI del servidor
dbDatabaseBase de datos async (SQLite o PostgreSQL)
settingsSettingsConfiguració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

EventoArgumentosDisparador
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íaEjemplos
StreamingBandcamp, SoundCloud, Idagio, JioSaavn, Anghami
SalidaSnapcast, Squeezebox, Sonos, DAC USB personalizado
AudioCorrección de sala, EQ paramétrico, MQA, crossfeed
BibliotecaDiscogs, AllMusic, letras de Genius, Wikipedia
IntegraciónHome Assistant, MQTT, Stream Deck, Matter
AnalíticaPrometheus, 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

¿Preguntas? Únase a la conversación en el foro.