musikcube

musikCube is a lightweight, terminal‑driven music engine that bundles an audio library, playback core, and an optional streaming server into a single C++ binary. It is designed for cross‑platform operation, running natively on Windows, macOS, Linux, and even ARM devices such as the Raspberry Pi. The core engine—musikcore—provides robust media handling (gapless playback, crossfading, metadata extraction) while the front‑end (musikcube) exposes a keyboard‑centric UI that can be operated from any terminal or over SSH. Because the application is compiled to a single executable, it has minimal runtime dependencies and can be deployed as a self‑contained service or embedded into other projects.

Technical Stack

• Language & Build: Modern C++ (C++17/20) compiled with GCC, Clang or MSVC. Build system is CMake, allowing platform‑specific toolchain selection and optional static linking.
• Audio Engine: Uses the RtAudio or PortAudio abstraction layer for low‑latency playback, supporting 24 bit/192 kHz output on supported hardware.
• Networking: A lightweight WebSocket server (port 7905) for metadata queries and an HTTP server (port 7906) that streams audio data, optionally transcoding on the fly. The servers are built on top of Boost.Asio for asynchronous I/O.
• Database: Tracks and metadata are stored in a SQLite3 database. The schema is fully indexed to support rapid queries over libraries exceeding 250 k tracks.
• Plugin Architecture: Plugins are shared objects (.so, .dll, .dylib) loaded at runtime. The API exposes hooks for playback control, metadata manipulation, and custom UI widgets, enabling developers to extend functionality without modifying the core.

Core Capabilities

• Library Management: Automatic scanning of directories, tag extraction (ID3v2, Vorbis, FLAC), and real‑time indexing. The API exposes CRUD operations for playlists and queue management.
• Playback Features: Gapless playback, crossfading, and customizable fade curves. Developers can bind to the musikcore API to implement custom playback logic or integrate with external audio routing systems.
• Streaming Server: Exposes a WebSocket endpoint for real‑time metadata and an HTTP endpoint that streams raw PCM or encoded audio. The server can be wrapped with a reverse proxy (NGINX, Caddy) to add TLS and more robust authentication.
• Remote Control: The Android client (musikdroid) communicates via the same WebSocket protocol, allowing developers to build custom remote UIs or integrate with home automation platforms.

Deployment & Infrastructure

• Self‑Hosting: The binary is portable; on Linux it can be run as a systemd service, on macOS as a launch daemon, and on Windows as a scheduled task or service. No external services are required beyond the optional reverse proxy.
• Containerization: A Dockerfile is provided in the repository, making it trivial to spin up a containerized instance for cloud or edge deployments. The image exposes ports 7905 and 7906, and mounts a volume for the music library.
• Scalability: While designed for single‑user environments, the stateless nature of the HTTP stream and WebSocket server means multiple clients can connect concurrently. For larger libraries, tuning SQLite cache size and leveraging SSD storage ensures query performance remains acceptable.

Integration & Extensibility

• Plugin System: Developers can write plugins in C++ that hook into the core event loop. Examples include custom audio effects, third‑party metadata enrichment, or UI overlays.
• API & Hooks: The public API is documented in the Wiki; it includes callback registration for track start/end, queue changes, and playback position updates. This allows integration with external monitoring tools or custom dashboards.
• Webhooks: While not built‑in, the WebSocket interface can be wrapped to emit JSON events that external services can consume via a lightweight webhook listener.

Developer Experience

• Documentation: The project hosts comprehensive Wiki pages covering installation, building from source, Raspberry Pi setup, and advanced configuration. The API is referenced in the source comments.
• Community: Active GitHub issue tracking and a mailing list provide quick responses to feature requests. The plugin examples in the repository serve as practical starting points.
• Configuration: Settings are stored in a plain‑text JSON file (~/.config/musikcube/config.json), making it easy to edit or generate programmatically. Security can be enhanced by placing the config in a secure directory and managing passwords via environment variables.

Use Cases

1. Home Stereo Automation – Run musikCube on a Raspberry Pi connected to a DAC, expose the HTTP stream behind an HTTPS reverse proxy, and control playback from a mobile app or home‑assistant integration.
2. Embedded Audio Applications – Use musikcore as a library inside a custom C++ media player, leveraging its robust tagging and queue logic without re‑implementing the engine.
3. Remote Listening Stations – Deploy a Dockerized instance in a LAN, stream to multiple clients via the WebSocket API, and use the Android app for remote control.

Advantages

• Performance & Low Latency: Native C++ implementation with direct audio API access delivers minimal jitter, suitable for audiophile setups.
• Licensing: Open‑source under a