NymphCast

NymphCast is a lightweight, network‑centric media streaming platform designed for Linux‑capable hardware such as Raspberry Pi, Intel NUCs, or any ARM/AMD device. At its core, it separates the receiver (the target device that decodes and outputs audio/video) from a client controller (desktop or mobile app). The server exposes a UDP discovery protocol on port 4004 and accepts TCP playback streams on the same port, enabling zero‑configuration discovery in a local network. The architecture is intentionally minimal to keep CPU usage low on embedded devices, yet it supports advanced features like multi‑room synchronization and plugin‑driven extensions.

Technical Stack & Architecture

• Core Runtime: C++17, leveraging the standard library for cross‑platform portability. The server is compiled with GCC/Clang and statically linked to reduce runtime dependencies.
• Networking: Custom UDP multicast discovery (RFC 6762‑style) and a TCP socket server for stream control. All communication is framed with a simple binary protocol that includes command IDs, payload lengths, and checksums for reliability.
• Media Decoding: The server relies on libav (FFmpeg) for decoding MP3, AAC, H.264, and other common codecs. Decoded frames are forwarded to either ALSA for audio or DRM/Wayland compositors for video.
• Configuration: Profiles are stored as plain INI files (nymphcast_audio_config.ini, nymphcast_video_config.ini, etc.), allowing developers to script or embed configuration changes without recompilation.
• Plugin System: AngelScript is embedded for runtime scripting. Developers can write small scripts to add support for niche protocols (e.g., RTSP, Chromecast) or customize the client UI logic. The script API exposes the networking stack, media pipeline, and event callbacks.

Core Capabilities & APIs

• File Streaming: Direct playback of local or remote files via HTTP/HTTPS, FTP, or SMB. The client can stream entire playlists with minimal buffering.
• Subtitle & Stream Selection: Current support for bitmap subtitles (PGS) with future extensions planned for text and external subtitle formats.
• Multi‑cast Playback: Experimental but functional multi-room sync, achieved by broadcasting a master clock over UDP and synchronizing playback positions on each receiver.
• Extensibility: Developers can hook into the event loop to implement custom protocols or UI widgets. The AngelScript API allows adding new command handlers, manipulating playback queues, and exposing internal state to the client.
• Webhooks & REST: While not a full HTTP server, the client SDK exposes a lightweight JSON‑over‑TCP interface that can be repurposed for simple webhooks or integrated into home automation systems.

Deployment & Infrastructure

NymphCast is designed for self‑hosting on resource‑constrained devices. A single binary (≈ 15 MB) runs on ARMv6 (Pi 2/Zero) and x86_64, requiring only the OS base packages. The application can be containerized with Docker; a minimal Dockerfile pulls the prebuilt binary and exposes ports 4004/UDP/TCP. For larger deployments, a fleet of receivers can be orchestrated with Kubernetes or Docker‑Compose, using ConfigMaps to inject per‑room profiles.

Scalability is limited by network bandwidth and the CPU decoding capability of each receiver. However, because each device operates independently, adding more rooms is as simple as powering on another Pi and configuring its profile. The lightweight UDP discovery ensures that new receivers appear automatically without manual IP assignment.

Integration & Extensibility

The client side is available as a cross‑platform SDK written in C++/Qt, exposing classes for discovery, playback control, and event handling. Developers can embed this SDK into custom GUIs or automate playback via scripts. The AngelScript engine on the server side allows adding new media sources (e.g., DLNA, UPnP) without touching the core C++ code. The API surface is documented in doc/ and includes sample scripts for adding a custom protocol.

Developer Experience

Documentation is organized into clear sections: Getting Started, Developer's Guide, and SDK. Inline comments in the C++ source are plentiful, and the AngelScript API is accompanied by example scripts. Community support is active on GitHub Issues; contributors can submit patches for new codecs or bug fixes. The project’s license (MIT) guarantees unrestricted use and modification, which is attractive for commercial or embedded product developers.

Use Cases

1. Home Media Server – Deploy a Pi as an audio/video sink for a living‑room TV, controlled from a smartphone or desktop.
2. Multi‑Room Audio – Use the multi‑cast feature to sync music across several rooms, ideal for a smart home setup.
3. Custom Media Player – Embed the SDK into an existing application (e.g., a kiosk or digital signage) to provide network playback.
4. IoT Integration – Expose the AngelScript API as a webhook endpoint for Home Assistant or OpenHAB, enabling voice‑controlled playback.

Advantages

• Performance: Native C++ code and direct FFmpeg integration keep CPU usage low, essential for ARM devices.
• Flexibility: AngelScript scripting lets developers add features without recompiling the core.
• Licensing: MIT license allows commercial use with no royalties or copyleft obligations.
• Community & Modularity: Active GitHub repository, modular design, and clear