Struct SubsonicClient 

pub struct SubsonicClient { /* private fields */ }

Subsonic/Navidrome API client.

Holds two HTTP clients with different timeout semantics: http bounds a whole JSON request, which is right for small API responses read in one go; downloader bounds only connect and per-read stalls, so a large track on a slow link is never cut off for taking too long overall.

Implementations

impl SubsonicClient

pub fn new(base_url: &str, username: &str, password: &str) -> Self

pub fn from_auth(auth: SubsonicAuth) -> Self

pub fn outage(&self) -> &Outage

Whether downloads from this server are waiting out an outage.

pub fn get_cover_art( &self, id: &str, size: Option<u32>, ) -> Result<Vec<u8>, SubsonicError>

Fetch cover art bytes for a song or album ID.

Returns the raw image rather than a parsed response — getCoverArt answers with image data, not JSON, so it can’t go through get(). size requests a square thumbnail; omit it for the original.

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

Ping the server — verify connection and credentials.

pub fn server_type(&self) -> Result<Option<String>, SubsonicError>

Which server this is, by its OpenSubsonic type. One round trip.

pub fn profile(&self) -> Result<ServerProfile, SubsonicError>

What this server says it is and which OpenSubsonic extensions it offers: ping, then getOpenSubsonicExtensions when it speaks OpenSubsonic. A server that does not has no extensions to list.

pub fn get_artists(&self) -> Result<Vec<SubsonicArtist>, SubsonicError>

Get all artists (indexed).

pub fn get_album(&self, id: &str) -> Result<SubsonicAlbumFull, SubsonicError>

Get an album by ID, including its tracks.

pub fn get_album_list( &self, list_type: &str, size: u32, offset: u32, ) -> Result<Vec<SubsonicAlbum>, SubsonicError>

Get a paginated list of albums.

pub fn stream_url(&self, track_id: &str) -> Result<String, SubsonicError>

Build the streaming URL for a track (doesn’t make a request).

pub fn stream_url_template(&self, track_id: &str) -> String

Stream URL without auth params — safe for database storage.

pub fn download(&self, track_id: &str, dest: &Path) -> Result<(), SubsonicError>

Download a track to a local path.

pub fn download_with_progress( &self, track_id: &str, dest: &Path, cancelled: &dyn Fn() -> bool, on_progress: impl Fn(u64, u64), ) -> Result<(), SubsonicError>

Download a track with progress reporting.

The callback receives (bytes_downloaded, total_bytes); total is 0 when the server sends no Content-Length, and the count restarts from zero if an attempt is retried. dest only appears once the file is complete.

A server that is not answering is waited out, however long that takes, until cancelled says the track is no longer wanted.

pub fn stream_to_file( &self, track_id: &str, dest: &Path, on_progress: impl Fn(u64, u64), ) -> Result<(), SubsonicError>

Fetch a track through /rest/stream instead of /rest/download.

download returns the untranscoded original and is what library sync wants from Navidrome. koan’s own server implements only stream, so that is how the remote bridge pulls audio from a koan serve instance.

pub fn all_songs_page( &self, size: u32, offset: u32, ) -> Result<Vec<SubsonicSong>, SubsonicError>

One page of every song on the server, size from offset.

An empty search3 query lists the whole library on OpenSubsonic servers (Navidrome, koan). Older servers answer it with nothing or an error, which is the caller’s cue to walk albums one at a time instead.

pub fn song_count(&self) -> Result<Option<u64>, SubsonicError>

How many songs the server says it has, from getScanStatus. None where the server does not count.

pub fn library_modified( &self, since: Option<i64>, ) -> Result<Option<i64>, SubsonicError>

When the server’s library last changed, in milliseconds, as getIndexes reports it. Asked since the version last seen, so a library that has not moved answers with the timestamp alone. None where the server gives none.

pub fn search(&self, query: &str) -> Result<SubsonicSearchResult, SubsonicError>

Search for tracks/albums/artists.

pub fn scrobble( &self, track_id: &str, heard_at_ms: u64, ) -> Result<(), SubsonicError>

Scrobble a play that counts, dated to heard_at_ms (ms since the epoch the listen began).

pub fn report_playback( &self, track_id: &str, state: PlaybackReportState, position_ms: u64, ) -> Result<(), SubsonicError>

Tell the server where playback of a track stands, so its Now Playing follows pauses, seeks and stops.

Uses OpenSubsonic’s reportPlayback where the server offers it, always with ignoreScrobble: koan decides what counts as a play and scrobbles it itself. Elsewhere only playing can be said, as a now-playing scrobble from position (seconds, as Navidrome reads it); a pause or a stop has no equivalent there and is not sent.

pub fn star(&self, track_id: &str) -> Result<(), SubsonicError>

Star (favourite) a track on the server.

pub fn unstar(&self, track_id: &str) -> Result<(), SubsonicError>

Unstar (unfavourite) a track on the server.

pub fn get_starred_all(&self) -> Result<SubsonicStarred, SubsonicError>

Everything the server has starred: songs, albums and artists.

Subsonic returns all three from one call, so asking for songs alone leaves a starred album invisible to us for no saving.

pub fn star_album(&self, album_id: &str) -> Result<(), SubsonicError>

Star an album. Subsonic keys this off a different parameter to a song — id would be read as a track and silently star nothing.

pub fn unstar_album(&self, album_id: &str) -> Result<(), SubsonicError>

pub fn star_artist(&self, artist_id: &str) -> Result<(), SubsonicError>

pub fn unstar_artist(&self, artist_id: &str) -> Result<(), SubsonicError>

pub fn create_share( &self, ids: &[&str], description: Option<&str>, ) -> Result<SubsonicShare, SubsonicError>

Create a sharing link for one or more resources (songs, albums, etc). Returns the created share including its ID which forms the public URL.

pub fn get_similar_songs( &self, song_id: &str, count: usize, ) -> Result<Vec<SubsonicSong>, SubsonicError>

Get similar songs for a track (Subsonic getSimilarSongs2 endpoint). Returns up to count similar songs based on the server’s algorithm.

pub fn get_playlists(&self) -> Result<Vec<SubsonicPlaylist>, SubsonicError>

Every playlist the server will show this user, without their contents.

pub fn get_playlist( &self, id: &str, ) -> Result<SubsonicPlaylistFull, SubsonicError>

One playlist, with its songs in order.

pub fn create_playlist( &self, playlist_id: Option<&str>, name: &str, song_ids: &[String], ) -> Result<Option<SubsonicPlaylistFull>, SubsonicError>

Create a playlist, or replace an existing one’s contents wholesale.

createPlaylist is the only Subsonic call that can set a playlist’s order: updatePlaylist appends and removes by index, which cannot express a reorder. Passing playlist_id turns this into “these songs, in this order, from now on”, which is exactly what koan has after any edit — so every push takes this path and there is one way for the two sides to disagree instead of five.

pub fn update_playlist( &self, id: &str, name: Option<&str>, comment: Option<&str>, public: Option<bool>, ) -> Result<(), SubsonicError>

Change what can be changed without touching the song list.

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

pub fn koan_users(&self) -> Result<Vec<KoanUser>, SubsonicError>

pub fn koan_create_user( &self, username: &str, role: &str, ) -> Result<KoanInvite, SubsonicError>

role is admin, user or readonly.

pub fn koan_invite( &self, username: &str, reset: bool, ) -> Result<KoanInvite, SubsonicError>

With reset, the account gets a new password, which comes back with the invite, and its devices sign out.

pub fn koan_revoke_own_key(&self) -> Result<(), SubsonicError>

Revoke the API key this client signs in with (koanRevokeKey).

pub fn koan_set_user_role( &self, username: &str, role: &str, ) -> Result<(), SubsonicError>

pub fn koan_delete_user(&self, username: &str) -> Result<(), SubsonicError>

pub fn koan_command(&self, to: &str, command: &str) -> Result<(), SubsonicError>

Have the server hand command (a link command, as JSON) to the device to on this account: a koan extension, koanDevices.

pub fn auth(&self) -> &SubsonicAuth

pub fn base_url(&self) -> &str

The configured server base URL (for constructing share links etc).