subsonic

package module
v0.0.0-...-2744002 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 15, 2022 License: GPL-3.0 Imports: 19 Imported by: 3

README

go-subsonic

GoDoc

This is an API client library for Subsonic and Subsonic-compatible music servers. It is tested on Subsonic, Airsonic, and Navidrome.

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)

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)

Jukebox

  • jukeboxControl (1.2.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)

Documentation

Overview

Package subsonic implements an API client library for Subsonic-compatible music streaming servers.

This project handles communication with a remote *sonic server, but does not handle playback of media. The library user should be prepared to do something with the stream of audio in bytes, like decoding and playing that audio on a sound card. The list of API endpoints implemented is available on the project's github page.

The API is divided between functions with no suffix, and functions that have a "2" suffix (or "3" in the case of Search3). Generally, things with "2" on the end are organized by file tags rather than folder structure. This is how you'd expect most music players to work and is recommended. The variants without a suffix organize the library by directory structure; artists are a directory, albums are children of that directory, songs (subsonic.Child) are children of albums. This has some disadvantages: possibly duplicating items with identical directory names, treating songs and albums in much the same fashion, and being more difficult to query consistently.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AlbumID3

type AlbumID3 struct {
	ID        string    `xml:"id,attr"`                                    // Manually added
	Song      []*Child  `xml:"http://subsonic.org/restapi song,omitempty"` // Merged from AlbumWithSongsID3
	Name      string    `xml:"name,attr"`
	Artist    string    `xml:"artist,attr,omitempty"`
	ArtistID  string    `xml:"artistId,attr,omitempty"`
	CoverArt  string    `xml:"coverArt,attr,omitempty"`
	SongCount int       `xml:"songCount,attr"`
	Duration  int       `xml:"duration,attr"`
	PlayCount int64     `xml:"playCount,attr,omitempty"`
	Created   time.Time `xml:"created,attr"`
	Starred   time.Time `xml:"starred,attr,omitempty"`
	Year      int       `xml:"year,attr,omitempty"`
	Genre     string    `xml:"genre,attr,omitempty"`
}

AlbumID3 is an album that's organized by music file tags.

type AlbumInfo

type AlbumInfo struct {
	Notes          string `xml:"http://subsonic.org/restapi notes,omitempty"`
	MusicBrainzID  string `xml:"http://subsonic.org/restapi musicBrainzId,omitempty"`
	LastFmUrl      string `xml:"http://subsonic.org/restapi lastFmUrl,omitempty"`
	SmallImageUrl  string `xml:"http://subsonic.org/restapi smallImageUrl,omitempty"`
	MediumImageUrl string `xml:"http://subsonic.org/restapi mediumImageUrl,omitempty"`
	LargeImageUrl  string `xml:"http://subsonic.org/restapi largeImageUrl,omitempty"`
}

AlbumInfo is a collection of notes and links describing an album.

type Artist

type Artist struct {
	ID             string    `xml:"id,attr"`
	Name           string    `xml:"name,attr"`
	ArtistImageUrl string    `xml:"artistImageUrl,attr,omitempty"`
	Starred        time.Time `xml:"starred,attr,omitempty"`
	UserRating     int       `xml:"userRating,attr,omitempty"`
	AverageRating  float64   `xml:"averageRating,attr,omitempty"`
}

Artist is an artist from the server, organized in the folders pattern.

type ArtistID3

type ArtistID3 struct {
	ID             string      `xml:"id,attr"`                                     // Manually added
	Album          []*AlbumID3 `xml:"http://subsonic.org/restapi album,omitempty"` // Merged with ArtistWithAlbumsID3
	Name           string      `xml:"name,attr"`
	CoverArt       string      `xml:"coverArt,attr,omitempty"`
	ArtistImageUrl string      `xml:"artistImageUrl,attr,omitempty"`
	AlbumCount     int         `xml:"albumCount,attr"`
	Starred        time.Time   `xml:"starred,attr,omitempty"`
}

ArtistID3 is an artist from the server, organized by ID3 tag.

type ArtistInfo

type ArtistInfo struct {
	SimilarArtist  []*Artist `xml:"http://subsonic.org/restapi similarArtist,omitempty"`
	Biography      string    `xml:"http://subsonic.org/restapi biography,omitempty"`
	MusicBrainzID  string    `xml:"http://subsonic.org/restapi musicBrainzId,omitempty"`
	LastFmUrl      string    `xml:"http://subsonic.org/restapi lastFmUrl,omitempty"`
	SmallImageUrl  string    `xml:"http://subsonic.org/restapi smallImageUrl,omitempty"`
	MediumImageUrl string    `xml:"http://subsonic.org/restapi mediumImageUrl,omitempty"`
	LargeImageUrl  string    `xml:"http://subsonic.org/restapi largeImageUrl,omitempty"`
}

ArtistInfo is all auxillary information about an artist from GetArtistInfo.

type ArtistInfo2

type ArtistInfo2 struct {
	SimilarArtist  []*ArtistID3 `xml:"http://subsonic.org/restapi similarArtist,omitempty"`
	Biography      string       `xml:"http://subsonic.org/restapi biography,omitempty"`
	MusicBrainzID  string       `xml:"http://subsonic.org/restapi musicBrainzId,omitempty"`
	LastFmUrl      string       `xml:"http://subsonic.org/restapi lastFmUrl,omitempty"`
	SmallImageUrl  string       `xml:"http://subsonic.org/restapi smallImageUrl,omitempty"`
	MediumImageUrl string       `xml:"http://subsonic.org/restapi mediumImageUrl,omitempty"`
	LargeImageUrl  string       `xml:"http://subsonic.org/restapi largeImageUrl,omitempty"`
}

ArtistInfo2 is all auxillary information about an artist from GetArtistInfo2, with similar artists organized by ID3 tags.

type ArtistsID3

type ArtistsID3 struct {
	Index           []*IndexID3 `xml:"http://subsonic.org/restapi index,omitempty"`
	IgnoredArticles string      `xml:"ignoredArticles,attr"`
}

ArtistsID3 is an index of every artist on the server organized by ID3 tag, from getArtists.

type Bookmark

type Bookmark struct {
	Entry    *Child    `xml:"http://subsonic.org/restapi entry"`
	Position int64     `xml:"position,attr"`
	Username string    `xml:"username,attr"`
	Comment  string    `xml:"comment,attr,omitempty"`
	Created  time.Time `xml:"created,attr"`
	Changed  time.Time `xml:"changed,attr"`
}

func (*Bookmark) MarshalXML

func (t *Bookmark) MarshalXML(e *xml.Encoder, start xml.StartElement) error

func (*Bookmark) UnmarshalXML

func (t *Bookmark) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type ChatMessage

type ChatMessage struct {
	Username string `xml:"username,attr"`
	Time     int64  `xml:"time,attr"`
	Message  string `xml:"message,attr"`
}

type Child

type Child struct {
	ID                    string    `xml:"id,attr"` // Manually added
	Parent                string    `xml:"parent,attr,omitempty"`
	IsDir                 bool      `xml:"isDir,attr"`
	Title                 string    `xml:"title,attr"`
	Album                 string    `xml:"album,attr,omitempty"`
	Artist                string    `xml:"artist,attr,omitempty"`
	Track                 int       `xml:"track,attr,omitempty"`
	Year                  int       `xml:"year,attr,omitempty"`
	Genre                 string    `xml:"genre,attr,omitempty"`
	CoverArt              string    `xml:"coverArt,attr,omitempty"`
	Size                  int64     `xml:"size,attr,omitempty"`
	ContentType           string    `xml:"contentType,attr,omitempty"`
	Suffix                string    `xml:"suffix,attr,omitempty"`
	TranscodedContentType string    `xml:"transcodedContentType,attr,omitempty"`
	TranscodedSuffix      string    `xml:"transcodedSuffix,attr,omitempty"`
	Duration              int       `xml:"duration,attr,omitempty"`
	BitRate               int       `xml:"bitRate,attr,omitempty"`
	Path                  string    `xml:"path,attr,omitempty"`
	IsVideo               bool      `xml:"isVideo,attr,omitempty"`
	UserRating            int       `xml:"userRating,attr,omitempty"`
	AverageRating         float64   `xml:"averageRating,attr,omitempty"`
	PlayCount             int64     `xml:"playCount,attr,omitempty"`
	DiscNumber            int       `xml:"discNumber,attr,omitempty"`
	Created               time.Time `xml:"created,attr,omitempty"`
	Starred               time.Time `xml:"starred,attr,omitempty"`
	AlbumID               string    `xml:"albumId,attr,omitempty"`
	ArtistID              string    `xml:"artistId,attr,omitempty"`
	Type                  string    `xml:"type,attr,omitempty"` // May be one of music, podcast, audiobook, video
	BookmarkPosition      int64     `xml:"bookmarkPosition,attr,omitempty"`
	OriginalWidth         int       `xml:"originalWidth,attr,omitempty"`
	OriginalHeight        int       `xml:"originalHeight,attr,omitempty"`
}

Child is a song, or a generic entry in the hierarchical directory structure of the database. You can tell if Child is used as a song contextually based on what it was returned by, or if the IsDir boolean was set to true.

type Client

type Client struct {
	Client       *http.Client
	BaseUrl      string
	User         string
	ClientName   string
	PasswordAuth bool
	// contains filtered or unexported fields
}

func (*Client) Authenticate

func (s *Client) Authenticate(password string) error

Authenticate authenticates the current user with a provided password. The password is salted before transmission and requires Subsonic > 1.13.0.

func (*Client) ChangePassword

func (c *Client) ChangePassword(username, password string) error

ChangePassword changes the password of an existing Subsonic user, using the following parameters. You can only change your own password unless you have admin privileges.

func (*Client) CreatePlaylist

func (s *Client) CreatePlaylist(parameters map[string]string) error

CreatePlaylist creates (or updates) a playlist.

Optional Parameters:

songId:     ID of a song in the playlist. Use one songId parameter for each song in the playlist.

Mutually Exclusive Parameters:

playlistId: The playlist ID.
name:       The human-readable name of the playlist.

This returns a Playlist object in Subsonic > 1.14.0, so it cannot consistently return a *Playlist

func (*Client) CreateUser

func (c *Client) CreateUser(username, password, email string, parameters map[string]string) error

CreateUser creates a new Subsonic user.

Optional Parameters Default Description

ldapAuthenticated		false		Whether the user is authenicated in LDAP.
adminRole						false		Whether the user is administrator.
settingsRole					true		Whether the user is allowed to change personal settings and password.
streamRole						true		Whether the user is allowed to play files.
jukeboxRole					false		Whether the user is allowed to play files in jukebox mode.
downloadRole					false		Whether the user is allowed to download files.
uploadRole						false		Whether the user is allowed to upload files.
playlistRole					false		Whether the user is allowed to create and delete playlists. Since 1.8.0, changing this role has no effect.
coverArtRole					false		Whether the user is allowed to change cover art and tags.
commentRole					false		Whether the user is allowed to create and edit comments and ratings.
podcastRole					false		Whether the user is allowed to administrate Podcasts.
shareRole						false		(Since 1.8.0) Whether the user is allowed to share files with anyone.
videoConversionRole	false		(Since 1.15.0) Whether the user is allowed to start video conversions.
musicFolderId				All 		(Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder.

func (*Client) DeletePlaylist

func (s *Client) DeletePlaylist(playlistId string) error

DeletePlaylist deletes a saved playlist.

func (*Client) DeleteUser

func (s *Client) DeleteUser(username string) error

DeleteUser deletes an existing Subsonic user.

func (*Client) Download

func (s *Client) Download(id string) (io.Reader, error)

Download returns a given media file. Similar to stream, but this method returns the original media data without transcoding or downsampling.

func (*Client) Get

func (s *Client) Get(endpoint string, params map[string]string) (*Response, error)

Get is a convenience interface to issue a GET request and parse the response body (99% of Subsonic API calls)

func (*Client) GetAlbum

func (s *Client) GetAlbum(id string) (*AlbumID3, error)

GetAlbum returns an Album by ID.

func (*Client) GetAlbumInfo

func (s *Client) GetAlbumInfo(id string) (*AlbumInfo, error)

GetAlbumInfo returns album notes, image data, etc using data from last.fm. This accepts both album and song IDs.

func (*Client) GetAlbumInfo2

func (s *Client) GetAlbumInfo2(id string) (*AlbumInfo, error)

GetAlbumInfo2 returns the same data as GetAlbumInfo, but organized by id3 tag. It only accepts album IDs.

func (*Client) GetAlbumList

func (s *Client) GetAlbumList(listType string, parameters map[string]string) ([]*Child, error)

GetAlbumList returns a list of random, newest, highest rated etc. albums. Similar to the album lists on the home page of the Subsonic web interface.

Optional Parameters:

size:           The number of albums to return. Max 500, default 10.
offset:         The list offset. Useful if you for example want to page through the list of newest albums.
fromYear:       The first year in the range. If fromYear > toYear a reverse chronological list is returned.
toYear:         The last year in the range.
genre:          The name of the genre, e.g., "Rock".
musicFolderId:  (Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders.

toYear and fromYear are required parameters when type == "byYear". genre is a required parameter when type == "byGenre".

func (*Client) GetAlbumList2

func (s *Client) GetAlbumList2(listType string, parameters map[string]string) ([]*AlbumID3, error)

GetAlbumList2 returns a list of albums like GetAlbumList, but organized according to id3 tags.

Optional Parameters:

size:           The number of albums to return. Max 500, default 10.
offset:         The list offset. Useful if you for example want to page through the list of newest albums.
fromYear:       The first year in the range. If fromYear > toYear a reverse chronological list is returned.
toYear:         The last year in the range.
genre:          The name of the genre, e.g., "Rock".
musicFolderId:  (Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders.

toYear and fromYear are required parameters when type == "byYear". genre is a required parameter when type == "byGenre".

func (*Client) GetArtist

func (s *Client) GetArtist(id string) (*ArtistID3, error)

GetAlbum returns an Artist by ID.

func (*Client) GetArtistInfo

func (s *Client) GetArtistInfo(id string, parameters map[string]string) (*ArtistInfo, error)

GetArtistInfo returns biography, image links, and similar artists from last.fm.

Optional Parameters:

count:             Max number of similar artists to return.
includeNotPresent: Whether to return artists that are not present in the media library.

func (*Client) GetArtistInfo2

func (s *Client) GetArtistInfo2(id string, parameters map[string]string) (*ArtistInfo2, error)

GetArtistInfo2 returns biography, image links, and similar artists like GetArtistInfo, but using id3 tags.

Optional Parameters:

count:             Max number of similar artists to return.
includeNotPresent: Whether to return artists that are not present in the media library.

func (*Client) GetArtists

func (s *Client) GetArtists(parameters map[string]string) (*ArtistsID3, error)

GetArtists returns all artists in the server.

Optional Parameters:

musicFolderId:  Only return songs in the music folder with the given ID. See getMusicFolders.

func (*Client) GetAvatar

func (s *Client) GetAvatar(username string) (image.Image, error)

GetAvatar returns the avatar (personal image) for a user.

func (*Client) GetCoverArt

func (s *Client) GetCoverArt(id string, parameters map[string]string) (image.Image, error)

GetCoverArt returns a cover art image for a song, album, or artist.

Optional Parameters:

size:            If specified, scale image to this size.

func (*Client) GetGenres

func (s *Client) GetGenres() ([]*Genre, error)

GetGenres returns all genres in the server.

func (*Client) GetIndexes

func (s *Client) GetIndexes(parameters map[string]string) (*Indexes, error)

GetIndexes returns the index of entries by letter/number.

Optional Parameters:

musicFolderId:    Only return songs in the music folder with the given ID. See getMusicFolders.
ifModifiedSince:  If specified, only return a result if the artist collection has changed since the given time (in milliseconds since 1 Jan 1970).

func (*Client) GetLicense

func (s *Client) GetLicense() (*License, error)

GetLicense retrieves details about the software license. Subsonic requires a license after a 30-day trial, compatible applications have a perpetually valid license.

func (*Client) GetMusicDirectory

func (s *Client) GetMusicDirectory(id string) (*Directory, error)

GetMusicDirectory returns a listing of all files in a music directory. Typically used to get list of albums for an artist, or list of songs for an album. The ID can be an album, song, or artist - anything considered within the directory hierarchy of Subsonic.

func (*Client) GetMusicFolders

func (s *Client) GetMusicFolders() ([]*MusicFolder, error)

GetMusicFolders returns all configured top-level music folders.

func (*Client) GetNowPlaying

func (s *Client) GetNowPlaying() ([]*NowPlayingEntry, error)

GetNowPlaying returns what is currently being played by all users.

func (*Client) GetPlaylist

func (s *Client) GetPlaylist(id string) (*Playlist, error)

GetPlaylist returns a listing of files in a saved playlist.

func (*Client) GetPlaylists

func (s *Client) GetPlaylists(parameters map[string]string) ([]*Playlist, error)

GetPlaylists returns all playlists a user is allowed to play.

Optional Parameters:

user: get playlists visible to this username rather than the current user. Must have admin permission.

func (*Client) GetRandomSongs

func (s *Client) GetRandomSongs(parameters map[string]string) ([]*Child, error)

GetRandomSongs returns a randomly selected set of songs limited by the optional parameters.

Optional Parameters:

size:           The maximum number of songs to return. Max 500, default 10.
genre:          Only returns songs belonging to this genre.
fromYear:       Only return songs published after or in this year.
toYear:         Only return songs published before or in this year.
musicFolderId:  Only return songs in the music folder with the given ID. See getMusicFolders.

func (*Client) GetScanStatus

func (c *Client) GetScanStatus() (*ScanStatus, error)

GetScanStatus returns the current status for media library scanning.

func (*Client) GetSimilarSongs

func (s *Client) GetSimilarSongs(id string, parameters map[string]string) ([]*Child, error)

GetSimilarSongs finds similar songs to an album, track, or artist. This is mostly used for radio features. This accepts artist, album, or song IDs.

Optional Parameters:

count: Number of songs to return

func (*Client) GetSimilarSongs2

func (s *Client) GetSimilarSongs2(id string, parameters map[string]string) ([]*Child, error)

GetSimilarSongs2 finds similar songs like GetSimilarSongs, but using id3 tags.

Optional Parameters:

count: Number of songs to return

func (*Client) GetSong

func (s *Client) GetSong(id string) (*Child, error)

GetSong returns a Song by ID.

func (*Client) GetSongsByGenre

func (s *Client) GetSongsByGenre(name string, parameters map[string]string) ([]*Child, error)

GetSongsByGenre returns songs in a given genre name.

Optional Parameters:

count:          The maximum number of songs to return. Max 500, default 10.
offset:         The offset. Useful if you want to page through the songs in a genre.
musicFolderId:  Only return songs in the music folder with the given ID. See getMusicFolders.

func (*Client) GetStarred

func (s *Client) GetStarred(parameters map[string]string) (*Starred, error)

GetStarred returns starred albums, artists, and songs.

Optional Parameters:

musicFolderId:  Only return songs in the music folder with the given ID. See getMusicFolders.

func (*Client) GetStarred2

func (s *Client) GetStarred2(parameters map[string]string) (*Starred2, error)

GetStarred2 returns starred albums, artists, and songs arranged by id3 tag.

Optional Parameters:

musicFolderId:  Only return songs in the music folder with the given ID. See getMusicFolders.

func (*Client) GetTopSongs

func (s *Client) GetTopSongs(name string, parameters map[string]string) ([]*Child, error)

GetTopSongs returns the top songs for a given artist by name.

Optional Parameters:

count: Number of songs to return

func (*Client) GetUser

func (c *Client) GetUser(username string) (*User, error)

GetUser gets details about a given user, including which authorization roles and folder access it has. Can be used to enable/disable certain features in the client, such as jukebox control.

func (*Client) GetUsers

func (c *Client) GetUsers() ([]*User, error)

GetUsers gets details about all users, including which authorization roles and folder access they have. Only users with admin privileges are allowed to call this method.

func (*Client) Ping

func (s *Client) Ping() bool

Ping is used to test connectivity with the server. It returns true if the server is up.

func (*Client) Request

func (s *Client) Request(method string, endpoint string, params url.Values) (*http.Response, error)

Request performs a HTTP request against the Subsonic server as the current user.

func (*Client) Scrobble

func (s *Client) Scrobble(id string, parameters map[string]string) error

Scrobble submits a song to last.fm if the user has configured their credentials to do so.

Optional Parameters:

time:            (Since 1.8.0) The time (in milliseconds since 1 Jan 1970) at which the song was listened to.
submission:      Whether this is a "submission" (true) or a "now playing" (false) notification. Defaults to a submission.

func (*Client) Search2

func (s *Client) Search2(query string, parameters map[string]string) (*SearchResult2, error)

Search2 returns albums, artists and songs matching the given search criteria. Supports paging through the result.

Optional Parameters:

artistCount:     Maximum number of artists to return. (Default 20)
artistOffset:    Search result offset for artists. Used for paging.
albumCount:      Maximum number of albums to return. (Default 20)
albumOffset:     Search result offset for albums. Used for paging.
songCount:       Maximum number of songs to return. (Default 20)
songOffset:      Search result offset for songs. Used for paging.
musicFolderId:   (Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders.

func (*Client) Search3

func (s *Client) Search3(query string, parameters map[string]string) (*SearchResult3, error)

Search3 returns albums, artists and songs matching the given search criteria like Search2, but organized according to id3 tags. Optional Parameters:

artistCount:     Maximum number of artists to return. (Default 20)
artistOffset:    Search result offset for artists. Used for paging.
albumCount:      Maximum number of albums to return. (Default 20)
albumOffset:     Search result offset for albums. Used for paging.
songCount:       Maximum number of songs to return. (Default 20)
songOffset:      Search result offset for songs. Used for paging.
musicFolderId:   (Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders.

func (*Client) SetRating

func (s *Client) SetRating(id string, rating int) error

SetRating sets the rating of a music file.

func (*Client) Star

func (s *Client) Star(parameters StarParameters) error

Star adds the star annotation to songs, albums, and artists.

func (*Client) StartScan

func (c *Client) StartScan() (*ScanStatus, error)

StartScan initiates a rescan of the media libraries.

func (*Client) Stream

func (s *Client) Stream(id string, parameters map[string]string) (io.Reader, error)

Stream returns the contents of a song, optionally transcoded, from the server.

Optional Parameters:

maxBitRate:             (Since 1.2.0) If specified, the server will attempt to limit the bitrate to this value, in kilobits per second. If set to zero, no limit is imposed.
format:                 (Since 1.6.0) Specifies the preferred target format (e.g., "mp3" or "flv") in case there are multiple applicable transcodings.  Starting with 1.9.0 you can use the special value "raw" to disable transcoding.
timeOffset:             Only applicable to video streaming. If specified, start streaming at the given offset (in seconds) into the video. Typically used to implement video skipping.
size:                   (Since 1.6.0) Only applicable to video streaming. Requested video size specified as WxH, for instance "640x480".
estimateContentLength:  (Since 1.8.0). If set to "true", the Content-Length HTTP header will be set to an estimated value for transcoded or downsampled media.
converted:              (Since 1.14.0) Only applicable to video streaming. Subsonic can optimize videos for streaming by converting them to MP4. If a conversion exists for the video in question, then setting this parameter to "true" will cause the converted video to be returned instead of the original.

func (*Client) Unstar

func (s *Client) Unstar(parameters StarParameters) error

Unstar removes the star annotation from songs, albums, and artists.

func (*Client) UpdatePlaylist

func (s *Client) UpdatePlaylist(playlistId string, parameters map[string]string) error

UpdatePlaylist updates a playlist. Only the owner of a playlist is allowed to update it.

Optional Parameters:

name:              The human-readable name of the playlist.
comment:           The playlist comment.
public:            true if the playlist should be visible to all users, false otherwise.
songIdToAdd:       Add this song with this ID to the playlist. Multiple parameters allowed.
songIndexToRemove: Remove the song at this position in the playlist. Multiple parameters allowed.

func (*Client) UpdateUser

func (c *Client) UpdateUser(username string, parameters map[string]string) error

UpdateUser modifies an existing Subsonic user.

Optional Parameters:

password							The password of the user, either in clear text of hex-encoded.
email								The email address of the user.
ldapAuthenticated		Whether the user is authenicated in LDAP.
adminRole						Whether the user is administrator.
settingsRole					Whether the user is allowed to change personal settings and password.
streamRole						Whether the user is allowed to play files.
jukeboxRole					Whether the user is allowed to play files in jukebox mode.
downloadRole					Whether the user is allowed to download files.
uploadRole						Whether the user is allowed to upload files.
coverArtRole					Whether the user is allowed to change cover art and tags.
commentRole					Whether the user is allowed to create and edit comments and ratings.
podcastRole					Whether the user is allowed to administrate Podcasts.
shareRole						(Since 1.8.0) Whether the user is allowed to share files with anyone.
videoConversionRole	(Since 1.15.0) Whether the user is allowed to start video conversions.
musicFolderId				(Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder.
maxBitRate						(Since 1.13.0) The maximum bit rate (in Kbps) for the user. Audio streams of higher bit rates are automatically downsampled to this bit rate. Legal values: 0 (no limit), 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320.

type Directory

type Directory struct {
	ID            string    `xml:"id,attr"` // Manually added
	Child         []*Child  `xml:"http://subsonic.org/restapi child,omitempty"`
	Parent        string    `xml:"parent,attr,omitempty"`
	Name          string    `xml:"name,attr"`
	Starred       time.Time `xml:"starred,attr,omitempty"`
	UserRating    int       `xml:"userRating,attr,omitempty"`
	AverageRating float64   `xml:"averageRating,attr,omitempty"`
	PlayCount     int64     `xml:"playCount,attr,omitempty"`
}

Directory is an entry in the hierarchical folder structure organization of the server database.

type Error

type Error struct {
	Code    int    `xml:"code,attr"`
	Message string `xml:"message,attr,omitempty"`
}

type Genre

type Genre struct {
	Name       string `xml:",chardata"` // Added manually
	SongCount  int    `xml:"songCount,attr"`
	AlbumCount int    `xml:"albumCount,attr"`
}

Genre is a style tag for a collection of songs and albums.

type Index

type Index struct {
	Artist []*Artist `xml:"http://subsonic.org/restapi artist,omitempty"`
	Name   string    `xml:"name,attr"`
}

Index is a collection of artists that begin with the same first letter, along with that letter or category.

type IndexID3

type IndexID3 struct {
	Artist []*ArtistID3 `xml:"http://subsonic.org/restapi artist,omitempty"`
	Name   string       `xml:"name,attr"`
}

Index is a collection of artists by ID3 tag that begin with the same first letter, along with that letter or category.

type Indexes

type Indexes struct {
	Shortcut        []*Artist `xml:"http://subsonic.org/restapi shortcut,omitempty"`
	Index           []*Index  `xml:"http://subsonic.org/restapi index,omitempty"`
	Child           []*Child  `xml:"http://subsonic.org/restapi child,omitempty"`
	LastModified    int64     `xml:"lastModified,attr"`
	IgnoredArticles string    `xml:"ignoredArticles,attr"`
}

Indexes is the full index of the database, returned by getIndex. It contains some Index structs for each letter of the DB, plus Child entries for individual tracks.

type InternetRadioStation

type InternetRadioStation struct {
	Name        string `xml:"name,attr"`
	StreamUrl   string `xml:"streamUrl,attr"`
	HomePageUrl string `xml:"homePageUrl,attr,omitempty"`
}

type JukeboxPlaylist

type JukeboxPlaylist struct {
	Entry        []*Child `xml:"http://subsonic.org/restapi entry,omitempty"`
	CurrentIndex int      `xml:"currentIndex,attr"`
	Playing      bool     `xml:"playing,attr"`
	Gain         float32  `xml:"gain,attr"`
	Position     int      `xml:"position,attr,omitempty"`
}

type JukeboxStatus

type JukeboxStatus struct {
	CurrentIndex int     `xml:"currentIndex,attr"`
	Playing      bool    `xml:"playing,attr"`
	Gain         float32 `xml:"gain,attr"`
	Position     int     `xml:"position,attr,omitempty"`
}

type License

type License struct {
	Valid          bool      `xml:"valid,attr"`
	Email          string    `xml:"email,attr,omitempty"`
	LicenseExpires time.Time `xml:"licenseExpires,attr,omitempty"`
	TrialExpires   time.Time `xml:"trialExpires,attr,omitempty"`
}

License contains information about the Subsonic server's license validity and contact information in the case of a trial subscription.

type Lyrics

type Lyrics struct {
	Artist string `xml:"artist,attr,omitempty"`
	Title  string `xml:"title,attr,omitempty"`
}

type MusicFolder

type MusicFolder struct {
	ID   string `xml:"id,attr"`
	Name string `xml:"name,attr,omitempty"`
}

MusicFolder is a representation of a source of music files added to the server. It is identified primarily by the numeric ID.

type NowPlayingEntry

type NowPlayingEntry struct {
	Username              string    `xml:"username,attr"`
	MinutesAgo            int       `xml:"minutesAgo,attr"`
	PlayerID              int       `xml:"playerId,attr"`
	PlayerName            string    `xml:"playerName,attr,omitempty"`
	Parent                string    `xml:"parent,attr,omitempty"`
	IsDir                 bool      `xml:"isDir,attr"`
	Title                 string    `xml:"title,attr"`
	Album                 string    `xml:"album,attr,omitempty"`
	Artist                string    `xml:"artist,attr,omitempty"`
	Track                 int       `xml:"track,attr,omitempty"`
	Year                  int       `xml:"year,attr,omitempty"`
	Genre                 string    `xml:"genre,attr,omitempty"`
	CoverArt              string    `xml:"coverArt,attr,omitempty"`
	Size                  int64     `xml:"size,attr,omitempty"`
	ContentType           string    `xml:"contentType,attr,omitempty"`
	Suffix                string    `xml:"suffix,attr,omitempty"`
	TranscodedContentType string    `xml:"transcodedContentType,attr,omitempty"`
	TranscodedSuffix      string    `xml:"transcodedSuffix,attr,omitempty"`
	Duration              int       `xml:"duration,attr,omitempty"`
	BitRate               int       `xml:"bitRate,attr,omitempty"`
	Path                  string    `xml:"path,attr,omitempty"`
	IsVideo               bool      `xml:"isVideo,attr,omitempty"`
	UserRating            int       `xml:"userRating,attr,omitempty"`
	AverageRating         float64   `xml:"averageRating,attr,omitempty"`
	PlayCount             int64     `xml:"playCount,attr,omitempty"`
	DiscNumber            int       `xml:"discNumber,attr,omitempty"`
	Created               time.Time `xml:"created,attr,omitempty"`
	Starred               time.Time `xml:"starred,attr,omitempty"`
	AlbumID               string    `xml:"albumId,attr,omitempty"`
	ArtistID              string    `xml:"artistId,attr,omitempty"`
	Type                  string    `xml:"type,attr,omitempty"` // May be one of music, podcast, audiobook, video
	BookmarkPosition      int64     `xml:"bookmarkPosition,attr,omitempty"`
	OriginalWidth         int       `xml:"originalWidth,attr,omitempty"`
	OriginalHeight        int       `xml:"originalHeight,attr,omitempty"`
}

NowPlayingEntry is one individual stream coming from the server along with information about who was streaming it.

type PlayQueue

type PlayQueue struct {
	Entry     []*Child  `xml:"http://subsonic.org/restapi entry,omitempty"`
	Current   int       `xml:"current,attr,omitempty"`
	Position  int64     `xml:"position,attr,omitempty"`
	Username  string    `xml:"username,attr"`
	Changed   time.Time `xml:"changed,attr"`
	ChangedBy string    `xml:"changedBy,attr"`
}

func (*PlayQueue) MarshalXML

func (t *PlayQueue) MarshalXML(e *xml.Encoder, start xml.StartElement) error

func (*PlayQueue) UnmarshalXML

func (t *PlayQueue) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type Playlist

type Playlist struct {
	ID          string    `xml:"id,attr"`                                     // Added manually
	Entry       []*Child  `xml:"http://subsonic.org/restapi entry,omitempty"` // Merged from PlaylistWithSongs
	AllowedUser []string  `xml:"http://subsonic.org/restapi allowedUser,omitempty"`
	Name        string    `xml:"name,attr"`
	Comment     string    `xml:"comment,attr,omitempty"`
	Owner       string    `xml:"owner,attr,omitempty"`
	Public      bool      `xml:"public,attr,omitempty"`
	SongCount   int       `xml:"songCount,attr"`
	Duration    int       `xml:"duration,attr"`
	Created     time.Time `xml:"created,attr"`
	Changed     time.Time `xml:"changed,attr"`
	CoverArt    string    `xml:"coverArt,attr,omitempty"`
}

Playlist is a collection of songs with metadata like a name, comment, and information about the total duration of the playlist.

type PodcastChannel

type PodcastChannel struct {
	Episode          []*PodcastEpisode `xml:"http://subsonic.org/restapi episode,omitempty"`
	Url              string            `xml:"url,attr"`
	Title            string            `xml:"title,attr,omitempty"`
	Description      string            `xml:"description,attr,omitempty"`
	CoverArt         string            `xml:"coverArt,attr,omitempty"`
	OriginalImageUrl string            `xml:"originalImageUrl,attr,omitempty"`
	Status           string            `xml:"status,attr"` // May be one of new, downloading, completed, error, deleted, skipped
	ErrorMessage     string            `xml:"errorMessage,attr,omitempty"`
}

type PodcastEpisode

type PodcastEpisode struct {
	StreamID              string    `xml:"streamId,attr,omitempty"`
	ChannelID             string    `xml:"channelId,attr"`
	Description           string    `xml:"description,attr,omitempty"`
	Status                string    `xml:"status,attr"` // May be one of new, downloading, completed, error, deleted, skipped
	PublishDate           time.Time `xml:"publishDate,attr,omitempty"`
	Parent                string    `xml:"parent,attr,omitempty"`
	IsDir                 bool      `xml:"isDir,attr"`
	Title                 string    `xml:"title,attr"`
	Album                 string    `xml:"album,attr,omitempty"`
	Artist                string    `xml:"artist,attr,omitempty"`
	Track                 int       `xml:"track,attr,omitempty"`
	Year                  int       `xml:"year,attr,omitempty"`
	Genre                 string    `xml:"genre,attr,omitempty"`
	CoverArt              string    `xml:"coverArt,attr,omitempty"`
	Size                  int64     `xml:"size,attr,omitempty"`
	ContentType           string    `xml:"contentType,attr,omitempty"`
	Suffix                string    `xml:"suffix,attr,omitempty"`
	TranscodedContentType string    `xml:"transcodedContentType,attr,omitempty"`
	TranscodedSuffix      string    `xml:"transcodedSuffix,attr,omitempty"`
	Duration              int       `xml:"duration,attr,omitempty"`
	BitRate               int       `xml:"bitRate,attr,omitempty"`
	Path                  string    `xml:"path,attr,omitempty"`
	IsVideo               bool      `xml:"isVideo,attr,omitempty"`
	UserRating            int       `xml:"userRating,attr,omitempty"`
	AverageRating         float64   `xml:"averageRating,attr,omitempty"`
	PlayCount             int64     `xml:"playCount,attr,omitempty"`
	DiscNumber            int       `xml:"discNumber,attr,omitempty"`
	Created               time.Time `xml:"created,attr,omitempty"`
	Starred               time.Time `xml:"starred,attr,omitempty"`
	AlbumID               string    `xml:"albumId,attr,omitempty"`
	ArtistID              string    `xml:"artistId,attr,omitempty"`
	Type                  string    `xml:"type,attr,omitempty"` // May be one of music, podcast, audiobook, video
	BookmarkPosition      int64     `xml:"bookmarkPosition,attr,omitempty"`
	OriginalWidth         int       `xml:"originalWidth,attr,omitempty"`
	OriginalHeight        int       `xml:"originalHeight,attr,omitempty"`
}

func (*PodcastEpisode) MarshalXML

func (t *PodcastEpisode) MarshalXML(e *xml.Encoder, start xml.StartElement) error

func (*PodcastEpisode) UnmarshalXML

func (t *PodcastEpisode) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type Response

type Response struct {
	License               *License               `xml:"http://subsonic.org/restapi license"`
	MusicFolders          *musicFolders          `xml:"http://subsonic.org/restapi musicFolders"`
	Indexes               *Indexes               `xml:"http://subsonic.org/restapi indexes"`
	Directory             *Directory             `xml:"http://subsonic.org/restapi directory"`
	Genres                *genres                `xml:"http://subsonic.org/restapi genres"`
	Artists               *ArtistsID3            `xml:"http://subsonic.org/restapi artists"`
	Artist                *ArtistID3             `xml:"http://subsonic.org/restapi artist"`
	Album                 *AlbumID3              `xml:"http://subsonic.org/restapi album"`
	Song                  *Child                 `xml:"http://subsonic.org/restapi song"`
	NowPlaying            *nowPlaying            `xml:"http://subsonic.org/restapi nowPlaying"`
	SearchResult2         *SearchResult2         `xml:"http://subsonic.org/restapi searchResult2"`
	SearchResult3         *SearchResult3         `xml:"http://subsonic.org/restapi searchResult3"`
	Playlists             *playlists             `xml:"http://subsonic.org/restapi playlists"`
	Playlist              *Playlist              `xml:"http://subsonic.org/restapi playlist"`
	JukeboxStatus         *JukeboxStatus         `xml:"http://subsonic.org/restapi jukeboxStatus"`
	JukeboxPlaylist       *JukeboxPlaylist       `xml:"http://subsonic.org/restapi jukeboxPlaylist"`
	Users                 *users                 `xml:"http://subsonic.org/restapi users"`
	User                  *User                  `xml:"http://subsonic.org/restapi user"`
	ChatMessages          *chatMessages          `xml:"http://subsonic.org/restapi chatMessages"`
	AlbumList             *albumList             `xml:"http://subsonic.org/restapi albumList"`
	AlbumList2            *albumList2            `xml:"http://subsonic.org/restapi albumList2"`
	RandomSongs           *songs                 `xml:"http://subsonic.org/restapi randomSongs"`
	SongsByGenre          *songs                 `xml:"http://subsonic.org/restapi songsByGenre"`
	Lyrics                *Lyrics                `xml:"http://subsonic.org/restapi lyrics"`
	Podcasts              *podcasts              `xml:"http://subsonic.org/restapi podcasts"`
	NewestPodcasts        *newestPodcasts        `xml:"http://subsonic.org/restapi newestPodcasts"`
	InternetRadioStations *internetRadioStations `xml:"http://subsonic.org/restapi internetRadioStations"`
	Bookmarks             *bookmarks             `xml:"http://subsonic.org/restapi bookmarks"`
	PlayQueue             *PlayQueue             `xml:"http://subsonic.org/restapi playQueue"`
	Shares                *shares                `xml:"http://subsonic.org/restapi shares"`
	Starred               *Starred               `xml:"http://subsonic.org/restapi starred"`
	Starred2              *Starred2              `xml:"http://subsonic.org/restapi starred2"`
	AlbumInfo             *AlbumInfo             `xml:"http://subsonic.org/restapi albumInfo"`
	ArtistInfo            *ArtistInfo            `xml:"http://subsonic.org/restapi artistInfo"`
	ArtistInfo2           *ArtistInfo2           `xml:"http://subsonic.org/restapi artistInfo2"`
	SimilarSongs          *similarSongs          `xml:"http://subsonic.org/restapi similarSongs"`
	SimilarSongs2         *similarSongs2         `xml:"http://subsonic.org/restapi similarSongs2"`
	TopSongs              *topSongs              `xml:"http://subsonic.org/restapi topSongs"`
	ScanStatus            *ScanStatus            `xml:"http://subsonic.org/restapi scanStatus"`
	Error                 *Error                 `xml:"http://subsonic.org/restapi error"`
	Status                string                 `xml:"status,attr"`  // May be one of ok, failed
	Version               string                 `xml:"version,attr"` // Must match the pattern \d+\.\d+\.\d+
}

Response is the main target for unmarshalling data from the API - everything within the "subsonic-response" key

type ScanStatus

type ScanStatus struct {
	Scanning bool  `xml:"scanning,attr"`
	Count    int64 `xml:"count,attr,omitempty"`
}

type SearchResult2

type SearchResult2 struct {
	Artist []*Artist `xml:"http://subsonic.org/restapi artist,omitempty"`
	Album  []*Child  `xml:"http://subsonic.org/restapi album,omitempty"`
	Song   []*Child  `xml:"http://subsonic.org/restapi song,omitempty"`
}

SearchResult2 is a collection of songs, albums, and artists related to a query.

type SearchResult3

type SearchResult3 struct {
	Artist []*ArtistID3 `xml:"http://subsonic.org/restapi artist,omitempty"`
	Album  []*AlbumID3  `xml:"http://subsonic.org/restapi album,omitempty"`
	Song   []*Child     `xml:"http://subsonic.org/restapi song,omitempty"`
}

SearchResult3 is a collection of songs, albums, and artists related to a query.

type Share

type Share struct {
	Entry       []*Child  `xml:"http://subsonic.org/restapi entry,omitempty"`
	Url         string    `xml:"url,attr"`
	Description string    `xml:"description,attr,omitempty"`
	Username    string    `xml:"username,attr"`
	Created     time.Time `xml:"created,attr"`
	Expires     time.Time `xml:"expires,attr,omitempty"`
	LastVisited time.Time `xml:"lastVisited,attr,omitempty"`
	VisitCount  int       `xml:"visitCount,attr"`
}

func (*Share) MarshalXML

func (t *Share) MarshalXML(e *xml.Encoder, start xml.StartElement) error

func (*Share) UnmarshalXML

func (t *Share) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

type StarParameters

type StarParameters struct {
	SongIDs   []string
	AlbumIDs  []string
	ArtistIDs []string
}

StarParameters are used to identify songs, albums, and artists (or some subset of those) at the same time. subsonic.Star and subsonic.Unstar both use StarParameters to identify things to star.

type Starred

type Starred struct {
	Artist []*Artist `xml:"http://subsonic.org/restapi artist,omitempty"`
	Album  []*Child  `xml:"http://subsonic.org/restapi album,omitempty"`
	Song   []*Child  `xml:"http://subsonic.org/restapi song,omitempty"`
}

Starred is a collection of songs, albums, and artists annotated by a user as starred.

type Starred2

type Starred2 struct {
	Artist []*ArtistID3 `xml:"http://subsonic.org/restapi artist,omitempty"`
	Album  []*AlbumID3  `xml:"http://subsonic.org/restapi album,omitempty"`
	Song   []*Child     `xml:"http://subsonic.org/restapi song,omitempty"`
}

Starred2 is a collection of songs, albums, and artists organized by ID3 tags annotated by a user as starred.

type User

type User struct {
	Folder              []int     `xml:"http://subsonic.org/restapi folder,omitempty"`
	Username            string    `xml:"username,attr"`
	Email               string    `xml:"email,attr,omitempty"`
	ScrobblingEnabled   bool      `xml:"scrobblingEnabled,attr"`
	MaxBitRate          int       `xml:"maxBitRate,attr,omitempty"`
	AdminRole           bool      `xml:"adminRole,attr"`
	SettingsRole        bool      `xml:"settingsRole,attr"`
	DownloadRole        bool      `xml:"downloadRole,attr"`
	UploadRole          bool      `xml:"uploadRole,attr"`
	PlaylistRole        bool      `xml:"playlistRole,attr"`
	CoverArtRole        bool      `xml:"coverArtRole,attr"`
	CommentRole         bool      `xml:"commentRole,attr"`
	PodcastRole         bool      `xml:"podcastRole,attr"`
	StreamRole          bool      `xml:"streamRole,attr"`
	JukeboxRole         bool      `xml:"jukeboxRole,attr"`
	ShareRole           bool      `xml:"shareRole,attr"`
	VideoConversionRole bool      `xml:"videoConversionRole,attr"`
	AvatarLastChanged   time.Time `xml:"avatarLastChanged,attr,omitempty"`
}

func (*User) MarshalXML

func (t *User) MarshalXML(e *xml.Encoder, start xml.StartElement) error

func (*User) UnmarshalXML

func (t *User) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL