Black Candy

Black Candy is an open-source, self-hosted music streaming server that provides a web-based music library and player for personal use. It scans a mounted media directory, builds a browsable catalog from audio metadata, and serves audio to web and mobile clients.

Key Features

• Library indexing from a local media path (reads tags/metadata for artists, albums, tracks)
• Web player with playback queue, playlists and search
• Multi-user accounts and per-user preferences
• Mobile client support (Android APK / F‑Droid and iOS app available) and responsive web UI
• Docker images for easy deployment; supports environment variables for DB, media path and options
• Uses SQLite by default; optional PostgreSQL support for larger deployments
• Integrations: album/artist images via Discogs API; server-side audio handling via FFmpeg; image processing via libvips

Use Cases

• Personal cloud music server to stream your own music library across devices
• Small multi-user household or friend group music sharing with account separation
• Developers or hobbyists building features or integrations on top of a Rails-based streaming backend

Limitations and Considerations

• Default SQLite configuration may not scale well for very large libraries or many concurrent users; PostgreSQL is recommended for larger deployments
• Edge/master images are considered unstable and may contain breaking changes or data-loss risks; use stable releases for production
• Resource usage for large libraries (media scanning, transcoding with FFmpeg, image processing) can be significant and depends on host hardware

Black Candy is focused on delivering a simple, modern self-hosted music experience with mobile support and straightforward Docker deployment. It is suitable for personal and small-group use and can be scaled by using PostgreSQL and appropriate host resources.