Tune by Mozaiklabs

Guida tecnica

Questa pagina è destinata a utenti esperti e integratori: come è costruito Tune, la sua API e i dettagli operativi. Per le impostazioni quotidiane, vedi Configurazione.

Architettura

  • Server: un unico programma, tune-server, scritto in Rust. Indicizza la libreria, decodifica l'audio, pilota i dispositivi e serve l'interfaccia web, l'API e i flussi audio, tutto su una sola porta (8888 per impostazione predefinita).
  • Interfaccia web: un'applicazione Svelte servita dal server (la cartella web/ accanto al programma, oppure TUNE_WEB_DIR).
  • Database: SQLite per impostazione predefinita, PostgreSQL come opzione (vedi Configurazione). Le migrazioni vengono eseguite all'avvio.
  • Decodifica: decoder integrati (Symphonia, più i decoder WavPack e APE propri di Tune, e libopus). Il ricampionamento usa l'interpolazione sinc (rubato). La riproduzione non passa da ffmpeg; con le build pubblicate viene fornito un ffmpeg minimale, solo per la codifica AAC del convertitore.
  • Rilevamento: SSDP per DLNA/UPnP, mDNS per AirPlay e Chromecast, rilevamento Squeezebox su UDP 3483.
  • Tune si presenta inoltre sulla rete come server multimediale UPnP (la sua libreria è visibile alle app di controllo DLNA) e, zona per zona, come renderer UPnP.

API HTTP

Tutte le route si trovano sotto /api/v1. Un elenco JSON delle route è servito da GET /api/v1/system/api-docs (il link Documentazione API in Impostazioni › Sistema › Informazioni). Tune non fornisce una descrizione OpenAPI.

RouteScopo
GET /api/v1/system/healthStato del server: ok o degraded (HTTP 200), error (HTTP 503)
GET /api/v1/system/versionVersione del server
GET /api/v1/system/statsStatistiche (usate dal controllo di integrità dell'immagine Docker)
POST /api/v1/system/scan, GET /api/v1/system/scan/statusAvvia una scansione, ne segue l'avanzamento
GET /api/v1/system/logs?lines=NUltime righe di log (1000 per impostazione predefinita)
GET /api/v1/system/diagnostics/bundleArchivio di diagnostica
GET /api/v1/zonesElenco delle zone
GET /api/v1/zones/{id}/statusStato di riproduzione di una zona
POST /api/v1/zones/{id}/play, /pause, /resume, /stop, /next, /previous, /seek, /volumeComandi di riproduzione
GET /api/v1/zones/{id}/queueCoda
GET /api/v1/searchRicerca nella libreria e nei servizi
GET /api/v1/library/albums, /artists, /tracksLibreria

Gli eventi in tempo reale (riproduzione, coda, scansione…) passano da un WebSocket su /ws (o /api/v1/ws). Le vecchie route /api/scan senza v1 non esistono più.

Autenticazione

L'autenticazione è disattivata per impostazione predefinita, il che lascia l'API aperta a tutta la rete locale. Si attiva tramite l'API (/api/v1/auth/config). Gli account sono profili di Tune, le password sono sottoposte ad hash con Argon2 e le sessioni sono JWT di 24 ore. Un token API di lunga durata viene emesso da POST /api/v1/auth/token. Intestazioni accettate: Authorization: Bearer <token> e Authorization: ApiKey <key>. Anche con l'autenticazione attiva, /system/health e /system/version restano pubbliche. Tune non serve HTTPS: se ti serve, metti davanti un reverse proxy.

Compatibilità Squeezebox / LMS

  • Server SlimProto integrato sulla porta 3483 (TCP e UDP, configurabile con TUNE_SLIMPROTO_PORT), per i lettori Squeezelite e Squeezebox.
  • Porta dei comandi testuali compatibile con LMS sulla 9090 (TUNE_CLI_PORT), che passa alla successiva porta libera se la 9090 è occupata.

Gestione operativa

  • Pacchetto .deb: programma in /opt/tune/, dati in /var/lib/tune/, configurazione in /etc/default/tune-server (conservata tra gli aggiornamenti), unità tune-server.service eseguita come utente tune. apt purge non rimuove mai /var/lib/tune.
  • Docker: immagine renesenses/tune (amd64, arm64). Viene eseguita come utente tune non root (uid 1000), con i volumi /data e /music. Non include né uscite audio locali né PostgreSQL. Su arm64, AirPlay 2 non è disponibile e Tune usa AirPlay 1.
  • Tune OS: basato su Fedora. Programma in /opt/tune, servizio tune, dati in /opt/tune/data, porta 80 inoltrata alla 8888, SSH attivo (accesso root rifiutato).
  • Log: RUST_LOG consente un filtraggio fine per modulo.

Vedi anche