gonic: a Go implementation of the Subsonic API for your own music library

The gap gonic fills: a Subsonic server you can run as one binary

Subsonic defined an HTTP API for music streaming, and a large ecosystem of clients grew around it. The original server is Java, and the alternatives that followed it mostly inherited that weight. gonic takes the opposite route: it reimplements the Subsonic server API in Go, and the README describes the result as lightweight and suitable for a Raspberry Pi. The intended user is someone with an existing music directory who wants to keep using a Subsonic client (the README lists airsonic-refix, amperfy, Symfonium, DSub, Jamstash, Music Assistant, Strawberry, Ultrasonic and others as tested) without running a JVM-based server. The problem is not streaming audio in the abstract. It is serving an existing library to an existing client, with the client's expectations about browsing, playlists and transcoding intact.

Two ways to browse the same files: folder tree and tags

gonic indexes a music directory in two parallel views. The folder view keeps the full tree intact, so what you see in a Subsonic client mirrors what is on disk. The tag view reads metadata through taglib, and the README states support for mp3, opus, flac, ape, m4a and wav among others. Tag reading is what makes the artist, album and genre lists work, including multi-valued tags such as albumartists and genres, and the album-artist tag so that compilation appearances do not clutter the artist list. This dual indexing is the design decision worth noting. A server that only indexed tags would lose files with poor metadata; a server that only indexed folders would give clients nothing to sort by. gonic keeps both, at the cost of maintaining two representations of the same collection in its database.

Scanning, transcoding and caching: where ffmpeg and taglib sit

The scanning path is the part the README quantifies. The author reports that with a library of roughly 50k tracks, an initial scan takes about 10 minutes and an incremental scan about 6 seconds. That is a single data point from the maintainer's own library, not a benchmark, and it will move with disk speed, file count and metadata quality. Transcoding is on the fly and cached, and it requires ffmpeg. The cache path holds audio transcodes, covers and similar artefacts. That cache is a real operational object: it grows, it can be deleted, and it is separate from the database file. Playlists are also files on disk, not rows in a database. The playlists path holds m3u files named as `<userid>/<name>.m3u`, so the admin user's playlist might be `1/my-playlist.m3u`. gonic creates and edits those files over the Subsonic API, which means the playlist state is inspectable and editable outside the server. That is a deliberate choice in favour of file-based state over opaque storage.

Getting it running: environment variables and the default login

The README gives environment variables with matching command line flags. `GONIC_MUSIC_PATH` (or `-music-path`) points at the collection. `GONIC_PODCAST_PATH` and `-podcast-path` point at a podcasts directory. `GONIC_PLAYLISTS_PATH` and `-playlists-path` point at the m3u directory described above. `GONIC_CACHE_PATH` and `-cache-path` hold transcodes and covers. `GONIC_DB_PATH` and `-db-path` are optional and point at the database file. `GONIC_HTTP_LOG` and `-http-log` control request logging, which the README says is enabled by default. `GONIC_LISTEN_ADDR` and `-listen-addr` set the bind address, defaulting to `0.0.0.0:4747`. `GONIC_TLS_CERT` and `-tls-cert` take a certificate path and enable HTTPS listening. Installation is documented in the project wiki for source, Docker and systemd, and the README points to Repology for packages elsewhere. The default login is admin/admin, and the README says the password can then be changed from the web interface. That web interface also handles last.fm setup, user management and starting scans. The Docker image is published as `sentriz/gonic`.

Where gonic is the wrong tool

Transcoding requires ffmpeg, and tag browsing requires taglib. If neither is available on the host, the feature set narrows sharply. The README does not describe a fallback tag parser, so a deployment without taglib should expect the tag view to be unavailable or degraded, and the tag-based features built on it (artist similarities, biographies from the last.fm API, multi-valued tags) to follow. The second limitation is scope. gonic implements the Subsonic API and a web interface for configuration and administration. It does not present itself as a general media server with its own documented API, and the README does not describe one. If your clients are not Subsonic-compatible, gonic has nothing to offer them. The third is the jukebox mode. The README describes it as gapless server-side playback instead of streaming, which means the audio comes out of the machine running gonic. That is useful only when the server is attached to the speakers you actually want to hear.

How it differs from Airsonic and Navidrome

The closest comparison is Airsonic, the Java Subsonic-compatible server that gonic's tested-client list references through airsonic-refix, and Navidrome, another Go Subsonic-compatible server. The difference in approach is not the API, which all three implement, but what sits behind it. Airsonic carries a JVM and the deployment shape that comes with it, which is the weight gonic was written to avoid. Navidrome also targets a single Go binary, so the interesting distinction is elsewhere: gonic keeps folder browsing as a first-class view alongside tags, and it keeps playlists as m3u files on disk under `<userid>/<name>.m3u` rather than inside its database. If your library is organised by directory and you want clients to see that structure, that is the concrete reason to pick gonic over a tag-first server. The README does not make claims about matching Navidrome feature for feature, and it should not be read as doing so.

Licence, maintenance and what to check before you commit

gonic is GPL-3.0. That matters if you plan to modify it and distribute the result, because the licence's copyleft terms travel with derivative works. Running it on your own hardware for your own library is a different situation from shipping a modified binary to customers, and the licence text is the authority rather than any summary here. On maintenance, the release history shows v0.22.0 in June 2026, v0.21.0 two weeks earlier, and v0.20.1 in January 2026, with the last push to the repository in September 2026. That is a project that ships, and it is not archived. Upgrade cost is mostly operational: the database, the cache directory and the m3u playlists are all persistent state you own, and the README does not describe a migration tool. Back up the database file and the playlists directory before moving between versions. The concrete first checks are the ones the README makes possible: confirm your directory layout matches what the folder view expects, confirm ffmpeg is installed if you want transcoding, and change the admin password from the web interface on first login.

Editorial conclusion

Adopt gonic if you already run Subsonic-compatible clients and want a single Go binary serving a local library, with ffmpeg and taglib available on the host. Do not adopt it if you need a documented HTTP API beyond Subsonic, or if you cannot install ffmpeg. Before committing, verify that your music tree matches the directory layout the README describes, that ffmpeg is on PATH for the transcoding you intend to use, and that the default admin/admin login is changed from the web interface on first start.

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. sentriz/gonic on GitHub