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()
- __init__() — Instantiation. Do NOTHING here (no I/O, no heavy imports).
- setup(ctx: PluginContext) — Register routes, hooks, event listeners, output types.
- Active — Your routes respond, your hooks fire on every zone.
- teardown() — Release resources (connections, files, subscriptions).
If setup() raises an exception, the plugin is skipped. The other plugins keep loading.
PluginContext — available API
| Attribute | Type | Description |
|---|---|---|
event_bus | EventBus | Async pub/sub — subscribe to or emit events |
api_app | FastAPI | The server's FastAPI instance |
db | Database | Async database (SQLite or PostgreSQL) |
settings | Settings | Server 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
| Event | Arguments | Trigger |
|---|---|---|
| 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
| Category | Examples |
|---|---|
| Streaming | Bandcamp, SoundCloud, Idagio, JioSaavn, Anghami |
| Output | Snapcast, Squeezebox, Sonos, custom USB DAC |
| Audio | Room correction, parametric EQ, MQA, crossfeed |
| Library | Discogs, AllMusic, Genius lyrics, Wikipedia |
| Integration | Home Assistant, MQTT, Stream Deck, Matter |
| Analytics | Prometheus, 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
- Full guide on GitHub (detailed English version)
- Complete example plugin
- API source code (Protocol + Context)
- Plugin Store — browse available plugins
Questions? Join the discussion on the forum.