Relayroom

Masalah dan kebutuhan

Mengelola koleksi musik keluarga di infrastruktur mandiri sering kali menghadapi dua kendala utama: akses pemutaran yang nyaman tanpa ketergantungan aplikasi pihak ketiga, dan alur penambahan lagu baru yang mudah bagi anggota keluarga tanpa intervensi manual setiap saat.

Solusi media server standar seperti Navidrome menyediakan backend Subsonic yang andal, namun belum memiliki antarmuka permintaan terpadu, mekanisme download otomatis dari tautan Spotify, peninjauan metadata sebelum masuk ke perpustakaan kanonik, maupun pemutar web berbobot ringan yang dapat diakses langsung dari peramban tanpa harus menginstal klien khusus.

Relayroom dibangun untuk menjembatani kebutuhan tersebut: menyediakan portal web streaming audio terkurasi untuk keluarga, kotak permintaan lagu mandiri dengan pelacakan progres unduhan langsung, serta konsol administratif untuk menginspeksi, menyunting metadata, dan menyortir berkas musik.

Arsitektur dan integrasi streaming

Relayroom menggabungkan Laravel 12 pada backend dengan Inertia.js dan React 19 pada antarmuka pengguna. Aplikasi ini memanfaatkan integrasi langsung dengan server Navidrome:

• Autentikasi Keluarga: Anggota keluarga masuk menggunakan akun Navidrome yang diverifikasi melalui Subsonic API ping tanpa menyimpan ulang kata sandi di database aplikasi.
• Katalog Terpadu: Koleksi lagu dibaca langsung secara read-only dari database SQLite Navidrome untuk mempertahankan kecepatan query dan mencegah konflik konkurensi data.
• Persistent Web Player: Komponen pemutar audio (PlayerBar) terintegrasi pada layout Inertia, memungkinkan pemutaran musik tetap berlanjut tanpa putus ketika pengguna berpindah-pindah antar halaman koleksi, detail, atau form permintaan.
• Dukungan Lirik & Metadata: Sistem membaca berkas lirik sidecar .lrc serta cover art album langsung dari penyimpanan audio lokal untuk ditampilkan secara sinkron pada antarmuka pemutar.

Request box dan pipeline download

Fitur utama bagi anggota keluarga adalah alur permintaan lagu yang sepenuhnya otomatis:

1. Input Permintaan: Pengguna mencari judul atau menempelkan tautan lagu Spotify pada halaman request.
2. Antrean Unduhan: Permintaan dimasukkan ke queue database Laravel yang dieksekusi secara asinkron oleh worker terpisah (ProcessTrackDownload).
3. Penyedia Media & Validasi: Unduhan ditarik melalui integrasi RapidAPI dengan proteksi server-side: pemeriksaan ukuran berkas minimal, pembersihan nama file, dan pencegahan duplikasi trek berdasarkan signature audio dan ID katalog.
4. Pelacakan Progres Real-time: Antarmuka request menampilkan status langsung (antrean, proses unduh, persentase data, hingga verifikasi importir) melalui polling API terarah.
5. Handoff ke Importir Otomatis: Berkas yang berhasil diunduh dialihkan ke folder inbox bersama untuk diproses lebih lanjut oleh script otomatisasi Python (auto_import.py) yang berjalan via systemd timer untuk menandai ID3 tag, mengambil lirik, dan memicu sinkronisasi library Navidrome.

Konsol admin dan otomasi

Selain area keluarga, Relayroom menyediakan panel kontrol khusus administrator yang dilindungi otentikasi independen:

• Triage & Review: Dasbor untuk memeriksa berkas musik baru yang membutuhkan verifikasi manual, persetujuan metadata, atau penanganan karantina jika terjadi anomali tag atau kualitas audio.
• Lookup Provider: Integrasi pengecekan metadata daring terhadap basis data MusicBrainz dan iTunes untuk memperkaya tahun rilis, genre, dan penamaan artis yang akurat.
• Manajemen Laporan: Modul pelaporan lagu oleh anggota keluarga (misal cover art keliru atau audio rusak) yang dapat ditinjau dan diselesaikan langsung oleh admin.
• Runner & Task History: Utilitas eksekusi task batch dan pencatatan audit log untuk memantau aktivitas sistem, unduhan, dan perubahan status koleksi.

Operasi dan reliabilitas

Relayroom dirancang untuk berjalan efisien pada lingkungan Docker Compose di homelab:

• Konfigurasi Multi-service: Terdiri dari layanan web server aplikasi dan worker queue khusus yang berbagi volume database SQLite lokal berkecepatan tinggi dengan mode WAL (Write-Ahead Logging) dan batas timeout proteksi busy lock.
• Keamanan Penyimpanan: Seluruh direktori koleksi Navidrome dipetakan secara read-only, sedangkan akses tulis dibatasi hanya pada volume inbox unduhan dan antrean spool kontrol.
• Infrastruktur Terdistribusi: Akses publik diamankan melalui Cloudflare Tunnel terenkripsi dengan pemantauan ketersediaan berkala via Uptime Kuma, memastikan sistem tetap ringan, tangguh, dan terpantau sepanjang waktu.