imcarsen / go-subsonic

API client library for Subsonic-compatible music servers

go-subsonic

This is an API client library for Subsonic and Subsonic-compatible music servers. It is tested on Subsonic, Airsonic, and Navidrome.
This is a slightly modified version of dweymouth/go-subsonic

Docs

Changes and reasoning

The Stream and Download functions did not support seeking.

Changes made:

• Added SeekableReader, which implements io.Reader and io.Seeker interfaces
• Made the Stream and Download functions use SeekableReader
• Update to Go version 1.22

Will I actively maintain this?

Kind of. If people have PRs or issues, I may be willing to look at/into them. But I can't promise anything.

Testing

Tests for this library run live against instances of Subsonic-compatible servers. A docker-compose setup comes with this repo to run instances of Airsonic and Navidrome for testing purposes. To set up the test environment and run tests against the docker containers, run test.sh. This test runner does the following:

• Download CC-licensed sample music into build/music
• Set up a location for configuration for both servers in build/data
• Run docker-compose up to initialize both servers with the music & configuration directories as volumes
• Wait until the servers are up
• Run tests for both Subsonic and Navidrome

The tests for Subsonic run against the demo server, so please be mindful to exclude them from all but final test runs in respect for their server load. To manually tests for only one server type, use the -run argument to go test like so:

# Just Airsonic
go test . -test.v -run Airsonic
# Subsonic and Airsonic
go test . -test.v -run '(Sub|Air)sonic'
# Navidrome
go test . -test.v -run Navidrome

If you intend on testing with your own server, modify the top-level TestSubsonic, TestAirsonic, or TestNavidrome functions with your server's address and credentials. Please test this library with other Subsonic-compatible streaming servers, and file an issue if something is amiss!

API Support

System

• ping (1.0.0)
• getLicense (1.0.0)

Browsing

• getMusicFolders (1.0.0)
• getIndexes (1.0.0)
• getMusicDirectory
• getGenres (1.9.0)
• getArtists (1.8.0)
• getArtist (1.8.0)
• getAlbum (1.0.0)
• getSong (1.8.0)
• getArtistInfo (1.11.0)
• getArtistInfo2 (1.11.0)
• getAlbumInfo (1.14.0)
• getAlbumInfo2 (1.14.0)
• getSimilarSongs (1.11.0)
• getSimilarSongs2 (1.11.0)
• getTopSongs (1.13.0)

Album/song lists

• getAlbumList (1.2.0)
• getAlbumList2 (1.8.0)
• getRandomSongs (1.2.0)
• getSongsByGenre (1.9.0)
• getNowPlaying (1.0.0)
• getStarred (1.8.0)
• getStarred2 (1.8.0)

Searching

• search2 (1.4.0)
• search3 (1.8.0)

Playlists

• getPlaylists (1.0.0)
• getPlaylist (1.0.0)
• createPlaylist (1.2.0)
• updatePlaylist (1.8.0)
• deletePlaylist (1.2.0)

Media retrieval

• stream (1.0.0)
• download (1.0.0)
• getCoverArt (1.0.0)
• getLyrics (1.2.0)
• getAvatar (1.8.0)

Media annotation

• star (1.8.0)
• unstar (1.8.0)
• setRating (1.6.0)
• scrobble (1.5.0)

User management

• getUser (1.3.0)
• getUsers (1.8.0)
• createUser (1.1.0)
• updateUser (1.10.1)
• deleteUser (1.3.0)
• changePassword (1.1.0)

Media library scanning

• getScanStatus (1.15.0)
• startScan (1.15.0)

Jukebox

• jukeboxControl (1.2.0)

Bookmarks

• getBookmarks (1.9.0)
• createBookmark (1.9.0)
• deleteBookmark (1.9.0)
• getPlayQueue (1.12.0)
• savePlayQueue (1.12.0)

Sharing

• getShares (1.6.0)
• createShare (1.6.0)
• updateShare (1.6.0)
• deleteShare (1.6.0)

Podcast

• getPodcasts (1.6.0)
• getNewestPodcasts (1.13.0)
• refreshPodcasts (1.9.0)
• createPodcastChannel (1.9.0)
• deletePodcastChannel (1.9.0)
• deletePodcastEpisode (1.9.0)
• downloadPodcastEpisode (1.9.0)

Internet radio

• getInternetRadioStations (1.9.0)
• createInternetRadioStation (1.16.0)
• updateInternetRadioStation (1.16.0)
• deleteInternetRadioStation (1.16.0)

Chat

• getChatMessages (1.2.0)
• addChatMessage (1.2.0)

Out of Scope

Video endpoints are currently out of scope- please file an issue if you would like support for them. The deprecated "search" endpoint is unimplemented.

• hls.m3u8 (1.8.0)
• getVideos (1.8.0)
• getVideoInfo (1.14.0)
• getCaptions (1.14.0)
• search (1.0.0)