pub struct CiderClient { /* private fields */ }Expand description
Async client for the Cider music player REST API.
Communicates with Cider’s local HTTP server (default http://127.0.0.1:10767)
to control playback, manage the queue, and query track information.
§Construction
use cider_api::CiderClient;
// Default (localhost:10767, no auth)
let client = CiderClient::new();
// Custom port
let client = CiderClient::with_port(9999);
// With authentication
let client = CiderClient::new().with_token("my-token");The client is cheaply Cloneable — it shares an inner connection pool.
§Errors
All async methods return Result<_, CiderError>. Common error cases:
CiderError::Http— network or connection failure.CiderError::Unauthorized— invalid API token (HTTP 401/403).CiderError::Api— unexpected response from Cider.
Implementations§
Source§impl CiderClient
impl CiderClient
Sourcepub fn with_port(port: u16) -> Self
pub fn with_port(port: u16) -> Self
Create a new client targeting http://127.0.0.1:{port}.
§Panics
Panics if the underlying HTTP client cannot be constructed (only possible if TLS initialisation fails at the OS level).
Sourcepub fn with_token(self, token: impl Into<String>) -> Self
pub fn with_token(self, token: impl Into<String>) -> Self
Attach an API token for authentication.
The token is sent in the apptoken header on every request.
Generate one in Cider under Settings > Connectivity > Manage External
Application Access.
Sourcepub async fn is_active(&self) -> Result<(), CiderError>
pub async fn is_active(&self) -> Result<(), CiderError>
Check that Cider is running and the RPC server is reachable.
Sends GET /active — Cider responds with 204 No Content if alive.
§Errors
CiderError::Unauthorizedif the token is wrong.CiderError::Apiif the connection is refused or times out.
Sourcepub async fn is_playing(&self) -> Result<bool, CiderError>
pub async fn is_playing(&self) -> Result<bool, CiderError>
Check whether music is currently playing.
Sends GET /is-playing.
§Errors
Returns CiderError if the request fails or the response cannot be parsed.
Sourcepub async fn now_playing(&self) -> Result<Option<NowPlaying>, CiderError>
pub async fn now_playing(&self) -> Result<Option<NowPlaying>, CiderError>
Get the currently playing track.
Returns None if nothing is loaded. The returned NowPlaying includes
both Apple Music catalog metadata and live playback state
(current_playback_time, remaining_time, etc.).
Sends GET /now-playing.
§Errors
Returns CiderError on network failure. Returns Ok(None) (not an
error) if nothing is playing or the response cannot be parsed.
Sourcepub async fn play(&self) -> Result<(), CiderError>
pub async fn play(&self) -> Result<(), CiderError>
Resume playback.
If nothing is loaded, the behaviour set under Settings > Play Button on Stopped Action takes effect.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn pause(&self) -> Result<(), CiderError>
pub async fn pause(&self) -> Result<(), CiderError>
Pause the current track. No-op if already paused or nothing is playing.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn play_pause(&self) -> Result<(), CiderError>
pub async fn play_pause(&self) -> Result<(), CiderError>
Toggle between playing and paused.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn stop(&self) -> Result<(), CiderError>
pub async fn stop(&self) -> Result<(), CiderError>
Stop playback and unload the current track. Queue items are kept.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn next(&self) -> Result<(), CiderError>
pub async fn next(&self) -> Result<(), CiderError>
Skip to the next track in the queue.
Respects autoplay status if the queue is empty.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn previous(&self) -> Result<(), CiderError>
pub async fn previous(&self) -> Result<(), CiderError>
Go back to the previously played track (from playback history).
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn seek(&self, position_secs: f64) -> Result<(), CiderError>
pub async fn seek(&self, position_secs: f64) -> Result<(), CiderError>
Seek to a position in the current track.
§Arguments
position_secs— target offset in seconds (e.g.30.0).
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn seek_ms(&self, position_ms: u64) -> Result<(), CiderError>
pub async fn seek_ms(&self, position_ms: u64) -> Result<(), CiderError>
Convenience wrapper for seek that accepts milliseconds.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn play_url(&self, url: &str) -> Result<(), CiderError>
pub async fn play_url(&self, url: &str) -> Result<(), CiderError>
Start playback of an Apple Music URL.
The URL can be obtained from Share > Apple Music in Cider or the Apple Music web player.
§Arguments
url— e.g."https://music.apple.com/ca/album/…/1719860281"
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn play_item(
&self,
item_type: &str,
id: &str,
) -> Result<(), CiderError>
pub async fn play_item( &self, item_type: &str, id: &str, ) -> Result<(), CiderError>
Start playback of an item by Apple Music type and catalog ID.
§Arguments
item_type— Apple Music type:"songs","albums","playlists", etc.id— catalog ID as a string (e.g."1719861213").
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn play_item_href(&self, href: &str) -> Result<(), CiderError>
pub async fn play_item_href(&self, href: &str) -> Result<(), CiderError>
Start playback of an item by its Apple Music API href.
§Arguments
href— API path, e.g."/v1/catalog/ca/songs/1719861213".
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn play_next(
&self,
item_type: &str,
id: &str,
) -> Result<(), CiderError>
pub async fn play_next( &self, item_type: &str, id: &str, ) -> Result<(), CiderError>
Add an item to the start of the queue (plays next).
§Arguments
item_type—"songs","albums", etc.id— catalog ID as a string.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn play_later(
&self,
item_type: &str,
id: &str,
) -> Result<(), CiderError>
pub async fn play_later( &self, item_type: &str, id: &str, ) -> Result<(), CiderError>
Add an item to the end of the queue (plays last).
§Arguments
item_type—"songs","albums", etc.id— catalog ID as a string.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn get_queue(&self) -> Result<Vec<QueueItem>, CiderError>
pub async fn get_queue(&self) -> Result<Vec<QueueItem>, CiderError>
Get the current playback queue.
Returns a Vec<QueueItem> that includes history items, the currently
playing track, and upcoming items. Use QueueItem::is_current to
find the active track.
Returns an empty Vec if the queue is empty or the response format is
unexpected.
§Errors
Returns CiderError on network failure. Returns Ok(vec![]) (not an
error) if the queue is empty or the format is unrecognised.
Sourcepub async fn queue_move_to_position(
&self,
start_index: u32,
destination_index: u32,
) -> Result<(), CiderError>
pub async fn queue_move_to_position( &self, start_index: u32, destination_index: u32, ) -> Result<(), CiderError>
Move a queue item from one position to another.
Both indices are 1-based. The queue includes history items, so the first visible “Up Next” item may not be at index 1.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn queue_remove_by_index(&self, index: u32) -> Result<(), CiderError>
pub async fn queue_remove_by_index(&self, index: u32) -> Result<(), CiderError>
Remove a queue item by its 1-based index.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn clear_queue(&self) -> Result<(), CiderError>
pub async fn clear_queue(&self) -> Result<(), CiderError>
Clear all items from the queue.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn get_volume(&self) -> Result<f32, CiderError>
pub async fn get_volume(&self) -> Result<f32, CiderError>
Get the current volume (0.0 = muted, 1.0 = full).
§Errors
Returns CiderError if the request fails or the response cannot be parsed.
Sourcepub async fn set_volume(&self, volume: f32) -> Result<(), CiderError>
pub async fn set_volume(&self, volume: f32) -> Result<(), CiderError>
Set the volume. Values are clamped to 0.0..=1.0.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn add_to_library(&self) -> Result<(), CiderError>
pub async fn add_to_library(&self) -> Result<(), CiderError>
Add the currently playing track to the user’s library.
No-op if the track is already in the library.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn set_rating(&self, rating: i8) -> Result<(), CiderError>
pub async fn set_rating(&self, rating: i8) -> Result<(), CiderError>
Rate the currently playing track.
-1— dislike0— remove rating1— like
The value is clamped to -1..=1.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn get_repeat_mode(&self) -> Result<u8, CiderError>
pub async fn get_repeat_mode(&self) -> Result<u8, CiderError>
Get the current repeat mode.
0— off1— repeat this song2— repeat all
§Errors
Returns CiderError if the request fails or the response cannot be parsed.
Sourcepub async fn toggle_repeat(&self) -> Result<(), CiderError>
pub async fn toggle_repeat(&self) -> Result<(), CiderError>
Cycle repeat mode: repeat one > repeat all > off.
§Errors
Returns CiderError if the request fails or the server rejects it.
Sourcepub async fn get_shuffle_mode(&self) -> Result<u8, CiderError>
pub async fn get_shuffle_mode(&self) -> Result<u8, CiderError>
Get the current shuffle mode (0 = off, 1 = on).
§Errors
Returns CiderError if the request fails or the response cannot be parsed.
Sourcepub async fn toggle_shuffle(&self) -> Result<(), CiderError>
pub async fn toggle_shuffle(&self) -> Result<(), CiderError>
Sourcepub async fn get_autoplay(&self) -> Result<bool, CiderError>
pub async fn get_autoplay(&self) -> Result<bool, CiderError>
Get the current autoplay status (true = on).
§Errors
Returns CiderError if the request fails or the response cannot be parsed.
Sourcepub async fn toggle_autoplay(&self) -> Result<(), CiderError>
pub async fn toggle_autoplay(&self) -> Result<(), CiderError>
Sourcepub async fn amapi_run_v3(&self, path: &str) -> Result<Value, CiderError>
pub async fn amapi_run_v3(&self, path: &str) -> Result<Value, CiderError>
Execute a raw Apple Music API request via Cider’s passthrough.
Sends POST /api/v1/amapi/run-v3 with the given path, and returns
the raw JSON response from Apple Music.
§Arguments
path— Apple Music API path, e.g."/v1/me/library/songs"or"/v1/catalog/us/search?term=flume&types=songs".
§Errors
Returns CiderError if the request fails or the response cannot be parsed.
Trait Implementations§
Source§impl Clone for CiderClient
impl Clone for CiderClient
Source§fn clone(&self) -> CiderClient
fn clone(&self) -> CiderClient
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more