cider-api 0.1.1

Async Rust client for the Cider music player REST API.

Cider exposes a local HTTP API (default port 10767) for controlling playback, managing the queue, and querying track information. This crate provides a fully typed, async client built on reqwest.

Quick start

use cider_api::CiderClient;

#[tokio::main]
async fn main() -> Result<(), cider_api::CiderError> {
    let client = CiderClient::new();

    // Check if Cider is running
    client.is_active().await?;

    // Get the currently playing track
    if let Some(track) = client.now_playing().await? {
        println!("{} — {}", track.name, track.artist_name);
        println!("Album: {}", track.album_name);
        println!("Artwork: {}", track.artwork_url(600));
        println!(
            "Position: {:.1}s / {:.1}s",
            track.current_playback_time,
            track.duration_in_millis as f64 / 1000.0,
        );

        if !track.audio_traits.is_empty() {
            println!("Audio: {}", track.audio_traits.join(", "));
        }
    }

    // Control playback
    client.pause().await?;
    client.seek_ms(30_000).await?;
    client.play().await?;

    Ok(())
}

Authentication

If Cider has API authentication enabled, pass the token via with_token:

let client = CiderClient::new().with_token("your-api-token");

The token is sent in the apitoken header on every request (no Bearer prefix). Generate one in Cider under Settings > Connectivity > Manage External Application Access.

API coverage

Response types

All response types are fully typed with serde and match the Cider RPC documentation.

NowPlaying

Returned by now_playing(). Contains Apple Music catalog metadata plus live playback state.

QueueItem

Returned by get_queue(). Includes track attributes, streaming internals, and container info.

Artwork

Use artwork.url_for_size(300) to get a resolved URL.

Error handling

All async methods return Result<_, CiderError>. Match on variants to handle specific failures:

use cider_api::{CiderClient, CiderError};

async fn example() {
    let client = CiderClient::new();
    match client.is_active().await {
        Ok(()) => println!("Cider is running"),
        Err(CiderError::Unauthorized) => println!("Bad API token"),
        Err(CiderError::Http(e)) if e.is_connect() => println!("Cider not running"),
        Err(e) => println!("Other error: {e}"),
    }
}

Prerequisites

• Cider running with an Apple Music subscription
• API enabled in Cider: Settings > Connectivity > Manage External Application Access