Black Candy

Black Candy is a fully self‑hosted audio streaming platform that turns any media library into an on‑premise music service. From a developer’s standpoint, it exposes a RESTful API and WebSocket endpoints that allow programmatic control over playback, library management, and user sessions. The core goal is to provide a lightweight yet feature‑rich backend that can be deployed behind a reverse proxy or within a Kubernetes cluster, while still offering a polished web UI and native mobile clients.

Key Features

• Library ingestion – Scans a mounted media directory, extracts ID3/FLAC tags, and builds an indexed catalog in PostgreSQL.
• Streaming & transcoding – Uses FFmpeg for on‑the‑fly conversion to user‑selected bitrates, supporting progressive HTTP and HLS streaming.
• User & ACL system – Supports OAuth2, JWT tokens, and role‑based access control for fine‑grained permissions.
• Playlists & queues – Exposes endpoints to create, update, and persist complex queue structures that can be shared across devices.
• Webhooks & plugins – Allows external services to react to events (e.g., track play, user login) and extend functionality via a plugin API.

Technical Stack

• Language & Framework – Written in Go (v1.22+) with the Gin web framework, chosen for its compiled performance and minimal runtime footprint.
• Database – PostgreSQL 13+ serves as the relational store; schema migrations are handled by Goose.
• Media backend – FFmpeg (≥4.4) is bundled for transcoding; the application also leverages libavformat to probe media metadata.
• Containerization – A single‑layer Docker image (ghcr.io/blackcandy-org/blackcandy) is built using a multi‑stage Dockerfile, ensuring small attack surface and fast startup.
• Observability – Prometheus metrics are exposed on /metrics; logs use structured JSON for easy ingestion into ELK or Loki stacks.

Deployment & Infrastructure

Deploying Black Candy is a matter of running the Docker image with appropriate port mappings and volume mounts. For production, it is recommended to place the container behind a TLS‑terminating reverse proxy (NGINX/Traefik) and to run PostgreSQL in a dedicated, replicated instance. The application scales horizontally by sharing the same database; however, each node streams audio independently, so network bandwidth becomes the primary bottleneck. Kubernetes manifests are available under deploy/k8s/, allowing stateful sets for the database and deployment of the web tier with autoscaling enabled.

Integration & Extensibility

The plugin system is built on Go interfaces that can be compiled into shared objects and loaded at runtime. Developers can write custom authentication providers, media processors, or UI extensions without modifying the core codebase. Webhooks are JSON‑payload POSTs to configurable endpoints, making it trivial to integrate with CI/CD pipelines, notification services, or analytics platforms. The REST API follows OpenAPI 3.0 specifications, enabling auto‑generated SDKs in languages such as TypeScript, Python, or Java.

Developer Experience

Configuration is driven by environment variables (MEDIA_PATH, DB_URL, JWT_SECRET) and a simple YAML file for advanced settings. The documentation is hosted in the repo’s docs/ directory, with a live API reference generated by Swagger UI. Community support is active on GitHub Discussions and the project’s Discord channel, where contributors can request new features or report bugs. The license (MIT) allows unrestricted use and modification, making it attractive for internal tooling or commercial deployment.

Use Cases

• Personal media server – A tech‑savvy user can host a private music collection with full control over access and quality.
• Enterprise podcast distribution – Organizations can publish internal podcasts, track listens via webhooks, and enforce ACLs per department.
• IoT audio services – Embedded devices can stream music from a local network, leveraging the low‑resource Go binary and efficient FFmpeg transcoding.

Advantages

Black Candy stands out for its combination of performance (Go’s concurrency model), flexibility (plugin architecture and open API), and ease of deployment (single Docker image). Unlike cloud‑centric streaming services, it offers full ownership of data and compliance with strict privacy regulations. Its MIT license removes vendor lock‑in, while the active community ensures rapid iteration and timely security patches.