Tune by Mozaiklabs

Plugin SDK — Developer Guide

Tune Plugin SDK

Extend Tune Server with your own plugins: streaming connectors, audio outputs, signal processing, home-automation integrations.

A plugin installs with a single command (pip install tune-plugin-xxx) and activates automatically when the server starts. No modification of the core code required.


Quick Start (5 minutes)

1. Create a Python package

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

2. Write the plugin class

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 the entry point

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

4. Install and run

pip install -e ./my-tune-plugin
tune-server  # plugin auto-discovered at startup

Your endpoint is available at GET /api/v1/my-endpoint.


Plugin lifecycle

__init__()  →  setup(ctx)  →  [actif]  →  teardown()
  1. __init__() — Instantiation. Do NOTHING here (no I/O, no heavy imports).
  2. setup(ctx: PluginContext) — Register routes, hooks, event listeners, output types.
  3. Active — Your routes respond, your hooks fire on every zone.
  4. teardown() — Release resources (connections, files, subscriptions).

If setup() raises an exception, the plugin is skipped. The other plugins keep loading.


PluginContext — available API

AttributeTypeDescription
event_busEventBusAsync pub/sub — subscribe to or emit events
api_appFastAPIThe server's FastAPI instance
dbDatabaseAsync database (SQLite or PostgreSQL)
settingsSettingsServer configuration (read-only)

ctx.register_output_type(spec)

Register a new audio output type (Snapcast, Icecast, direct USB DAC…)

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

Mount a FastAPI router. All routes are prefixed automatically.

ctx.register_player_hook(event, fn)

Register a callback on player events.

ctx.register_migrations(path)

Declare an Alembic migrations directory for the plugin's tables.


Player Hooks

EventArgumentsTrigger
BEFORE_TRACK(zone_id, track)Just before playback starts
AFTER_TRACK(zone_id, track)Natural end of a track
PLAY(zone_id,)Play or Resume
PAUSE(zone_id,)Pause
STOP(zone_id,)Stop

Hooks fire for all zones. Sync and async callbacks are supported.


EventBus

Subscribe to the 40+ built-in events or emit your own custom events:

# Subscribe to a core event
unsub = ctx.event_bus.on(EventType.LIBRARY_SCAN_COMPLETED, on_scan)

# Custom event (convention: plugin_name.event)
unsub = ctx.event_bus.on("snapcast.client_connected", handler)

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

Configuration

Use pydantic-settings with the TUNE_<NAME>_* prefix:

from pydantic_settings import BaseSettings

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

Configuration via .env or environment variables.


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"

Naming conventions

  • PyPI package: tune-plugin-<name>
  • Entry point key: <name>
  • Env variables: TUNE_<NAME>_*
  • DB tables: <name>_*

Plugin categories

CategoryExamples
StreamingBandcamp, SoundCloud, Idagio, JioSaavn, Anghami
OutputSnapcast, Squeezebox, Sonos, custom USB DAC
AudioRoom correction, parametric EQ, MQA, crossfeed
LibraryDiscogs, AllMusic, Genius lyrics, Wikipedia
IntegrationHome Assistant, MQTT, Stream Deck, Matter
AnalyticsPrometheus, ListenBrainz, advanced Last.fm scrobbler

Best practices

  • Nothing in __init__() — defer everything to setup()
  • Use structlog — consistent with the server
  • Prefix DB tables and env vars — avoid collisions
  • Unsubscribe in teardown() — no orphaned listeners
  • Handle errors — never crash the player
  • Test in isolation — PluginContext is mockable (see pytest fixtures)

Resources

Questions? Join the discussion on the forum.