Developer links
Black Candy
With 4,300+ GitHub stars and native mobile apps on three platforms, Black Candy transforms any VPS into a private Spotify-style streaming service for your personal music collection. The Ruby on Rails 7 backend with Hotwire Turbo and Stimulus delivers a responsive single-page-feeling web player supporting album browsing, artist views, playlists, favorites, and queue management without full page reloads. Point it at a media directory containing MP3, FLAC, OGG, AAC, or WAV files and Black Candy indexes metadata, fetches album artwork from Discogs API, and begins streaming immediately with on-the-fly transcoding that adapts bitrate to client bandwidth. Multi-user support gives each account independent playlists, favorites, and listening history while sharing the same music library — ideal for families or shared households. Native iOS, Android, and F-Droid apps maintained as separate repositories provide offline caching, background playback, and server discovery for mobile listening. The admin panel manages user accounts, configures media paths, and sets Discogs API tokens for automatic cover art retrieval. Deployment requires one Docker command — `docker run -p 80:80 ghcr.io/blackcandy-org/blackcandy:latest` — with persistent storage volumes for the SQLite database and media directory. For larger deployments, switch to PostgreSQL via environment variables with dedicated database URLs for ActionCable, SolidQueue, and SolidCache. Running on a dedicated VPS on RepoCloud with guaranteed CPU, RAM, and SSD, full root SSH access, and a browser serial console. MIT licensed.
Benefits
- One-Command Docker Deployment
- A single docker run command with two volume mounts deploys a complete music streaming server — no build steps, no compile times, no dependency management required.
- Native Mobile Apps With Offline
- Official iOS App Store, Google Play, and F-Droid apps provide background playback, offline caching, and server discovery without relying on third-party Subsonic clients.
- Zero Subscription Music Streaming
- Stream your entire personal library without monthly fees, upload limits, or algorithmic interference. MIT license ensures no commercial restrictions or forced cloud dependency.
- Multi-User Shared Library Access
- Create individual accounts via the admin panel, each with private playlists and favorites while sharing one music library — perfect for households without duplicate storage.
Features
- Web Audio Player
- Hotwire Turbo-powered single-page player with album art, queue management, playlists, favorites, and artist browsing across desktop and mobile browsers.
- On-the-Fly Transcoding
- Server-side audio transcoding adapts format and bitrate to client capabilities without requiring pre-conversion of FLAC, OGG, AAC, or WAV source files.
- Discogs Album Art
- Automatic cover art retrieval from Discogs API using configurable token — fetches artist images and album covers for your entire library.
- Dual Database Support
- SQLite default for single-user simplicity or PostgreSQL for multi-user concurrency with dedicated ActionCable, SolidQueue, and SolidCache database URLs.
- Multi-Platform Mobile Apps
- Dedicated iOS, Android, and F-Droid applications built with Kotlin Multiplatform providing offline caching, background playback, and native device integration.