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 scrobble_many(&self, plays: &[(&str, i64)]) -> Result<(), SubsonicError>

Scrobble several plays in one request, (track id, started at ms).

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_pair_info(&self, pair: &str) -> Result<KoanPair, SubsonicError>

The device waiting on pairing pair, an id or a code, and where it asked from (koanPairInfo).

pub fn koan_pair_approve( &self, pair: &str, decline: bool, ) -> Result<String, SubsonicError>

Sign the device waiting on pair in as this account, or with decline, turn it away (koanPairApprove). Answers with its name.

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

Give username a password (koanSetUserPassword): an admin’s call for another account. Its devices sign out.

pub fn koan_change_own_password( &self, current: &str, password: &str, device: &str, ) -> Result<KoanJoined, SubsonicError>

Change this account’s own password, proving the current one. Every key the account had is revoked, this client’s included, so the server answers with a new one named device.

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

Where assistants connect to this server, and the page saying how: koan servers offering koanMcp.

pub fn koan_api_keys(&self) -> Result<Vec<KoanApiKey>, SubsonicError>

pub fn koan_create_api_key( &self, name: &str, ) -> Result<KoanApiKey, SubsonicError>

A new key named name, with the key itself, which is never shown again.

pub fn koan_revoke_api_key(&self, id: i64) -> Result<(), SubsonicError>

pub fn koan_app_passwords(&self) -> Result<Vec<KoanAppPassword>, SubsonicError>

pub fn koan_create_app_password( &self, name: &str, ) -> Result<KoanAppPassword, SubsonicError>

A new app password named name, with the password itself, which is never shown again.

pub fn koan_revoke_app_password(&self, id: i64) -> Result<(), SubsonicError>

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, ack: Option<u64>, ) -> Result<Option<AckOutcome>, SubsonicError>

Have the server hand command (a link command, as JSON) to the device to on this account: a koan extension, koanDevices. Ask the server to get command (JSON) to the device to. With ack, a server offering koanAck waits a moment for the device and says how it went; one that does not answers None.

pub fn koan_history( &self, since: HistoryCursor, count: u32, ) -> Result<KoanHistoryPage, SubsonicError>

The account’s plays and forgettings after since, at most count of each.

pub fn koan_forget_plays( &self, plays: &[(&str, i64)], ) -> Result<(), SubsonicError>

Forget these plays, (track id, started at ms), for every device on the account.

pub fn koan_forget_plays_through(&self, at_ms: i64) -> Result<(), SubsonicError>

Forget every play up to at_ms, for every device on the account.

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

Where the account’s plays are forwarded.

pub fn koan_scrobbling_connect( &self, token: &str, ) -> Result<KoanScrobbling, SubsonicError>

Connect the account’s ListenBrainz with its user token, which the server checks with ListenBrainz before keeping.

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

pub fn koan_dsp_profiles( &self, since: i64, ) -> Result<KoanDspProfiles, SubsonicError>

The account’s profiles changed after revision since.

pub fn koan_dsp_profile_save( &self, uid: &str, edited_at: i64, doc: &str, ) -> Result<KoanDspSaved, SubsonicError>

Keep doc as profile uid’s, edited at edited_at (ms).

pub fn koan_dsp_profile_delete( &self, uid: &str, edited_at: i64, ) -> Result<KoanDspSaved, SubsonicError>

pub fn koan_dsp_deleted( &self, ) -> Result<Vec<KoanDspDeletedProfile>, SubsonicError>

The account’s profiles deleted in the last thirty days: servers offering koanDspDeleted.

pub fn koan_dsp_restore(&self, uid: &str) -> Result<KoanDspSaved, SubsonicError>

Save deleted profile uid again from the server’s copy, as a new edit.

pub fn koan_dsp_dismiss(&self, output: &str) -> Result<(), SubsonicError>

Turn the AutoEQ suggestion for output down on every device.

pub fn koan_dsp_file(&self, sha256: &str) -> Result<Vec<u8>, SubsonicError>

A file a profile names, by its SHA-256.

pub fn koan_dsp_upload( &self, sha256: &str, data: Vec<u8>, ) -> Result<(), SubsonicError>

Send a file a saved profile names and the server lacks.

pub fn get_play_queue( &self, by_index: bool, ) -> Result<Option<SavedPlayQueue>, SubsonicError>

The account’s saved play queue, None when there is none. by_index for a server listing indexBasedQueue.

pub fn save_play_queue( &self, song_ids: &[String], current: Option<usize>, position_ms: u64, by_index: bool, form: bool, client: &str, ) -> Result<(), SubsonicError>

Replace the account’s saved play queue with song_ids, position_ms into the entry at current, as the client client: what a later get_play_queue reports as changedBy. form posts it as a form, for a server listing formPost, since a long queue does not fit in a URL; otherwise it goes in the query. by_index for a server listing indexBasedQueue; otherwise the current entry goes by its song’s id, which is ambiguous for a song queued twice.

pub fn auth(&self) -> &SubsonicAuth

pub fn base_url(&self) -> &str

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

Trait Implementations

impl Remote for SubsonicClient

fn changes(&self, since: i64) -> Result<KoanDspProfiles, SubsonicError>

fn save( &self, uid: &str, edited_at: i64, doc: &str, ) -> Result<KoanDspSaved, SubsonicError>

fn delete( &self, uid: &str, edited_at: i64, ) -> Result<KoanDspSaved, SubsonicError>

fn dismiss(&self, output: &str) -> Result<(), SubsonicError>

fn file(&self, sha256: &str) -> Result<Vec<u8>, SubsonicError>

fn upload(&self, sha256: &str, data: Vec<u8>) -> Result<(), SubsonicError>