Gonic

gonic is a fully‑self‑hosted media streaming server that implements the Subsonic API, enabling a wide array of existing clients (Airsonic‑refix, Symfonium, dsub, etc.) to interact with a local music library. From a developer’s standpoint, gonic exposes a RESTful interface that mimics Subsonic’s XML/JSON contracts while also offering additional endpoints for transcoding, playlist management, and scrobbling. The server is written in Go, which gives it a small binary footprint and excellent concurrency support—ideal for embedded platforms such as Raspberry Pi or ARM‑based NAS devices. Its architecture is intentionally modular: the core handles HTTP routing, authentication (SHA‑256 salted passwords and token auth), and media metadata extraction; separate goroutines manage on‑the‑fly transcoding via FFmpeg, cache eviction, and background library scans.

Technical Stack

• Language & Runtime: Go 1.22+ (static binary, cross‑compiled for x86_64 and armv7/arm64).
• Web Framework: Standard net/http with a custom router that maps Subsonic paths to handlers; minimal dependencies keep the image size under 100 MB.
• Database: SQLite (default) for persistence of user accounts, playlists, and library metadata. The schema is lightweight but fully ACID‑compliant, making it suitable for single‑node deployments.
• Metadata Extraction: TagLib (via a Go binding) reads ID3v2, Vorbis comments, FLAC tags, etc., enabling tag‑based browsing and multi‑valued tag support.
• Transcoding & Caching: FFmpeg is invoked through the command line; transcoded streams are cached in a memory‑mapped file system (/tmp/gonic_cache) to reduce repeated conversions.
• Scrobbling: Integrations with Last.fm and ListenBrainz are exposed as optional services that can be toggled per‑user via the web UI.
• Testing & CI: Continuous integration runs unit tests against multiple Go versions and container builds, ensuring compatibility across distributions.

Core Capabilities

• Folder & Tag Browsing: Endpoints such as /rest/getMusicDirectory and /rest/search2 allow clients to navigate the physical tree or query by artist/album/genre.
• Gapless Jukebox: The /rest/jukebox API streams pre‑buffered, gapless audio by concatenating decoded PCM frames on the server side.
• On‑the‑Fly Transcoding: Clients can request a specific bitrate or format; gonic spawns FFmpeg processes, streams the output, and caches it for subsequent requests.
• User Management: Multi‑user support with per‑user transcoding profiles, playlist collections, and scrobbling credentials.
• Podcast Support: New podcast feeds can be added via the /rest/addPodcast endpoint; episodes are automatically scanned and indexed.
• Metadata Enrichment: Artist similarity, biographies, and cover art are fetched from the Last.fm API on demand.
• Web Configuration UI: A lightweight React/Vue front‑end exposes all settings, from library paths to FFmpeg options, and can be extended with custom plugins.

Deployment & Infrastructure

gonic ships as a Docker image (both amd64 and arm64/v7 tags) and includes pre‑built binaries for most major Linux distributions. The image contains a minimal alpine base, the Go binary, and a bundled FFmpeg build. For developers targeting high‑throughput scenarios, gonic can be run behind a reverse proxy (NGINX or Traefik) with HTTP/2 and TLS termination. The SQLite database can be externalized to a shared volume or migrated to PostgreSQL with minimal changes, thanks to the sqlx abstraction. Horizontal scaling is limited by SQLite’s file‑locking semantics, but a common pattern is to run multiple gonic instances behind a load balancer and share the media library via NFS or SMB; each instance maintains its own cache to avoid contention.

Integration & Extensibility

While gonic implements the Subsonic API out of the box, developers can augment functionality through its plugin architecture. The plugins directory accepts Go plugins compiled with the same version of Go; these are loaded at startup and can register new HTTP handlers, modify metadata extraction, or hook into the transcoding pipeline. Webhooks are available for external services—e.g., trigger a CI job when a new album is added. The configuration UI can be extended with custom panels by injecting JavaScript modules, allowing teams to build internal dashboards that consume the same API.

Developer Experience

The project’s documentation is hosted on GitHub Wiki and includes detailed sections for source‑based builds, Docker usage, systemd service files, and environment variable configuration. A dedicated Slack channel (Libera.Chat #gonic) provides real‑time support, and the issue tracker is actively maintained with a clear triage process. The API documentation follows Subsonic’s spec, so developers familiar with existing clients can quickly prototype custom front‑ends. The codebase is well‑structured, with clear separation between handlers, services, and utilities, making it approachable for contributors.

Use Cases

• Home Media Server: A single‑user setup on a Raspberry Pi, serving music to Android/iOS clients via Subsonic‑compatible apps.
• Enterprise Audio Hub: