Tune by Mozaiklabs

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()
  1. __init__() — インスタンス化。ここでは何もしないでください(I/O なし、重い import なし)。
  2. setup(ctx: PluginContext) — ルート、hook、event listener、output タイプを登録します。
  3. アクティブ — ルートが応答し、hook がすべての zone で発火します。
  4. teardown() — リソース(接続、ファイル、subscription)を解放します。

setup() が例外を送出した場合、そのプラグインはスキップされます。他のプラグインは読み込みを続行します。


PluginContext — 利用可能な API

属性型説明
event_busEventBus非同期 pub/sub — イベントの購読または発行
api_appFastAPIサーバーの FastAPI インスタンス
dbDatabase非同期データベース(SQLite または PostgreSQL)
settingsSettingsサーバー設定(読み取り専用)

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 を参照)

リソース

ご質問は?フォーラムのディスカッションにご参加ください。