Struct Client 

pub struct Client { /* private fields */ }

An async client for the Subsonic / OpenSubsonic REST API.

Construct via Client::new and optionally customise with the builder methods (Client::with_client_name, Client::with_api_version, Client::with_http_client).

API endpoint methods are provided by the crate::api module and are available as methods on this struct via extension traits.

Implementations

impl Client

pub async fn get_bookmarks(&self) -> Result<Vec<Bookmark>, Error>

Get all bookmarks.

See https://opensubsonic.netlify.app/docs/endpoints/getbookmarks/

pub async fn create_bookmark( &self, id: &str, position: i64, comment: Option<&str>, ) -> Result<(), Error>

Create or update a bookmark.

See https://opensubsonic.netlify.app/docs/endpoints/createbookmark/

pub async fn delete_bookmark(&self, id: &str) -> Result<(), Error>

Delete a bookmark.

See https://opensubsonic.netlify.app/docs/endpoints/deletebookmark/

pub async fn get_play_queue(&self) -> Result<PlayQueue, Error>

Get the play queue (current playlist/position saved by a client).

See https://opensubsonic.netlify.app/docs/endpoints/getplayqueue/

pub async fn save_play_queue( &self, ids: &[&str], current: Option<&str>, position: Option<i64>, ) -> Result<(), Error>

Save the play queue.

See https://opensubsonic.netlify.app/docs/endpoints/saveplayqueue/

pub async fn get_play_queue_by_index(&self) -> Result<PlayQueueByIndex, Error>

Get the play queue by index (OpenSubsonic extension).

See https://opensubsonic.netlify.app/docs/endpoints/getplayqueuebyindex/

pub async fn save_play_queue_by_index( &self, ids: &[&str], current_index: Option<i32>, position: Option<i64>, ) -> Result<(), Error>

Save the play queue by index (OpenSubsonic extension).

See https://opensubsonic.netlify.app/docs/endpoints/saveplayqueuebyindex/

impl Client

pub async fn get_music_folders(&self) -> Result<Vec<MusicFolder>, Error>

Get all configured music folders.

See https://opensubsonic.netlify.app/docs/endpoints/getmusicfolders/

pub async fn get_indexes( &self, music_folder_id: Option<&str>, if_modified_since: Option<i64>, ) -> Result<Indexes, Error>

Get an indexed structure of all artists (folder-based).

See https://opensubsonic.netlify.app/docs/endpoints/getindexes/

pub async fn get_music_directory(&self, id: &str) -> Result<Directory, Error>

Get a directory listing (folder-based browsing).

See https://opensubsonic.netlify.app/docs/endpoints/getmusicdirectory/

pub async fn get_genres(&self) -> Result<Vec<Genre>, Error>

Get all genres.

See https://opensubsonic.netlify.app/docs/endpoints/getgenres/

pub async fn get_artists( &self, music_folder_id: Option<&str>, ) -> Result<ArtistsId3, Error>

Get all artists (ID3-based).

See https://opensubsonic.netlify.app/docs/endpoints/getartists/

pub async fn get_artist(&self, id: &str) -> Result<ArtistWithAlbumsId3, Error>

Get details for an artist, including a list of albums (ID3-based).

See https://opensubsonic.netlify.app/docs/endpoints/getartist/

pub async fn get_album(&self, id: &str) -> Result<AlbumWithSongsId3, Error>

Get details for an album, including a list of songs (ID3-based).

See https://opensubsonic.netlify.app/docs/endpoints/getalbum/

pub async fn get_song(&self, id: &str) -> Result<Child, Error>

Get details for a song.

See https://opensubsonic.netlify.app/docs/endpoints/getsong/

pub async fn get_videos(&self) -> Result<Vec<Child>, Error>

Get all video files. Returns an empty list if the server has no videos.

See https://opensubsonic.netlify.app/docs/endpoints/getvideos/

pub async fn get_artist_info( &self, id: &str, count: Option<i32>, include_not_present: Option<bool>, ) -> Result<ArtistInfo, Error>

Get artist info (folder-based).

See https://opensubsonic.netlify.app/docs/endpoints/getartistinfo/

pub async fn get_artist_info2( &self, id: &str, count: Option<i32>, include_not_present: Option<bool>, ) -> Result<ArtistInfo2, Error>

Get artist info (ID3-based).

See https://opensubsonic.netlify.app/docs/endpoints/getartistinfo2/

pub async fn get_album_info(&self, id: &str) -> Result<AlbumInfo, Error>

Get album info (external metadata).

See https://opensubsonic.netlify.app/docs/endpoints/getalbuminfo/

pub async fn get_album_info2(&self, id: &str) -> Result<AlbumInfo, Error>

Get album info (ID3-based).

See https://opensubsonic.netlify.app/docs/endpoints/getalbuminfo2/

pub async fn get_similar_songs( &self, id: &str, count: Option<i32>, ) -> Result<Vec<Child>, Error>

Get similar songs (folder-based).

See https://opensubsonic.netlify.app/docs/endpoints/getsimilarsongs/

pub async fn get_similar_songs2( &self, id: &str, count: Option<i32>, ) -> Result<Vec<Child>, Error>

Get similar songs (ID3-based).

See https://opensubsonic.netlify.app/docs/endpoints/getsimilarsongs2/

pub async fn get_top_songs( &self, artist: &str, count: Option<i32>, ) -> Result<Vec<Child>, Error>

Get top songs for an artist.

See https://opensubsonic.netlify.app/docs/endpoints/gettopsongs/

impl Client

pub async fn get_chat_messages( &self, since: Option<i64>, ) -> Result<Vec<ChatMessage>, Error>

Get chat messages.

See https://opensubsonic.netlify.app/docs/endpoints/getchatmessages/

pub async fn add_chat_message(&self, message: &str) -> Result<(), Error>

Add a chat message.

See https://opensubsonic.netlify.app/docs/endpoints/addchatmessage/

impl Client

pub async fn get_internet_radio_stations( &self, ) -> Result<Vec<InternetRadioStation>, Error>

Get all internet radio stations.

See https://opensubsonic.netlify.app/docs/endpoints/getinternetradiostations/

pub async fn create_internet_radio_station( &self, stream_url: &str, name: &str, home_page_url: Option<&str>, ) -> Result<(), Error>

Create a new internet radio station.

See https://opensubsonic.netlify.app/docs/endpoints/createinternetradiostation/

pub async fn update_internet_radio_station( &self, id: &str, stream_url: &str, name: &str, home_page_url: Option<&str>, ) -> Result<(), Error>

Update an existing internet radio station.

See https://opensubsonic.netlify.app/docs/endpoints/updateinternetradiostation/

pub async fn delete_internet_radio_station(&self, id: &str) -> Result<(), Error>

Delete an internet radio station.

See https://opensubsonic.netlify.app/docs/endpoints/deleteinternetradiostation/

impl Client

pub async fn jukebox_control( &self, action: JukeboxAction, index: Option<i32>, offset: Option<i32>, ids: &[&str], gain: Option<f64>, ) -> Result<JukeboxResult, Error>

Control the jukebox (server-side playback).

See https://opensubsonic.netlify.app/docs/endpoints/jukeboxcontrol/

impl Client

pub async fn get_album_list( &self, list_type: AlbumListType, size: Option<i32>, offset: Option<i32>, from_year: Option<i32>, to_year: Option<i32>, genre: Option<&str>, music_folder_id: Option<&str>, ) -> Result<Vec<Child>, Error>

Get a list of albums (folder-based).

See https://opensubsonic.netlify.app/docs/endpoints/getalbumlist/

pub async fn get_album_list2( &self, list_type: AlbumListType, size: Option<i32>, offset: Option<i32>, from_year: Option<i32>, to_year: Option<i32>, genre: Option<&str>, music_folder_id: Option<&str>, ) -> Result<Vec<AlbumId3>, Error>

Get a list of albums (ID3-based).

See https://opensubsonic.netlify.app/docs/endpoints/getalbumlist2/

pub async fn get_random_songs( &self, size: Option<i32>, genre: Option<&str>, from_year: Option<i32>, to_year: Option<i32>, music_folder_id: Option<&str>, ) -> Result<Vec<Child>, Error>

Get random songs.

See https://opensubsonic.netlify.app/docs/endpoints/getrandomsongs/

pub async fn get_songs_by_genre( &self, genre: &str, count: Option<i32>, offset: Option<i32>, music_folder_id: Option<&str>, ) -> Result<Vec<Child>, Error>

Get songs by genre.

See https://opensubsonic.netlify.app/docs/endpoints/getsongsbygenre/

pub async fn get_now_playing(&self) -> Result<Vec<NowPlayingEntry>, Error>

Get what is currently being played by all users.

See https://opensubsonic.netlify.app/docs/endpoints/getnowplaying/

pub async fn get_starred( &self, music_folder_id: Option<&str>, ) -> Result<StarredContent, Error>

Get starred songs, albums and artists (folder-based).

See https://opensubsonic.netlify.app/docs/endpoints/getstarred/

pub async fn get_starred2( &self, music_folder_id: Option<&str>, ) -> Result<Starred2Content, Error>

Get starred songs, albums and artists (ID3-based).

See https://opensubsonic.netlify.app/docs/endpoints/getstarred2/

impl Client

pub async fn star( &self, ids: &[&str], album_ids: &[&str], artist_ids: &[&str], ) -> Result<(), Error>

Star songs, albums, or artists.

See https://opensubsonic.netlify.app/docs/endpoints/star/

pub async fn unstar( &self, ids: &[&str], album_ids: &[&str], artist_ids: &[&str], ) -> Result<(), Error>

Unstar songs, albums, or artists.

See https://opensubsonic.netlify.app/docs/endpoints/unstar/

pub async fn set_rating(&self, id: &str, rating: i32) -> Result<(), Error>

Set the rating of a song, album, or artist.

A rating of 0 removes the rating.

See https://opensubsonic.netlify.app/docs/endpoints/setrating/

pub async fn scrobble( &self, id: &str, time: Option<i64>, submission: Option<bool>, ) -> Result<(), Error>

Register a song as played (scrobble).

If submission is false, this is a “now playing” notification rather than a scrobble.

See https://opensubsonic.netlify.app/docs/endpoints/scrobble/

pub async fn report_playback( &self, media_id: &str, media_type: &str, position_ms: i64, state: &str, playback_rate: Option<f64>, ignore_scrobble: Option<bool>, ) -> Result<(), Error>

Report playback state to the server (OpenSubsonic, playbackReport extension).

See https://opensubsonic.netlify.app/docs/endpoints/reportplayback/

impl Client

pub async fn stream( &self, id: &str, max_bit_rate: Option<i32>, format: Option<&str>, time_offset: Option<i32>, estimated_content_length: Option<bool>, ) -> Result<Bytes, Error>

Stream a song or video. Returns the raw bytes.

See https://opensubsonic.netlify.app/docs/endpoints/stream/

pub fn stream_url( &self, id: &str, max_bit_rate: Option<i32>, format: Option<&str>, ) -> Result<Url, Error>

Build a streaming URL for a song without making an HTTP request.

Useful for passing to external audio players or download managers.

pub async fn download(&self, id: &str) -> Result<Bytes, Error>

Download a song or video. Returns raw bytes.

See https://opensubsonic.netlify.app/docs/endpoints/download/

pub fn hls_url( &self, id: &str, bit_rate: Option<&str>, audio_track: Option<&str>, ) -> Result<Url, Error>

Get an HLS playlist URL for a video or song.

See https://opensubsonic.netlify.app/docs/endpoints/hls/

pub async fn get_captions( &self, id: &str, format: Option<&str>, ) -> Result<Bytes, Error>

Get captions (subtitles) for a video. Returns raw bytes.

See https://opensubsonic.netlify.app/docs/endpoints/getcaptions/

pub async fn get_cover_art( &self, id: &str, size: Option<i32>, ) -> Result<Bytes, Error>

Get cover art for an album or artist. Returns raw image bytes.

See https://opensubsonic.netlify.app/docs/endpoints/getcoverart/

pub fn cover_art_url(&self, id: &str, size: Option<i32>) -> Result<Url, Error>

Build a cover art URL without making an HTTP request.

pub async fn get_lyrics( &self, artist: Option<&str>, title: Option<&str>, ) -> Result<Lyrics, Error>

Get lyrics for a song (legacy, unstructured).

See https://opensubsonic.netlify.app/docs/endpoints/getlyrics/

pub async fn get_lyrics_by_song_id( &self, id: &str, enhanced: Option<bool>, ) -> Result<LyricsList, Error>

Get structured lyrics for a song by ID (OpenSubsonic extension).

See https://opensubsonic.netlify.app/docs/endpoints/getlyricsbysongid/

pub async fn get_avatar(&self, username: &str) -> Result<Bytes, Error>

Get a user’s avatar image. Returns raw image bytes.

See https://opensubsonic.netlify.app/docs/endpoints/getavatar/

impl Client

pub async fn get_playlists( &self, username: Option<&str>, ) -> Result<Vec<Playlist>, Error>

Get all playlists.

See https://opensubsonic.netlify.app/docs/endpoints/getplaylists/

pub async fn get_playlist(&self, id: &str) -> Result<PlaylistWithSongs, Error>

Get a playlist with its songs.

See https://opensubsonic.netlify.app/docs/endpoints/getplaylist/

pub async fn create_playlist( &self, playlist_id: Option<&str>, name: Option<&str>, song_ids: &[&str], ) -> Result<PlaylistWithSongs, Error>

Create or update a playlist.

If playlist_id is provided, the existing playlist is updated. Otherwise, a new playlist is created with the given name.

See https://opensubsonic.netlify.app/docs/endpoints/createplaylist/

pub async fn update_playlist( &self, playlist_id: &str, name: Option<&str>, comment: Option<&str>, public: Option<bool>, song_ids_to_add: &[&str], song_indexes_to_remove: &[i32], ) -> Result<(), Error>

Update a playlist (name, comment, public status, add/remove songs).

See https://opensubsonic.netlify.app/docs/endpoints/updateplaylist/

pub async fn delete_playlist(&self, id: &str) -> Result<(), Error>

Delete a playlist.

See https://opensubsonic.netlify.app/docs/endpoints/deleteplaylist/

impl Client

pub async fn get_podcasts( &self, include_episodes: Option<bool>, id: Option<&str>, ) -> Result<Vec<PodcastChannel>, Error>

Get all podcast channels.

If include_episodes is false, episodes are not included in the response.

See https://opensubsonic.netlify.app/docs/endpoints/getpodcasts/

pub async fn get_newest_podcasts( &self, count: Option<i32>, ) -> Result<Vec<PodcastEpisode>, Error>

Get the newest podcast episodes.

See https://opensubsonic.netlify.app/docs/endpoints/getnewestpodcasts/

pub async fn get_podcast_episode( &self, id: &str, ) -> Result<PodcastEpisode, Error>

Get a specific podcast episode (OpenSubsonic extension).

See https://opensubsonic.netlify.app/docs/endpoints/getpodcastepisode/

pub async fn refresh_podcasts(&self) -> Result<(), Error>

Tell the server to check for new podcast episodes.

See https://opensubsonic.netlify.app/docs/endpoints/refreshpodcasts/

pub async fn create_podcast_channel(&self, url: &str) -> Result<(), Error>

Add a new podcast channel (by feed URL).

See https://opensubsonic.netlify.app/docs/endpoints/createpodcastchannel/

pub async fn delete_podcast_channel(&self, id: &str) -> Result<(), Error>

Delete a podcast channel.

See https://opensubsonic.netlify.app/docs/endpoints/deletepodcastchannel/

pub async fn delete_podcast_episode(&self, id: &str) -> Result<(), Error>

Delete a podcast episode.

See https://opensubsonic.netlify.app/docs/endpoints/deletepodcastepisode/

pub async fn download_podcast_episode(&self, id: &str) -> Result<(), Error>

Tell the server to download a podcast episode.

See https://opensubsonic.netlify.app/docs/endpoints/downloadpodcastepisode/

impl Client

pub async fn get_scan_status(&self) -> Result<ScanStatus, Error>

Get the current scan status.

See https://opensubsonic.netlify.app/docs/endpoints/getscanstatus/

pub async fn start_scan(&self) -> Result<ScanStatus, Error>

Start a media library scan.

See https://opensubsonic.netlify.app/docs/endpoints/startscan/

impl Client

pub async fn search( &self, artist: Option<&str>, album: Option<&str>, title: Option<&str>, any: Option<&str>, count: Option<i32>, offset: Option<i32>, newer_than: Option<i64>, ) -> Result<SearchResult, Error>

Search (legacy, pre-1.4.0).

See https://opensubsonic.netlify.app/docs/endpoints/search/

pub async fn search2( &self, query: &str, artist_count: Option<i32>, artist_offset: Option<i32>, album_count: Option<i32>, album_offset: Option<i32>, song_count: Option<i32>, song_offset: Option<i32>, music_folder_id: Option<&str>, ) -> Result<SearchResult2, Error>

Search (folder-based, search2).

See https://opensubsonic.netlify.app/docs/endpoints/search2/

pub async fn search3( &self, query: &str, artist_count: Option<i32>, artist_offset: Option<i32>, album_count: Option<i32>, album_offset: Option<i32>, song_count: Option<i32>, song_offset: Option<i32>, music_folder_id: Option<&str>, ) -> Result<SearchResult3, Error>

Search (ID3-based, search3).

See https://opensubsonic.netlify.app/docs/endpoints/search3/

impl Client

pub async fn get_shares(&self) -> Result<Vec<Share>, Error>

Get all shares.

See https://opensubsonic.netlify.app/docs/endpoints/getshares/

pub async fn create_share( &self, ids: &[&str], description: Option<&str>, expires: Option<i64>, ) -> Result<Vec<Share>, Error>

Create a new share.

See https://opensubsonic.netlify.app/docs/endpoints/createshare/

pub async fn update_share( &self, id: &str, description: Option<&str>, expires: Option<i64>, ) -> Result<(), Error>

Update an existing share.

See https://opensubsonic.netlify.app/docs/endpoints/updateshare/

pub async fn delete_share(&self, id: &str) -> Result<(), Error>

Delete an existing share.

See https://opensubsonic.netlify.app/docs/endpoints/deleteshare/

impl Client

pub async fn get_sonic_similar_tracks( &self, id: &str, count: Option<i32>, ) -> Result<Vec<SonicMatch>, Error>

Get tracks sonically similar to the given song (OpenSubsonic, sonicSimilarity extension).

See https://opensubsonic.netlify.app/docs/endpoints/getsonicsimilartracks/

pub async fn find_sonic_path( &self, start_song_id: &str, end_song_id: &str, count: Option<i32>, ) -> Result<Vec<SonicMatch>, Error>

Find a path of sonically similar tracks between two songs (OpenSubsonic, sonicSimilarity extension).

See https://opensubsonic.netlify.app/docs/endpoints/findsonicpath/

impl Client

pub async fn ping(&self) -> Result<(), Error>

Test connectivity with the server. Returns Ok(()) on success.

See https://opensubsonic.netlify.app/docs/endpoints/ping/

pub async fn get_license(&self) -> Result<License, Error>

Get details about the software license.

See https://opensubsonic.netlify.app/docs/endpoints/getlicense/

pub async fn get_open_subsonic_extensions( &self, ) -> Result<Vec<OpenSubsonicExtension>, Error>

Get the list of OpenSubsonic API extensions supported by the server.

See https://opensubsonic.netlify.app/docs/endpoints/getopensubsonicextensions/

pub async fn token_info(&self) -> Result<TokenInfo, Error>

Get information about the API token (OpenSubsonic extension).

See https://opensubsonic.netlify.app/docs/endpoints/tokeninfo/

impl Client

pub async fn get_transcode_decision( &self, id: &str, max_bit_rate: Option<i32>, format: Option<&str>, client_info: Option<&ClientInfo>, ) -> Result<TranscodeDecision, Error>

Get a transcode decision for a song (OpenSubsonic extension).

This endpoint uses POST with a JSON body containing client info.

See https://opensubsonic.netlify.app/docs/endpoints/gettranscodedecision/

pub fn get_transcode_stream_url( &self, id: &str, max_bit_rate: Option<i32>, format: Option<&str>, ) -> Result<Url, Error>

Get a transcoded stream URL (OpenSubsonic extension).

Returns the URL for streaming transcoded audio. Does not make an HTTP request.

See https://opensubsonic.netlify.app/docs/endpoints/gettranscodestream/

pub async fn get_transcode_stream( &self, id: &str, max_bit_rate: Option<i32>, format: Option<&str>, ) -> Result<Bytes, Error>

Get a transcoded stream as raw bytes (OpenSubsonic extension).

See https://opensubsonic.netlify.app/docs/endpoints/gettranscodestream/

impl Client

pub async fn get_user(&self, username: &str) -> Result<User, Error>

Get details about a specific user.

See https://opensubsonic.netlify.app/docs/endpoints/getuser/

pub async fn get_users(&self) -> Result<Vec<User>, Error>

Get details about all users (admin only).

See https://opensubsonic.netlify.app/docs/endpoints/getusers/

pub async fn create_user( &self, username: &str, password: &str, email: &str, ldap_authenticated: Option<bool>, admin_role: Option<bool>, settings_role: Option<bool>, stream_role: Option<bool>, jukebox_role: Option<bool>, download_role: Option<bool>, upload_role: Option<bool>, playlist_role: Option<bool>, cover_art_role: Option<bool>, comment_role: Option<bool>, podcast_role: Option<bool>, share_role: Option<bool>, video_conversion_role: Option<bool>, music_folder_ids: &[i64], ) -> Result<(), Error>

Create a new user (admin only).

See https://opensubsonic.netlify.app/docs/endpoints/createuser/

pub async fn update_user( &self, username: &str, password: Option<&str>, email: Option<&str>, ldap_authenticated: Option<bool>, admin_role: Option<bool>, settings_role: Option<bool>, stream_role: Option<bool>, jukebox_role: Option<bool>, download_role: Option<bool>, upload_role: Option<bool>, playlist_role: Option<bool>, cover_art_role: Option<bool>, comment_role: Option<bool>, podcast_role: Option<bool>, share_role: Option<bool>, video_conversion_role: Option<bool>, max_bit_rate: Option<i32>, music_folder_ids: &[i64], ) -> Result<(), Error>

Update an existing user (admin only).

See https://opensubsonic.netlify.app/docs/endpoints/updateuser/

pub async fn delete_user(&self, username: &str) -> Result<(), Error>

Delete a user (admin only).

See https://opensubsonic.netlify.app/docs/endpoints/deleteuser/

pub async fn change_password( &self, username: &str, password: &str, ) -> Result<(), Error>

Change a user’s password.

See https://opensubsonic.netlify.app/docs/endpoints/changepassword/

impl Client

pub fn new(base_url: &str, auth: Auth) -> Result<Self, Error>

Create a new Subsonic API client.

Arguments

• base_url — The server base URL, e.g. "https://music.example.com".
• auth — Authentication method (see Auth::token, Auth::plain, Auth::api_key).

Errors

Returns Error::Url if base_url cannot be parsed.

pub fn with_client_name(self, name: &str) -> Self

Override the client application name sent as the c parameter.

pub fn with_api_version(self, version: &str) -> Self

Override the Subsonic REST protocol version sent as the v parameter.

pub fn with_http_client(self, client: Client) -> Self

Inject a custom reqwest::Client (e.g. with custom timeouts or TLS settings).

pub fn with_danger_accept_invalid_certs(self) -> Result<Self, Error>

Accept invalid TLS certificates (self-signed, expired, wrong hostname).

WARNING: This disables TLS certificate verification and should only be used in trusted network environments (e.g. Tailscale, local LAN).

Errors

Returns Error::Http if the HTTP client cannot be built.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.