Tune by Mozaiklabs

技術ガイド

このページは、上級ユーザーとインテグレーター向けです。Tune の構成、API、運用の詳細を説明します。日常的な設定については、設定を参照してください。

アーキテクチャ

  • サーバー：Rust で書かれた単一のプログラム tune-server。ライブラリのインデックス化、オーディオのデコード、デバイスの制御を行い、Web インターフェース、API、オーディオストリームを、すべて 1 つのポート（既定は 8888）で提供します。
  • Web インターフェース：サーバーが配信する 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 の LMS 互換テキストコマンドポート（TUNE_CLI_PORT）。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 で、モジュールごとに細かくフィルタリングできます。

関連項目