Black Candy

What Black Candy does

Black Candy is a personal music streaming server written in Ruby on Rails. It indexes a music folder and offers a web player for browsing by album, artist and song, with search, album filters, playlists, favorites and a play queue. An administrator creates and manages user accounts.

Instead of relying on the Subsonic ecosystem, Black Candy has its own mobile apps. The iOS app is on the App Store, and the Android app is on Google Play and F-Droid, with APK files also published on GitHub. That gives a consistent experience across devices, but it also means third-party Subsonic apps cannot connect.

Streaming and library features

When a device cannot play a file, Black Candy transcodes it to MP3. The administrator chooses 128, 192 or 320 kbps, and can decide whether lossless files are transcoded too. Transcoded files are cached. The browser and mobile apps each have a list of formats they play natively; WMA, for example, is always transcoded for the web.

An optional media listener watches the music folder and syncs changes automatically. Artist and album images can be fetched from the Discogs API once you add a Discogs token in the settings. A demo mode, used on the public demo server, removes administrator rights from every account.

Self-hosting Black Candy

Installation is a single Docker image, published on both GitHub Container Registry and Docker Hub. One docker run command starts the server; for real use you mount the music folder and point MEDIA_PATH at it, and mount /rails/storage so the database and other data persist. The README provides a Docker Compose example. The container listens on port 80 by default.

SQLite is the default database, which the project describes as a good fit for small self-hosted servers. PostgreSQL is supported for larger setups or hosting platforms, and it requires separate connection URLs for the main, pub/sub, job queue and cache databases. Parallel media syncing is only available with PostgreSQL.

Two settings deserve attention. Set SECRET_KEY_BASE to a long random string, otherwise a new one is generated at each start and everyone is logged out. And change the initial administrator account, which uses a published default email and password. Before upgrading, read the upgrade guide: the README warns that new versions may contain breaking changes. An edge image built from the main branch exists for testing only.

Hosted version

There is no hosted service. A public demo with music from the Free Music Archive is available.

Limitations

No Subsonic or other standard API is documented, so you are limited to the web player and the official apps. Documentation is the README and an upgrade guide. Features found in larger servers, such as podcasts, folder browsing or scrobbling, are not documented. Upgrades can involve manual steps.

Who it suits

Black Candy suits people who want to get a music server running with a single container and use polished first-party apps on their phones, without choosing between Subsonic clients. It is a simple way to replace Spotify for your own files. If you need compatibility with many clients, compare Navidrome.