Karaoke Eternal

Karaoke Eternal is a fully self‑hosted media streaming platform that turns any computer or single‑board device into a karaoke server. The system exposes a lightweight web interface for participants to browse, queue, and play songs while the server hosts the media library and orchestrates real‑time synchronization across multiple rooms. From a developer’s perspective, the project is intentionally modular: a Node.js/Express backend serves static assets and API endpoints; a React‑based mobile web app provides the user interface; and a minimal player component runs fullscreen on the host machine, handling audio/video decoding and WebGL visualizations. This separation allows teams to swap out or extend individual components without disrupting the overall workflow.

Key Features

• Multi‑room architecture with optional password protection and dynamic queue balancing to prevent song hogging.
• Support for MP3+G (Winamp/MilkDrop WebGL 2) and MP4 video playback, with ReplayGain normalization for consistent volume levels.
• Browser‑native visualizations that run on WebGL 2, eliminating the need for external plugins or desktop clients.
• Zero‑dependency on microphones – the player outputs only music, giving developers flexibility to integrate external audio routing or hardware.
• No telemetry or ads, ensuring privacy and compliance with stricter data‑handling policies.

Technical Stack

The project ships with Docker Compose files that expose the server as a single container, but developers can also run it directly on any platform with Node.js support. The architecture is intentionally stateless except for the SQLite database, which facilitates horizontal scaling through shared storage or a replicated database layer.

Core Capabilities & APIs

• RESTful endpoints for creating rooms, adding/removing tracks, and querying queue status.
• WebSocket interface for real‑time updates: song changes, queue reordering, and room membership events.
• Webhook hooks that trigger on significant actions (e.g., new song added, room deleted), enabling integration with external services such as Discord bots or Slack notifications.
• Plugin hooks exposed via a simple JavaScript API, allowing developers to inject custom logic (e.g., OAuth authentication, custom visualizations) without modifying core code.
• CLI utilities for bulk media import and metadata extraction, useful in automated deployment pipelines.

Deployment & Infrastructure

Karaoke Eternal is designed to run on “almost anything”: a Windows PC, macOS machine, Raspberry Pi, or Synology NAS. The Docker images are built on Alpine Linux for minimal footprint, and the Compose setup exposes ports 80/443 (HTTPS) with optional TLS termination via a reverse proxy. For scalability, the stateless API layer can be replicated behind a load balancer, while the SQLite database can be migrated to PostgreSQL or MySQL for larger user bases. The player component is intentionally lightweight, consuming <50 MB of RAM on a Pi 4, making it suitable for embedded use cases.

Integration & Extensibility

• Plugin system: Developers can drop JavaScript modules into the plugins/ directory; each module receives a context object containing room state and API helpers.
• Custom visualizations: The WebGL shader pipeline is exposed, allowing developers to replace MilkDrop with any GLSL effect or even integrate Three.js scenes.
• API rate limits: Optional middleware can enforce per‑room or per‑user throttling, useful in high‑traffic scenarios.
• Authentication: While the core app is open by default, developers can integrate JWT or OAuth providers via middleware to restrict access.

The documentation includes a comprehensive reference for the API and plugin lifecycle, and the community maintains a Discord channel where contributors discuss extensions.

Use Cases

1. Bar or club karaoke – Deploy on a dedicated server with a USB audio interface; the player runs fullscreen on the club’s monitor while patrons queue via their phones.
2. Home parties – A Raspberry Pi on a home network hosts the server; guests stream songs from their smartphones, and the host can customize visual effects.
3. Educational workshops – Instructors host music‑theory sessions, using the player to play audio samples while students browse a curated library.
4. Event planning – Organizers can pre‑populate rooms with event‑specific playlists and expose webhooks to trigger stage lighting or sound cues.

Advantages

• Performance: Node.js + WebSocket delivers sub‑100 ms latency for queue updates, and the WebGL visualizer offloads rendering to the GPU.