기술 가이드
이 페이지는 고급 사용자와 연동 개발자를 위한 것입니다. Tune의 구성 방식, API, 운영 세부 사항을 설명합니다. 일상적인 설정은 설정을 참조하세요.
아키텍처
- 서버: Rust로 작성된 단일 프로그램
tune-server. 라이브러리를 색인하고, 오디오를 디코딩하고, 기기를 구동하며, 웹 인터페이스, API, 오디오 스트림을 모두 하나의 포트(기본값 8888)로 제공합니다. - 웹 인터페이스: 서버가 제공하는 Svelte 애플리케이션(프로그램 옆의
web/폴더 또는TUNE_WEB_DIR). - 데이터베이스: 기본은 SQLite이며 PostgreSQL은 선택 사항입니다(설정 참조). 마이그레이션은 시작할 때 실행됩니다.
- 디코딩: 내장 디코더(Symphonia, Tune 자체의 WavPack 및 APE 디코더, libopus). 리샘플링에는 sinc 보간(rubato)을 사용합니다. 재생은 ffmpeg를 거치지 않습니다. 공개 빌드에는 최소한의 ffmpeg가 포함되어 있지만, 변환기의 AAC 인코딩에만 사용됩니다.
- 검색: DLNA/UPnP는 SSDP, AirPlay와 Chromecast는 mDNS, Squeezebox 검색은 UDP 3483을 사용합니다.
- Tune은 네트워크에서 UPnP 미디어 서버(라이브러리가 DLNA 제어 앱에 보입니다)로, 그리고 존별로 UPnP 렌더러로도 자신을 알립니다.
HTTP API
모든 라우트는 /api/v1 아래에 있습니다. 라우트의 JSON 목록은 GET /api/v1/system/api-docs에서 제공됩니다(설정 › 시스템 › 정보의 API 문서 링크). Tune은 OpenAPI 명세를 제공하지 않습니다.
| 라우트 | 용도 |
|---|---|
GET /api/v1/system/health | 서버 상태: ok 또는 degraded(HTTP 200), error(HTTP 503) |
GET /api/v1/system/version | 서버 버전 |
GET /api/v1/system/stats | 통계(Docker 이미지의 상태 점검에서 사용) |
POST /api/v1/system/scan, GET /api/v1/system/scan/status | 스캔 시작, 진행 상황 확인 |
GET /api/v1/system/logs?lines=N | 최근 로그 줄(기본값 1000) |
GET /api/v1/system/diagnostics/bundle | 진단 압축 파일 |
GET /api/v1/zones | 존 목록 |
GET /api/v1/zones/{id}/status | 존의 재생 상태 |
POST /api/v1/zones/{id}/play, /pause, /resume, /stop, /next, /previous, /seek, /volume | 재생 명령 |
GET /api/v1/zones/{id}/queue | 대기열 |
GET /api/v1/search | 라이브러리와 서비스 전체 검색 |
GET /api/v1/library/albums, /artists, /tracks | 라이브러리 |
실시간 이벤트(재생, 대기열, 스캔 등)는 /ws(또는 /api/v1/ws)의 WebSocket을 통해 전달됩니다. 예전 /api/scan 라우트(v1 없음)는 더 이상 존재하지 않습니다.
인증
인증은 기본적으로 꺼져 있어, API가 로컬 네트워크 전체에 열려 있습니다. 인증은 API(/api/v1/auth/config)로 켭니다. 계정은 Tune 프로필이고, 비밀번호는 Argon2로 해시되며, 세션은 24시간짜리 JWT입니다. 장기 API 토큰은 POST /api/v1/auth/token으로 발급됩니다. 허용되는 헤더는 Authorization: Bearer <token>과 Authorization: ApiKey <key>입니다. 인증을 켜도 /system/health와 /system/version은 공개로 유지됩니다. Tune은 HTTPS를 제공하지 않습니다. 필요하다면 앞단에 리버스 프록시를 두세요.
Squeezebox / LMS 호환성
- 포트 3483(TCP와 UDP,
TUNE_SLIMPROTO_PORT로 설정 가능)의 내장 SlimProto 서버. Squeezelite와 Squeezebox 플레이어용입니다. - 포트 9090(
TUNE_CLI_PORT)의 LMS 호환 텍스트 명령 포트. 9090이 사용 중이면 다음 빈 포트로 옮겨 갑니다.
운영
- .deb 패키지: 프로그램은
/opt/tune/, 데이터는/var/lib/tune/, 설정은/etc/default/tune-server(업그레이드해도 유지됨)에 있으며,tune-server.service유닛은tune사용자로 실행됩니다.apt purge는/var/lib/tune을 절대 삭제하지 않습니다. - Docker:
renesenses/tune이미지(amd64, arm64). root가 아닌tune사용자(uid 1000)로 실행되며/data와/music볼륨이 있습니다. 로컬 오디오 출력도 PostgreSQL도 포함되어 있지 않습니다. arm64에서는 AirPlay 2를 사용할 수 없으며 Tune은 AirPlay 1을 사용합니다. - Tune OS: Fedora 기반. 프로그램은
/opt/tune, 서비스는tune, 데이터는/opt/tune/data, 포트 80은 8888로 전달되고, SSH가 활성화되어 있습니다(root 로그인은 거부됨). - 로그:
RUST_LOG로 모듈별 세밀한 필터링이 가능합니다.