Plugin SDK — 開発者ガイド
Tune Plugin SDK
独自のプラグインで Tune Server を拡張しましょう。streaming コネクター、オーディオ出力、信号処理、ホームオートメーション連携など。
プラグインは 1 つのコマンド(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 # プラグインは起動時に自動検出されます
エンドポイントは 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>_* - DB テーブル:
<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 を使う — サーバーと一貫させる
- DB テーブルと環境変数にプレフィックスを付ける — 衝突を避ける
- teardown() で購読を解除する — 孤立した listener を残さない
- エラーを処理する — player を絶対にクラッシュさせない
- 分離してテストする — PluginContext は mock 可能(pytest の fixtures を参照)
リソース
- GitHub の完全ガイド(英語の詳細版)
- 完全なサンプルプラグイン
- API ソースコード(Protocol + Context)
- Plugin Store — 利用可能なプラグインを閲覧
ご質問は?フォーラムのディスカッションにご参加ください。