Black Candy

A personal music streaming server you run in Docker, with a web player and mobile apps, for listening to your own collection anywhere.

4.4k stars, 228 forks Ruby On GitHub since February 2018

View on GitHub How to run it

Black Candy at a glance

Open sourceYes, MITNo paid parts in the repository
Health49 of 100Actively developed
Self-hostingDockerSteps in the README
InterfaceEnglish onlyNo translation files found
Issue repliesWithin ~7 daysMedian first reply; 73% of recent issues answered

What is Black Candy?

Black Candy turns a folder of music files into a private streaming service. You mount your media directory into the container, log in through the browser and play your library there or in the mobile apps; an Android APK is also attached to GitHub releases. It uses SQLite by default, so a single container is enough for a small home server; PostgreSQL is supported for larger or cloud setups. With a Discogs API token it fetches artist and album artwork. A demo mode locks admin rights, which suits public showcase instances.

Good fit if

  • You own a music collection and want a simple player you can reach from your phone instead of a paid streaming subscription.
  • You prefer one Docker container with an embedded database over a multi-service stack.

Look elsewhere if

  • You want to compare other self-hosted music streamers: Navidrome or koel.
  • Your server should also stream films and TV: Jellyfin.

Before you adopt it

Black Candy is released under the MIT license, with nothing paid in the repository. A single developer writes nearly all of the code, and recent commits are sparse, so expect a slower pace of fixes. Read the upgrade guide before each new version, since releases can bring breaking changes, and set a fixed secret key so sessions survive restarts.

Drafted with AI from the project's README and repository data, then checked against that data on 7 November 2026. Report a correction

How to run Black Candy yourself

Docker
Dockerfile or compose file in the repository
Compose file
None in the repository
Setup effort
Not rated: no compose file to judge from
Kubernetes
No Helm chart in the repository
Desktop and mobile
No app builds in GitHub releases
Interface languages
English only

Install instructions: the README on GitHub.

Black Candy health: is it still maintained?

49 of 100, actively developed

Release rhythmEvery ~4 months2 releases in 12 months; latest v3.2.1
Issue repliesWithin ~7 daysMedian first reply; 73% of recent issues answered
Bus factorHigh riskThe most active of 2 authors wrote 88% of recent commits
  • Activity
    8 commits in the last 90 days, the latest on 7 October 2026.
    12 / 30
  • Contributors
    2 people wrote the 8 commits of the last 90 days; the most active wrote 88% of them.
    4 / 20
  • Releases
    2 releases in the last 12 months; the latest, v3.2.1, on 26 August 2026.
    15 / 20
  • Replies to issues
    Maintainers answered 73% of recent issues, with a median first reply after 7 days.
    13 / 20
  • Security practices
    No OpenSSF Scorecard for this repository yet, so this part gets a neutral score.
    5 / 10

Read from GitHub on 7 November 2026. How the score works

Black Candy license: is it open source?

Black Candy uses MIT, an open-source license approved by the OSI.

  1. February 2018First published on GitHub.
  2. TodayMIT.

Black Candy for developers

Written in

  • Ruby 61%
  • HTML 19%
  • CSS 11%
  • JavaScript 9%
  • Dockerfile <1%
  • Other <1%

Getting involved

Contributing guideNot foundNo CONTRIBUTING file in the repository
Open issues28On GitHub
Authors, 90 days2Of 8 commits

Language shares are GitHub’s count of the code in the repository.

Alternatives to Black Candy

  • koelMusic streaming solution that works. 74 health · MIT · 17.3k stars
  • NavidromeYour Personal Streaming Service 84 health · GPL-3.0 · 24.6k stars
  • MediaCMSMediaCMS is a modern, fully featured open source video and media CMS 64 health · AGPL-3.0 · 5.2k stars
  • SnapcastSynchronous multiroom audio player 47 health · GPL-3.0 · 8.1k stars
  • MopidyMopidy is an extensible music server written in Python 67 health · Apache-2.0 · 8.6k stars

All 28 projects in Media servers & streaming

Questions about Black Candy

Is Black Candy open source?

Yes. Black Candy is published under MIT, an OSI-approved open-source license.

Is Black Candy still maintained?

Its health score is 49 of 100 (actively developed). It had 8 commits in the last 90 days, the latest on 7 October 2026, and its latest release came out on 26 August 2026.

How do I run Black Candy?

You can run it with Docker. The README on GitHub has the exact steps.

What is Black Candy written in?

Black Candy is written mainly in Ruby (61% of the code), with HTML (19%) and CSS (11%), by GitHub’s count of the repository.

What are the alternatives to Black Candy?

Close alternatives in the Media servers & streaming category include koel, Navidrome, MediaCMS.