Relayroom

Problem and requirements

Managing a self-hosted family music collection often presents two distinct operational challenges: providing seamless streaming access without requiring third-party native apps on every personal device, and offering an effortless intake mechanism for family members to request new tracks without manual administrator intervention.

Standard media server solutions like Navidrome provide an excellent Subsonic API backend, but lack an integrated family request intake box, automatic Spotify link ingestion, metadata review queues prior to library ingestion, and a browser-native web player that persists playback across routes.

Relayroom was engineered to bridge these gaps: delivering a curated web streaming portal for household members, an automated track request workflow with real-time download tracking, and an administrative control panel for inspecting, deduplicating, and triaging incoming audio files.

Architecture and streaming integration

Relayroom combines Laravel 12 on the backend with Inertia.js and React 19 on the frontend, integrating tightly with the underlying Navidrome ecosystem:

• Family Authentication: Household members authenticate using their existing Navidrome accounts, verified on the fly via Subsonic ping calls without storing credentials inside the application database.
• Unified Catalog: The collection is queried directly from Navidrome’s SQLite database in read-only mode to ensure maximum query performance while avoiding concurrent write locks.
• Persistent Web Player: An integrated audio player component (PlayerBar) is embedded within the Inertia root layout, allowing continuous background music streaming while navigating across collection pages, track detail views, and request forms.
• Lyrics & Cover Art: The system reads synchronized .lrc sidecar files and embedded artwork directly from local storage, presenting live lyrics alongside audio playback.

Request box and download pipeline

The primary workflow for family members is the self-service track request system:

1. Intake: Users search for a song or paste a Spotify track link into the request interface.
2. Asynchronous Queue: Requests are recorded into the database queue and processed in the background by a dedicated worker container (ProcessTrackDownload).
3. Media Retrieval & Guardrails: Media streams are retrieved through a RapidAPI integration with strict server-side safeguards: file size verification, filename sanitisation, and audio signature deduplication.
4. Live Progress Reporting: The interface polls dedicated status endpoints, rendering real-time stage transitions (queued, downloading percentage, waiting for importer, completed).
5. Automated Importer Handoff: Finished audio downloads are handed off to an intake spool consumed by an external Python automation script (auto_import.py) driven by a systemd timer, which tags ID3 metadata, fetches missing lyrics, and triggers Navidrome library rescans.

Admin console and automation

Beyond the family experience, Relayroom provides a password-gated operations console for managing the media lifecycle:

• Triage & Review: A review interface for evaluating newly arrived tracks, validating metadata tags, or placing problematic audio files into quarantine.
• Provider Lookups: External lookup utilities integrated with MusicBrainz and iTunes API endpoints to automatically fill release years, cover artwork, and standardised artist credits.
• Report Queue: An internal reporting interface where family members can flag missing lyrics, mismatched metadata, or distorted audio files for quick administrative resolution.
• Task Runner & Audit Log: Batch task runners and persistent audit logs tracking ingest activities, manual overrides, and system health.

Operations and reliability

Relayroom is containerised and deployed with Docker Compose on the homelab host:

• Multi-service Deployment: Split into web application and queue worker services sharing a high-performance SQLite database operating in WAL (Write-Ahead Logging) mode with robust busy-timeout configurations.
• Storage Boundaries: The canonical Navidrome music directory is mounted strictly read-only, isolating the media library from unintended file modifications. Write privileges are restricted solely to the intake inbox and task spools.
• Network Ingress & Monitoring: Public ingress is managed via encrypted Cloudflare Tunnels, with uptime health and SSL verification continuously polled and validated by Uptime Kuma.