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()
- __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 — 사용 가능한 플러그인 둘러보기
궁금한 점이 있으신가요? 포럼의 토론에 참여하세요.