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
- Variables
- type AlbumID3
- type AlbumInfo
- type Artist
- type ArtistID3
- type ArtistInfo
- type ArtistInfo2
- type ArtistsID3
- type Bookmark
- type ChatMessage
- type Child
- type Client
- func (s *Client) Authenticate(password string) error
- func (c *Client) ChangePassword(username, password string) error
- func (s *Client) CreatePlaylist(parameters map[string]string) error
- func (s *Client) CreatePlaylistWithTracks(trackIDs []string, parameters map[string]string) error
- func (c *Client) CreateShare(id string, parameters map[string]string) (*Share, error)
- func (c *Client) CreateUser(username, password, email string, parameters map[string]string) error
- func (s *Client) DeletePlaylist(playlistId string) error
- func (c *Client) DeleteShare(id string) error
- func (s *Client) DeleteUser(username string) error
- func (s *Client) Download(id string) (io.ReadCloser, error)
- func (s *Client) Get(endpoint string, params map[string]string) (*Response, error)
- func (s *Client) GetAlbum(id string) (*AlbumID3, error)
- func (s *Client) GetAlbumInfo(id string) (*AlbumInfo, error)
- func (s *Client) GetAlbumInfo2(id string) (*AlbumInfo, error)
- func (s *Client) GetAlbumList(listType string, parameters map[string]string) ([]*Child, error)
- func (s *Client) GetAlbumList2(listType string, parameters map[string]string) ([]*AlbumID3, error)
- func (s *Client) GetArtist(id string) (*ArtistID3, error)
- func (s *Client) GetArtistInfo(id string, parameters map[string]string) (*ArtistInfo, error)
- func (s *Client) GetArtistInfo2(id string, parameters map[string]string) (*ArtistInfo2, error)
- func (s *Client) GetArtists(parameters map[string]string) (*ArtistsID3, error)
- func (s *Client) GetAvatar(username string) (image.Image, error)
- func (s *Client) GetCoverArt(id string, parameters map[string]string) (image.Image, error)
- func (s *Client) GetGenres() ([]*Genre, error)
- func (s *Client) GetIndexes(parameters map[string]string) (*Indexes, error)
- func (s *Client) GetInternetRadioStations() ([]*InternetRadioStation, error)
- func (c *Client) GetJukeboxPlaylist() (*JukeboxPlaylist, error)
- func (s *Client) GetLicense() (*License, error)
- func (s *Client) GetLyrics(title, artist string) (*Lyrics, error)
- func (c *Client) GetLyricsBySongId(songID string) (*LyricsList, error)
- func (s *Client) GetMusicDirectory(id string) (*Directory, error)
- func (s *Client) GetMusicFolders() ([]*MusicFolder, error)
- func (s *Client) GetNowPlaying() ([]*NowPlayingEntry, error)
- func (c *Client) GetOpenSubsonicExtensions() ([]*OpenSubsonicExtension, error)
- func (c *Client) GetPlayQueue() (*PlayQueue, error)
- func (s *Client) GetPlaylist(id string) (*Playlist, error)
- func (s *Client) GetPlaylists(parameters map[string]string) ([]*Playlist, error)
- func (s *Client) GetRandomSongs(parameters map[string]string) ([]*Child, error)
- func (c *Client) GetScanStatus() (*ScanStatus, error)
- func (c *Client) GetShares() ([]*Share, error)
- func (s *Client) GetSimilarSongs(id string, parameters map[string]string) ([]*Child, error)
- func (s *Client) GetSimilarSongs2(id string, parameters map[string]string) ([]*Child, error)
- func (s *Client) GetSong(id string) (*Child, error)
- func (s *Client) GetSongsByGenre(name string, parameters map[string]string) ([]*Child, error)
- func (s *Client) GetStarred(parameters map[string]string) (*Starred, error)
- func (s *Client) GetStarred2(parameters map[string]string) (*Starred2, error)
- func (s *Client) GetStreamURL(id string, parameters map[string]string) (*url.URL, error)
- func (s *Client) GetTopSongs(name string, parameters map[string]string) ([]*Child, error)
- func (c *Client) GetUser(username string) (*User, error)
- func (c *Client) GetUsers() ([]*User, error)
- func (c *Client) JukeboxControl(action string, parameters map[string]string) (*JukeboxStatus, error)
- func (s *Client) Ping() bool
- func (s *Client) Request(method string, endpoint string, params url.Values) (*http.Response, error)
- func (c *Client) SavePlayQueue(songIDs []string, params map[string]string) error
- func (s *Client) Scrobble(id string, parameters map[string]string) error
- func (s *Client) Search2(query string, parameters map[string]string) (*SearchResult2, error)
- func (s *Client) Search3(query string, parameters map[string]string) (*SearchResult3, error)
- func (s *Client) SendDownloadRequest(id string) (*http.Response, error)
- func (s *Client) SetRating(id string, rating int) error
- func (s *Client) Star(parameters StarParameters) error
- func (c *Client) StartScan() (*ScanStatus, error)
- func (s *Client) Stream(id string, parameters map[string]string) (io.ReadCloser, error)
- func (s *Client) Unstar(parameters StarParameters) error
- func (s *Client) UpdatePlaylist(playlistId string, parameters map[string]string) error
- func (s *Client) UpdatePlaylistTracks(playlistId string, trackIDsToAdd []string, trackIndexesToRemove []int) error
- func (c *Client) UpdateShare(id string, parameters map[string]string) error
- func (c *Client) UpdateUser(username string, parameters map[string]string) error
- type Contributor
- type Directory
- type Error
- type Genre
- type IDName
- type Index
- type IndexID3
- type Indexes
- type InternetRadioStation
- type ItemDate
- type JukeboxPlaylist
- type JukeboxStatus
- type License
- type LyricLine
- type Lyrics
- type LyricsList
- type MusicFolder
- type NowPlayingEntry
- type OpenSubsonicExtension
- type PlayQueue
- type Playlist
- type PodcastChannel
- type PodcastEpisode
- type ReplayGain
- type Response
- type ScanStatus
- type SearchResult2
- type SearchResult3
- type Share
- type StarParameters
- type Starred
- type Starred2
- type StructuredLyrics
- type User
Constants ¶
const ( SongLyricsExtension = "songLyrics" TranscodeOffset = "transcodeOffset" )
Variables ¶
var (
ErrAuthenticationFailure = errors.New("authentication failure")
)
Functions ¶
This section is empty.
Types ¶
type AlbumID3 ¶
type AlbumID3 struct { ID string `xml:"id,attr"` // Manually added Song []*Child `xml:"song,omitempty"` // Merged from AlbumWithSongsID3 Name string `xml:"name,attr"` Artist string `xml:"artist,attr,omitempty"` ArtistID string `xml:"artistId,attr,omitempty"` Artists []IDName `xml:"artists,omitempty"` // OpenSubsonic extension 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"` ReleaseDate *ItemDate `xml:"releaseDate,omitempty"` // OpenSubsonic extension OriginalReleaseDate *ItemDate `xml:"originalReleaseDate,omitempty"` // OpenSubsonic extension Genre string `xml:"genre,attr,omitempty"` Genres []IDName `xml:"genres,omitempty"` // OpenSubsonic extension ReleaseTypes []string `xml:"releaseTypes,omitempty"` // OpenSubsonic extension IsCompilation bool `xml:"isCompilation,attr"` // OpenSubsonic extension }
AlbumID3 is an album that's organized by music file tags.
func (*AlbumID3) MarshalXML ¶
func (*AlbumID3) UnmarshalXML ¶
type AlbumInfo ¶
type AlbumInfo struct { Notes string `xml:"notes,omitempty"` MusicBrainzID string `xml:"musicBrainzId,omitempty"` LastFmUrl string `xml:"lastFmUrl,omitempty"` SmallImageUrl string `xml:"smallImageUrl,omitempty"` MediumImageUrl string `xml:"mediumImageUrl,omitempty"` LargeImageUrl string `xml:"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.
func (*Artist) MarshalXML ¶
func (*Artist) UnmarshalXML ¶
type ArtistID3 ¶
type ArtistID3 struct { ID string `xml:"id,attr"` // Manually added Album []*AlbumID3 `xml:"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"` SortName string `xml:"sortName,attr,omitempty"` // OpenSubsonic extension MusicBrainzId string `xml:"musicBrainzId,attr,omitempty"` // OpenSubsonic extension }
ArtistID3 is an artist from the server, organized by ID3 tag.
func (*ArtistID3) MarshalXML ¶
func (*ArtistID3) UnmarshalXML ¶
type ArtistInfo ¶
type ArtistInfo struct { SimilarArtist []*Artist `xml:"similarArtist,omitempty"` Biography string `xml:"biography,omitempty"` MusicBrainzID string `xml:"musicBrainzId,omitempty"` LastFmUrl string `xml:"lastFmUrl,omitempty"` SmallImageUrl string `xml:"smallImageUrl,omitempty"` MediumImageUrl string `xml:"mediumImageUrl,omitempty"` LargeImageUrl string `xml:"largeImageUrl,omitempty"` }
ArtistInfo is all auxillary information about an artist from GetArtistInfo.
type ArtistInfo2 ¶
type ArtistInfo2 struct { SimilarArtist []*ArtistID3 `xml:"similarArtist,omitempty"` Biography string `xml:"biography,omitempty"` MusicBrainzID string `xml:"musicBrainzId,omitempty"` LastFmUrl string `xml:"lastFmUrl,omitempty"` SmallImageUrl string `xml:"smallImageUrl,omitempty"` MediumImageUrl string `xml:"mediumImageUrl,omitempty"` LargeImageUrl string `xml:"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:"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:"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 (*Bookmark) UnmarshalXML ¶
type ChatMessage ¶
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"` Artists []IDName `xml:"artists,omitempty"` // OpenSubsonic extension AlbumArtists []IDName `xml:"albumArtists,omitempty"` // OpenSubsonic extension DisplayArtist string `xml:"displayArtist,attr,omitempty"` // OpenSubsonic extension DisplayAlbumArtist string `xml:"displayAlbumArtist,attr,omitempty"` // OpenSubsonic extension Contributors []Contributor `xml:"contributors,omitempty"` // OpenSubsonic extension DisplayComposer string `xml:"displayComposer,attr,omitempty"` // OpenSubsonic extension Track int `xml:"track,attr,omitempty"` Year int `xml:"year,attr,omitempty"` Genre string `xml:"genre,attr,omitempty"` Genres []IDName `xml:"genres,omitempty"` // OpenSubsonic extension Comment string `xml:"comment,attr,omitempty"` // OpenSubsonic extension BPM int `xml:"bpm,attr"` // OpenSubsonic extension MusicBrainzID string `xml:"musicBrainzId,attr,omitempty"` // OpenSubsonic extension 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"` BitDepth int `xml:"bitDepth,attr,omitempty"` // OpenSubsonic extension SamplingRate int `xml:"samplingRate,attr,omitempty"` // OpenSubsonic extension ChannelCount int `xml:"channelCount,attr,omitempty"` // OpenSubsonic extension 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"` Played time.Time `xml:"played,attr,omitempty"` // OpenSubsonic extension 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"` ReplayGain *ReplayGain `xml:"replayGain,omitempty"` // OpenSubsonic extension }
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.
func (*Child) MarshalXML ¶
func (*Child) UnmarshalXML ¶
type Client ¶
type Client struct { Client *http.Client BaseUrl string User string ClientName string PasswordAuth bool RequestedAPIVersion string // contains filtered or unexported fields }
func (*Client) Authenticate ¶
Authenticate authenticates the current user with a provided password. If s.PasswordAuth is false, the password is salted before transmission and requires Subsonic > 1.13.0. Returns ErrAuthenticationFailure if the user/pass combo is incorrect, or another error type for any other failure reason.
func (*Client) ChangePassword ¶
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 ¶
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) CreatePlaylistWithTracks ¶
CreatePlaylistWithTracks creates (or updates) a playlist, with the given tracks being added.
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) CreateShare ¶
CreateShare creates a public URL that can be used by anyone to stream music or video from the Subsonic server. The URL is short and suitable for posting on Facebook, Twitter etc. Note: The user must be authorized to share.
Optional Parameters:
description: A user-defined description that will be displayed to people visiting the shared media. expires: The time at which the share expires. Given as milliseconds since 1970.
func (*Client) CreateUser ¶
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 ¶
DeletePlaylist deletes a saved playlist.
func (*Client) DeleteShare ¶
DeleteShare deletes an existing share.
func (*Client) DeleteUser ¶
DeleteUser deletes an existing Subsonic user.
func (*Client) Download ¶
func (s *Client) Download(id string) (io.ReadCloser, 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 ¶
Get is a convenience interface to issue a GET request and parse the response body (99% of Subsonic API calls)
func (*Client) GetAlbumInfo ¶
GetAlbumInfo returns album notes, image data, etc using data from last.fm. This accepts both album and song IDs.
func (*Client) GetAlbumInfo2 ¶
GetAlbumInfo2 returns the same data as GetAlbumInfo, but organized by id3 tag. It only accepts album IDs.
func (*Client) GetAlbumList ¶
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 ¶
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) GetArtistInfo ¶
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 ¶
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) GetCoverArt ¶
GetCoverArt returns a cover art image for a song, album, or artist.
Optional Parameters:
size: If specified, scale image to this size.
func (*Client) GetIndexes ¶
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) GetInternetRadioStations ¶
func (s *Client) GetInternetRadioStations() ([]*InternetRadioStation, error)
func (*Client) GetJukeboxPlaylist ¶
func (c *Client) GetJukeboxPlaylist() (*JukeboxPlaylist, error)
GetJukeboxPlaylist retrieves the current jukebox playlist.
func (*Client) GetLicense ¶
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) GetLyrics ¶
GetLyrics earches for and returns lyrics for a given song.
Optional Parameters:
title: The song title artist: The song artist
func (*Client) GetLyricsBySongId ¶
func (c *Client) GetLyricsBySongId(songID string) (*LyricsList, error)
Get structured lyrics for a track.
Server must support OpenSubsonic songLyrics extension
func (*Client) GetMusicDirectory ¶
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) GetOpenSubsonicExtensions ¶
func (c *Client) GetOpenSubsonicExtensions() ([]*OpenSubsonicExtension, error)
Get the list of supported OpenSubsonic extensions for this server.
func (*Client) GetPlayQueue ¶
GetPlayQueue Returns the state of the play queue for this user (as set by savePlayQueue). This includes the tracks in the play queue, the currently playing track, and the position within this track. Typically used to allow a user to move between different clients/apps while retaining the same play queue (for instance when listening to an audio book).
func (*Client) GetPlaylist ¶
GetPlaylist returns a listing of files in a saved playlist.
func (*Client) GetPlaylists ¶
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 ¶
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) GetShares ¶
GetShares returns information about shared media this user is allowed to manage.
func (*Client) GetSimilarSongs ¶
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 ¶
GetSimilarSongs2 finds similar songs like GetSimilarSongs, but using id3 tags.
Optional Parameters:
count: Number of songs to return
func (*Client) GetSongsByGenre ¶
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 ¶
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 ¶
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) GetStreamURL ¶
GetStreamURL returns the URL for streaming the specified media. Similar to Stream, except it does not actually perform the HTTP request. Useful when the streaming will be handled by an outside program, e.g. mpv.
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) GetTopSongs ¶
GetTopSongs returns the top songs for a given artist by name.
Optional Parameters:
count: Number of songs to return
func (*Client) GetUser ¶
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 ¶
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) JukeboxControl ¶
func (c *Client) JukeboxControl(action string, parameters map[string]string) (*JukeboxStatus, error)
JukeboxControl controls the jukebox, i.e., playback directly on the server's audio hardware. Note: The user must be authorized to control the jukebox (see Settings > Users > User is allowed to play files in jukebox mode).
Parameters:
action: The action to perform. Must be one of "status", "set", "start", "stop", "skip", "add", "clear", "remove", "shuffle", "setGain" Note: the "get" action is implemented as the GetJukeboxPlaylist() function.
Optional Parameters:
index: Used by skip and remove. Zero-based index of the song to skip to or remove. offset: Used by skip. Start playing this many seconds into the track. id: Used by add and set. ID of song to add to the jukebox playlist. Use multiple id parameters to add many songs in the same request. gain: Used by setGain to control the playback volume. A float value between 0.0 and 1.0.
func (*Client) Ping ¶
Ping is used to test connectivity with the server. It returns true if the server is up. Should generally NOT be called before authenticating as it will be considered an authentication by the Subsonic server. (Though this function will still return true)
func (*Client) Request ¶
Request performs a HTTP request against the Subsonic server as the current user. If a nil error is returned, the caller is responsible for closing the response body.
func (*Client) SavePlayQueue ¶
SavePlayQueue saves the state of the play queue for this user. This includes the tracks in the play queue, the currently playing track, and the position within this track. Typically used to allow a user to move between different clients/apps while retaining the same play queue (for instance when listening to an audio book).
Parameters:
songIDs: IDs of the songs in the play queue
Optional parameters:
current: the ID of the currently playing song position: The position in milliseconds within the currently playing song
func (*Client) Scrobble ¶
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 ¶
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 ¶
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) SendDownloadRequest ¶
Sends a download request and returns the raw http.Response with no further processing. Caller must read and close the response body.
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 ¶
Stream returns the contents of a song, optionally transcoded, from the server. If a nil error is returned, the caller is responsable for closing the Reader.
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 ¶
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) UpdatePlaylistTracks ¶
func (s *Client) UpdatePlaylistTracks( playlistId string, trackIDsToAdd []string, trackIndexesToRemove []int, ) error
UpdatePlaylistTracks updates the tracks in a playlist. Only the owner of a playlist is allowed to update it.
func (*Client) UpdateShare ¶
UpdateShare updates the description and/or expiration date for an existing share.
Optional Parameters:
description: A user-defined description that will be displayed to people visiting the shared media. expires: The time at which the share expires. Given as milliseconds since 1970, or zero to remove the expiration.
func (*Client) UpdateUser ¶
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 Contributor ¶
type Directory ¶
type Directory struct { ID string `xml:"id,attr"` // Manually added Child []*Child `xml:"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.
func (*Directory) MarshalXML ¶
func (*Directory) UnmarshalXML ¶
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 IDName ¶
Used for any entity where only a name and an ID appear. Eg. OpenSubsonic artists list for an album.
type Index ¶
Index is a collection of artists that begin with the same first letter, along with that letter or category.
type IndexID3 ¶
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:"shortcut,omitempty"` Index []*Index `xml:"index,omitempty"` Child []*Child `xml:"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 JukeboxPlaylist ¶
type JukeboxStatus ¶
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.
func (*License) MarshalXML ¶
func (*License) UnmarshalXML ¶
type LyricsList ¶
type LyricsList struct {
StructuredLyrics []*StructuredLyrics `xml:"structuredLyrics,omitempty"`
}
type MusicFolder ¶
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.
func (*NowPlayingEntry) MarshalXML ¶
func (t *NowPlayingEntry) MarshalXML(e *xml.Encoder, start xml.StartElement) error
func (*NowPlayingEntry) UnmarshalXML ¶
func (t *NowPlayingEntry) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
type OpenSubsonicExtension ¶
type PlayQueue ¶
type PlayQueue struct { Entries []*Child `xml:"entry,omitempty"` Current string `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 (*PlayQueue) UnmarshalXML ¶
type Playlist ¶
type Playlist struct { ID string `xml:"id,attr"` // Added manually Entry []*Child `xml:"entry,omitempty"` // Merged from PlaylistWithSongs AllowedUser []string `xml:"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,omitempty"` 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.
func (*Playlist) MarshalXML ¶
func (*Playlist) UnmarshalXML ¶
type PodcastChannel ¶
type PodcastChannel struct { Episode []*PodcastEpisode `xml:"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 ReplayGain ¶
type ReplayGain struct { TrackGain float64 `xml:"trackGain,omitempty,attr" json:"trackGain,omitempty"` AlbumGain float64 `xml:"albumGain,omitempty,attr" json:"albumGain,omitempty"` TrackPeak float64 `xml:"trackPeak,omitempty,attr" json:"trackPeak,omitempty"` AlbumPeak float64 `xml:"albumPeak,omitempty,attr" json:"albumPeak,omitempty"` }
type Response ¶
type Response struct { License *License `xml:"license"` MusicFolders *musicFolders `xml:"musicFolders"` Indexes *Indexes `xml:"indexes"` Directory *Directory `xml:"directory"` Genres *genres `xml:"genres"` Artists *ArtistsID3 `xml:"artists"` Artist *ArtistID3 `xml:"artist"` Album *AlbumID3 `xml:"album"` Song *Child `xml:"song"` NowPlaying *nowPlaying `xml:"nowPlaying"` SearchResult2 *SearchResult2 `xml:"searchResult2"` SearchResult3 *SearchResult3 `xml:"searchResult3"` Playlists *playlists `xml:"playlists"` Playlist *Playlist `xml:"playlist"` JukeboxStatus *JukeboxStatus `xml:"jukeboxStatus"` JukeboxPlaylist *JukeboxPlaylist `xml:"jukeboxPlaylist"` Users *users `xml:"users"` User *User `xml:"user"` ChatMessages *chatMessages `xml:"chatMessages"` AlbumList *albumList `xml:"albumList"` AlbumList2 *albumList2 `xml:"albumList2"` RandomSongs *songs `xml:"randomSongs"` SongsByGenre *songs `xml:"songsByGenre"` Lyrics *Lyrics `xml:"lyrics"` Podcasts *podcasts `xml:"podcasts"` NewestPodcasts *newestPodcasts `xml:"newestPodcasts"` InternetRadioStations *internetRadioStations `xml:"internetRadioStations"` Bookmarks *bookmarks `xml:"bookmarks"` PlayQueue *PlayQueue `xml:"playQueue"` Starred *Starred `xml:"starred"` Starred2 *Starred2 `xml:"starred2"` AlbumInfo *AlbumInfo `xml:"albumInfo"` ArtistInfo *ArtistInfo `xml:"artistInfo"` ArtistInfo2 *ArtistInfo2 `xml:"artistInfo2"` SimilarSongs *similarSongs `xml:"similarSongs"` SimilarSongs2 *similarSongs2 `xml:"similarSongs2"` TopSongs *topSongs `xml:"topSongs"` ScanStatus *ScanStatus `xml:"scanStatus"` Error *Error `xml:"error"` Status string `xml:"status,attr"` // May be one of ok, failed Version string `xml:"version,attr"` // Must match the pattern \d+\.\d+\.\d+ OpenSubsonic bool `xml:"openSubsonic,attr"` OpenSubsonicExtensions []*OpenSubsonicExtension `xml:"openSubsonicExtensions"` LyricsList *LyricsList `xml:"lyricsList"` }
Response is the main target for unmarshalling data from the API - everything within the "subsonic-response" key
type ScanStatus ¶
type SearchResult2 ¶
type SearchResult2 struct { Artist []*Artist `xml:"artist,omitempty"` Album []*Child `xml:"album,omitempty"` Song []*Child `xml:"song,omitempty"` }
SearchResult2 is a collection of songs, albums, and artists related to a query.
type SearchResult3 ¶
type SearchResult3 struct { Artist []*ArtistID3 `xml:"artist,omitempty"` Album []*AlbumID3 `xml:"album,omitempty"` Song []*Child `xml:"song,omitempty"` }
SearchResult3 is a collection of songs, albums, and artists related to a query.
type StarParameters ¶
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:"artist,omitempty"` Album []*Child `xml:"album,omitempty"` Song []*Child `xml:"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:"artist,omitempty"` Album []*AlbumID3 `xml:"album,omitempty"` Song []*Child `xml:"song,omitempty"` }
Starred2 is a collection of songs, albums, and artists organized by ID3 tags annotated by a user as starred.
type StructuredLyrics ¶
type User ¶
type User struct { Folder []int `xml:"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"` VideoConversionRole bool `xml:"videoConversionRole,attr"` AvatarLastChanged time.Time `xml:"avatarLastChanged,attr,omitempty"` }