Plugin SDK — 开发者指南
Tune Plugin SDK
用您自己的插件扩展 Tune Server:streaming 连接器、音频输出、信号处理、智能家居集成。
一个插件只需一条命令即可安装(pip install tune-plugin-xxx),并在服务器启动时自动激活。无需修改 core 代码。
快速开始(5 分钟)
1. 创建一个 Python 包
my-tune-plugin/
pyproject.toml
my_tune_plugin/
__init__.py
2. 编写插件类
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. 声明 entry point
[project.entry-points."tune_server.plugins"]
my_plugin = "my_tune_plugin:MyPlugin"
4. 安装并运行
pip install -e ./my-tune-plugin
tune-server # 插件在启动时自动发现
您的 endpoint 位于 GET /api/v1/my-endpoint。
插件生命周期
__init__() → setup(ctx) → [actif] → teardown()
- __init__() — 实例化。此处不要做任何事情(无 I/O,无重量级 import)。
- setup(ctx: PluginContext) — 注册路由、hook、event listener、output 类型。
- 激活 — 您的路由开始响应,您的 hook 会在每个 zone 上触发。
- teardown() — 释放资源(连接、文件、subscription)。
如果 setup() 抛出异常,该插件会被跳过。其他插件将继续加载。
PluginContext — 可用 API
| 属性 | 类型 | 说明 |
|---|---|---|
event_bus | EventBus | 异步 pub/sub — 订阅或发送事件 |
api_app | FastAPI | 服务器的 FastAPI 实例 |
db | Database | 异步数据库(SQLite 或 PostgreSQL) |
settings | Settings | 服务器配置(只读) |
ctx.register_output_type(spec)
注册一种新的音频输出类型(Snapcast、Icecast、直连 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")
挂载一个 FastAPI router。所有路由都会自动添加前缀。
ctx.register_player_hook(event, fn)
在 player 事件上注册回调。
ctx.register_migrations(path)
为插件的表声明一个 Alembic 迁移目录。
播放器 Hook
| 事件 | 参数 | 触发时机 |
|---|---|---|
| BEFORE_TRACK | (zone_id, track) | 播放开始之前 |
| AFTER_TRACK | (zone_id, track) | 曲目自然结束 |
| PLAY | (zone_id,) | 播放或继续 |
| PAUSE | (zone_id,) | 暂停 |
| STOP | (zone_id,) | 停止 |
Hook 会为所有 zone 触发。支持同步和异步回调。
EventBus
订阅 40 多个内置事件,或发送您自己的自定义事件:
# 订阅一个 core 事件
unsub = ctx.event_bus.on(EventType.LIBRARY_SCAN_COMPLETED, on_scan)
# 自定义事件(约定:plugin_name.event)
unsub = ctx.event_bus.on("snapcast.client_connected", handler)
# 发送
await ctx.event_bus.emit(Event(
type="snapcast.client_connected",
data={"client_id": "abc", "name": "Cuisine"},
source="snapcast_plugin",
))
Configuration
使用 pydantic-settings,并采用前缀 TUNE_<NAME>_*:
from pydantic_settings import BaseSettings
class MyPluginSettings(BaseSettings):
host: str = "localhost"
port: int = 1780
model_config = {"env_prefix": "TUNE_MYPLUGIN_"}
通过 .env 或环境变量进行配置。
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"
命名约定
- PyPI 包:
tune-plugin-<name> - Entry point 键:
<name> - 环境变量:
TUNE_<NAME>_* - 数据库表:
<name>_*
插件类别
| 类别 | 示例 |
|---|---|
| 流媒体 | Bandcamp, SoundCloud, Idagio, JioSaavn, Anghami |
| 输出 | Snapcast、Squeezebox、Sonos、自定义 USB DAC |
| 音频 | 房间校正、参数 EQ、MQA、crossfeed |
| 媒体库 | Discogs、AllMusic、Genius 歌词、Wikipedia |
| 集成 | Home Assistant, MQTT, Stream Deck, Matter |
| 分析 | Prometheus、ListenBrainz、高级 Last.fm scrobbler |
最佳实践
- 不要在 __init__() 中做任何事 — 把所有事情推迟到 setup()
- 使用 structlog — 与服务器保持一致
- 为数据库表和环境变量加前缀 — 避免冲突
- 在 teardown() 中取消订阅 — 不要留下孤立的 listener
- 处理错误 — 绝不要让 player 崩溃
- 隔离测试 — PluginContext 可被 mock(参见 pytest fixtures)
资源
- GitHub 上的完整指南(详细英文版)
- 完整的示例插件
- API 源代码(Protocol + Context)
- Plugin Store — 浏览可用的插件
有疑问?欢迎到论坛参与讨论。