Tune by Mozaiklabs

Guía técnica

Esta página está dirigida a usuarios avanzados e integradores: cómo está construido Tune, su API y detalles de operación. Para los ajustes de uso diario, consulta Configuración.

Arquitectura

  • Servidor: un único programa, tune-server, escrito en Rust. Indexa la biblioteca, decodifica el audio, controla los dispositivos y sirve la interfaz web, la API y los flujos de audio, todo en un solo puerto (8888 por defecto).
  • Interfaz web: una aplicación Svelte servida por el servidor (la carpeta web/ junto al programa, o TUNE_WEB_DIR).
  • Base de datos: SQLite por defecto, PostgreSQL como opción (consulta Configuración). Las migraciones se ejecutan al arrancar.
  • Decodificación: decodificadores integrados (Symphonia, más los decodificadores WavPack y APE propios de Tune, y libopus). El remuestreo usa interpolación sinc (rubato). La reproducción no pasa por ffmpeg; las compilaciones publicadas incluyen un ffmpeg mínimo, solo para la codificación AAC del conversor.
  • Descubrimiento: SSDP para DLNA/UPnP, mDNS para AirPlay y Chromecast, descubrimiento de Squeezebox en UDP 3483.
  • Tune también se presenta en la red como un servidor multimedia UPnP (su biblioteca es visible para las aplicaciones de control DLNA) y, zona por zona, como un reproductor UPnP.

API HTTP

Todas las rutas están bajo /api/v1. Una lista JSON de rutas se sirve en GET /api/v1/system/api-docs (el enlace Documentación de la API en Configuración › Sistema › Acerca de). Tune no proporciona una descripción OpenAPI.

RutaFinalidad
GET /api/v1/system/healthEstado del servidor: ok o degraded (HTTP 200), error (HTTP 503)
GET /api/v1/system/versionVersión del servidor
GET /api/v1/system/statsEstadísticas (usadas por la comprobación de estado de la imagen Docker)
POST /api/v1/system/scan, GET /api/v1/system/scan/statusIniciar un escaneo, seguir su progreso
GET /api/v1/system/logs?lines=NÚltimas líneas del registro (1000 por defecto)
GET /api/v1/system/diagnostics/bundleArchivo de diagnósticos
GET /api/v1/zonesLista de zonas
GET /api/v1/zones/{id}/statusEstado de reproducción de una zona
POST /api/v1/zones/{id}/play, /pause, /resume, /stop, /next, /previous, /seek, /volumeComandos de reproducción
GET /api/v1/zones/{id}/queueCola
GET /api/v1/searchBúsqueda en la biblioteca y los servicios
GET /api/v1/library/albums, /artists, /tracksBiblioteca

Los eventos en tiempo real (reproducción, cola, escaneo…) pasan por un WebSocket en /ws (o /api/v1/ws). Las antiguas rutas /api/scan sin v1 ya no existen.

Autenticación

La autenticación está desactivada por defecto, lo que deja la API abierta a toda la red local. Se activa a través de la API (/api/v1/auth/config). Las cuentas son perfiles de Tune, las contraseñas se almacenan con hash Argon2 y las sesiones son JWT de 24 horas. Un token de API de larga duración se emite con POST /api/v1/auth/token. Cabeceras aceptadas: Authorization: Bearer <token> y Authorization: ApiKey <key>. Incluso con la autenticación activada, /system/health y /system/version siguen siendo públicas. Tune no sirve HTTPS: coloca un proxy inverso delante si lo necesitas.

Compatibilidad con Squeezebox / LMS

  • Servidor SlimProto integrado en el puerto 3483 (TCP y UDP, configurable con TUNE_SLIMPROTO_PORT), para reproductores Squeezelite y Squeezebox.
  • Puerto de comandos de texto compatible con LMS en el 9090 (TUNE_CLI_PORT), que pasa al siguiente puerto libre si el 9090 está ocupado.

Operación

  • Paquete .deb: programa en /opt/tune/, datos en /var/lib/tune/, configuración en /etc/default/tune-server (se conserva entre actualizaciones), unidad tune-server.service ejecutada con el usuario tune. apt purge nunca elimina /var/lib/tune.
  • Docker: imagen renesenses/tune (amd64, arm64). Se ejecuta con el usuario tune sin privilegios de root (uid 1000), con los volúmenes /data y /music. No incluye ni salidas de audio locales ni PostgreSQL. En arm64, AirPlay 2 no está disponible y Tune usa AirPlay 1.
  • Tune OS: basado en Fedora. Programa en /opt/tune, servicio tune, datos en /opt/tune/data, puerto 80 redirigido al 8888, SSH activado (inicio de sesión como root rechazado).
  • Registros: RUST_LOG permite un filtrado fino por módulo.

Véase también