Black Candy — Self-Hosted Music Streaming Server

Introduction

Black Candy is a self-hosted music streaming server built with Ruby on Rails and Hotwire. It scans your local music library, extracts metadata and album art, and provides a responsive web player for streaming from any browser. It focuses on simplicity and a clean listening experience without the complexity of larger media servers.

What Black Candy Does

• Scans local music directories and indexes tracks with metadata from ID3 tags
• Streams music to any web browser with a built-in HTML5 audio player
• Organizes music by artist, album, genre, and custom playlists
• Supports multiple user accounts with individual libraries and favorites
• Displays album artwork extracted from files or fetched from online sources

Architecture Overview

Black Candy is a Rails application using PostgreSQL for metadata storage and Active Storage for media file management. Audio files remain on disk in the configured media directory. The frontend uses Hotwire (Turbo and Stimulus) for a single-page-app feel without a heavy JavaScript framework. Audio transcoding is handled by FFmpeg when needed.

Self-Hosting & Configuration

• Deploy via Docker with volumes for music files and application storage
• Point the media volume to your existing music library directory
• Configure PostgreSQL connection settings or use the bundled database
• Run the media scan from the admin panel to index your music collection
• Create user accounts for family members or friends

Key Features

• Clean, distraction-free web player with album art and playback controls
• Multi-user support with per-user playlists and favorites
• Automatic metadata extraction from ID3, Vorbis, and FLAC tags
• Mobile-responsive design that works well on phones and tablets
• Dark mode support for comfortable late-night listening

Comparison with Similar Tools

• Navidrome — Subsonic-compatible with broad client support; Black Candy provides a simpler web-only experience
• Jellyfin — full media server for video and music; Black Candy is purpose-built for music
• Koel — similar concept with Vue.js frontend; Black Candy uses Rails and Hotwire
• Plex — commercial with premium features; Black Candy is fully open source and free

FAQ

Q: What audio formats are supported? A: Black Candy supports MP3, FLAC, OGG, WAV, AAC, and other formats that FFmpeg can process.

Q: Is there a mobile app? A: Black Candy is accessed through the web browser. The responsive design works well on mobile devices.

Q: Can I stream outside my local network? A: Yes. Expose Black Candy through a reverse proxy with HTTPS for secure remote access.

Q: How large a library can it handle? A: Black Candy handles libraries with tens of thousands of tracks. Performance depends on server resources and database speed.

Sources

• https://github.com/blackcandy-org/blackcandy
• https://github.com/blackcandy-org/blackcandy#readme