Tune by Mozaiklabs

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  # 플러그인이 시작 시 자동으로 검색됩니다

엔드포인트는 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 참조)

리소스

궁금한 점이 있으신가요? 포럼의 토론에 참여하세요.