hub / github.com/sentriz/gonic

github.com/sentriz/gonic @v0.22.0 sqlite

repository ↗ · DeepWiki ↗ · release v0.22.0 ↗

952 symbols 3,304 edges 78 files 68 documented · 7%

README

free-software subsonic server API implementation, supporting its many clients

features

browsing by folder (keeping your full tree intact) see here
browsing by tags (using taglib - supports mp3, opus, flac, ape, m4a, wav, etc.)
on-the-fly audio transcoding and caching (requires ffmpeg) (thank you spijet)
subsonic jukebox mode, for gapless server-side audio playback instead of streaming (thank you lxea)
support for podcasts (thank you lxea)
pretty fast scanning (with my library of ~50k tracks, initial scan takes about 10m, and about 6s after incrementally)
multiple users, each with their own transcoding preferences, playlists, top tracks, top artists, etc.
last.fm scrobbling
listenbrainz scrobbling (thank you spezifisch, lxea)
artist similarities and biographies from the last.fm api
support for multi valued tags like albumartists and genres (see more)
a web interface for configuration (set up last.fm, manage users, start scans, etc.)
support for the album-artist tag, to not clutter your artist list with compilation album appearances
written in go, so lightweight and suitable for a raspberry pi, etc. (see ARM images below)
newer salt and token auth
tested on airsonic-refix, amperfy, symfonium, dsub, jamstash, music-assistant, subsonic.el, sublime music, soundwaves, stmp, termsonic, tempus, strawberry, and ultrasonic

installation

the default login is admin/admin.
password can then be changed from the web interface

...elsewhere

configuration options

env var	command line arg	description
`GONIC_MUSIC_PATH`	`-music-path`	path to your music collection (see also multi-folder support below)
`GONIC_PODCAST_PATH`	`-podcast-path`	path to a podcasts directory
`GONIC_PLAYLISTS_PATH`	`-playlists-path`	path to new or existing directory with m3u files for subsonic playlists. items in the directory should be in the format `<userid>/<name>.m3u`. for example the admin user could have `1/my-playlist.m3u`. gonic create and make changes to these playlists over the subsonic api.
`GONIC_CACHE_PATH`	`-cache-path`	path to store audio transcodes, covers, etc
`GONIC_DB_PATH`	`-db-path`	optional path to database file
`GONIC_HTTP_LOG`	`-http-log`	optional http request logging, enabled by default
`GONIC_LISTEN_ADDR`	`-listen-addr`	optional host and port to listen on (eg. `0.0.0.0:4747`, `127.0.0.1:4747`) (default `0.0.0.0:4747`)
`GONIC_TLS_CERT`	`-tls-cert`	optional path to a TLS cert (enables HTTPS listening)
`GONIC_TLS_KEY`	`-tls-key`	optional path to a TLS key (enables HTTPS listening)
`GONIC_PROXY_PREFIX`	`-proxy-prefix`	optional url path prefix to use if behind reverse proxy. eg `/gonic` (see example configs below)
`GONIC_SCAN_INTERVAL`	`-scan-interval`	optional interval (in minutes) to check for new music (automatic scanning disabled if omitted)
`GONIC_SCAN_AT_START_ENABLED`	`-scan-at-start-enabled`	optional whether to perform an initial scan at startup
`GONIC_SCAN_WATCHER_ENABLED`	`-scan-watcher-enabled`	optional whether to watch file system for new music and rescan
`GONIC_SCAN_EMBEDDED_COVER_ENABLED`	`-scan-embedded-cover-enabled`	optional whether to scan for embedded covers in audio files (default `true`)
`GONIC_JUKEBOX_ENABLED`	`-jukebox-enabled`	optional whether the subsonic jukebox api should be enabled
`GONIC_JUKEBOX_MPV_EXTRA_ARGS`	`-jukebox-mpv-extra-args`	optional extra command line arguments to pass to the jukebox mpv daemon
`GONIC_PODCAST_PURGE_AGE`	`-podcast-purge-age`	optional age (in days) to purge podcast episodes if not accessed
`GONIC_EXCLUDE_PATTERN`	`-exclude-pattern`	optional files matching this regex pattern will not be imported. eg `@eaDir\|[aA]rtwork\|[cC]overs\|[sS]cans\|[sS]pectrals`
`GONIC_MULTI_VALUE_GENRE`	`-multi-value-genre`	optional setting for multi-valued genre tags when scanning (see more)
`GONIC_MULTI_VALUE_ARTIST`	`-multi-value-artist`	optional setting for multi-valued artist tags when scanning (see more)
`GONIC_MULTI_VALUE_ALBUM_ARTIST`	`-multi-value-album-artist`	optional setting for multi-valued album artist tags when scanning (see more)
`GONIC_MULTI_VALUE_ISRC`	`-multi-value-isrc`	optional setting for multi-valued isrc tags when scanning (see more)
`GONIC_TRANSCODE_CACHE_SIZE`	`-transcode-cache-size`	optional size of the transcode cache in MB (0 = no limit)
`GONIC_TRANSCODE_EJECT_INTERVAL`	`-transcode-eject-interval`	optional interval (in minutes) to eject transcode cache (0 = never)
`GONIC_EXPVAR`	`-expvar`	optional enable the /debug/vars endpoint (exposes useful debugging attributes as well as database stats)

multi valued tags (v0.16+)

gonic can support potentially multi valued tags like genres, artists, and albumartists. in both cases gonic will individual entries in its database for each.

this means being able to click find album "X" under both "techno" and "house" for example. or finding the album "My Life in the Bush of Ghosts" under either "David Byrne" or "Brian Eno". it also means not cluttering up your artists list with "A & X", "A and Y", "A ft. Z", etc. you will only have A, X, Y, and Z.

the available modes are:

| value | desc

Extension points exported contracts — how you extend this code

Transcoder (Interface)

(no doc) [4 implementers]

transcode/transcode.go

AudioFile (Interface)

AudioFile is used to avoid some duplication in handlers_raw.go between Track and Podcast [2 implementers]

db/db.go

Result (Interface)

(no doc) [3 implementers]

server/ctrlsubsonic/specidpaths/specidpaths.go

Reader (Interface)

(no doc) [3 implementers]

tags/tags.go

Scrobbler (Interface)

(no doc) [2 implementers]

scrobble/scrobble.go

Middleware (FuncType)

(no doc)

handlerutil/handlerutil.go

ProxyPathResolver (FuncType)

(no doc)

server/ctrladmin/ctrl.go

KeySecretFunc (FuncType)

(no doc)

lastfm/client.go

Core symbols most depended-on inside this repo

server/ctrlsubsonic/spec/spec.go

resp

called by 92

server/ctrlsubsonic/ctrl.go

server/ctrlsubsonic/specidpaths/specidpaths.go

Get

called by 73

server/ctrlsubsonic/params/params.go

NewResponse

called by 63

server/ctrlsubsonic/spec/spec.go

construct

called by 62

db/migrations.go

Shape

Function 401

Method 355

Struct 168

TypeAlias 16

FuncType 7

Interface 5

Languages

Go100%

Modules by API surface

db/db.go91 symbols

db/migrations.go65 symbols

server/ctrlsubsonic/spec/spec.go60 symbols

server/ctrlsubsonic/params/params.go55 symbols

scanner/scanner.go48 symbols

scanner/scanner_test.go38 symbols

server/ctrladmin/handlers.go36 symbols

mockfs/mockfs.go35 symbols

podcast/podcast.go25 symbols

jukebox/jukebox.go25 symbols

server/ctrlsubsonic/handlers_common.go24 symbols

server/ctrlsubsonic/spec/queries.go23 symbols

Dependencies from manifests, versioned

github.com/Masterminds/goutilsv1.1.1 · 1×

github.com/Masterminds/semverv1.5.0 · 1×

github.com/Masterminds/sprigv2.22.0+incompatible · 1×

github.com/PuerkitoBio/goqueryv1.12.0 · 1×

github.com/andybalholm/cascadiav1.3.3 · 1×

github.com/araddon/dateparsev0.0.0-2021042916200 · 1×

github.com/aymerick/douceurv0.2.0 · 1×

github.com/davecgh/go-spewv1.1.1 · 1×

github.com/dexterlb/mpvipcv0.0.0-2024100511321 · 1×

github.com/disintegration/imagingv1.6.2 · 1×

github.com/djherbis/timesv1.6.0 · 1×

github.com/dustin/go-humanizev1.0.1 · 1×

For agents

$ claude mcp add gonic \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

github.com/sentriz/gonic @v0.22.0 sqlite

free-software subsonic server API implementation, supporting its many clients

features

installation

...from source

...with docker

...with systemd

...elsewhere

configuration options

multi valued tags (v0.16+)

Extension points exported contracts — how you extend this code

Core symbols most depended-on inside this repo

Shape

Languages

Modules by API surface

Dependencies from manifests, versioned

For agents