opensubsonic 0.1.0

Complete async Rust client for the OpenSubsonic/Subsonic REST API
Documentation

opensubsonic-rs

Crates.io Docs.rs CI License: MIT License: Apache-2.0

Complete async Rust client for the OpenSubsonic / Subsonic REST API.

Supports Subsonic API v1.16.1 and OpenSubsonic extensions. Works with Navidrome, Gonic, Ampache, and any other Subsonic-compatible server.

Quick start

use opensubsonic::{Client, Auth};

#[tokio::main]
async fn main() -> Result<(), opensubsonic::Error> {
    let client = Client::new(
        "https://music.example.com",
        "admin",
        Auth::token("password"),
    )?;

    // Verify connectivity.
    client.ping().await?;

    // Browse artists.
    let artists = client.get_artists(None).await?;
    for index in &artists.index {
        for artist in &index.artist {
            println!("{}", artist.name);
        }
    }

    // Search for songs.
    let results = client.search3("bohemian", None, None, None, None, None, None, None).await?;
    for song in &results.song {
        println!("{} - {}", song.artist.as_deref().unwrap_or("?"), song.title);
    }

    // Get a streaming URL (no HTTP request, just builds the URL).
    let url = client.stream_url("song-id-123", None, None)?;
    println!("Stream: {url}");

    Ok(())
}

Authentication

Two methods are supported:

// Token-based (recommended) — sends MD5(password + salt) + salt
let auth = Auth::token("my-password");

// Plain text (legacy) — sends hex-encoded password
let auth = Auth::plain("my-password");

API coverage

All ~80 endpoints from Subsonic API v1.16.1 are implemented, plus OpenSubsonic extensions:

Category Endpoints
System ping, getLicense, getOpenSubsonicExtensions, tokenInfo
Browsing getMusicFolders, getIndexes, getMusicDirectory, getGenres, getArtists, getArtist, getAlbum, getSong, getVideos, getArtistInfo/2, getAlbumInfo/2, getSimilarSongs/2, getTopSongs
Lists getAlbumList/2, getRandomSongs, getSongsByGenre, getNowPlaying, getStarred/2
Searching search, search2, search3
Playlists getPlaylists, getPlaylist, createPlaylist, updatePlaylist, deletePlaylist
Media Retrieval stream, download, hls, getCaptions, getCoverArt, getLyrics, getLyricsBySongId, getAvatar
Media Annotation star, unstar, setRating, scrobble
Sharing getShares, createShare, updateShare, deleteShare
Podcast getPodcasts, getNewestPodcasts, getPodcastEpisode, refreshPodcasts, createPodcastChannel, deletePodcastChannel, deletePodcastEpisode, downloadPodcastEpisode
Jukebox jukeboxControl
Internet Radio getInternetRadioStations, createInternetRadioStation, updateInternetRadioStation, deleteInternetRadioStation
Chat getChatMessages, addChatMessage
User Management getUser, getUsers, createUser, updateUser, deleteUser, changePassword
Bookmarks getBookmarks, createBookmark, deleteBookmark, getPlayQueue, savePlayQueue, getPlayQueueByIndex, savePlayQueueByIndex
Scanning getScanStatus, startScan
Transcoding getTranscodeDecision, getTranscodeStream (OpenSubsonic)

Builder options

let client = Client::new("https://music.example.com", "admin", Auth::token("pass"))?
    .with_client_name("my-app")        // Custom client identifier (default: "opensubsonic-rs")
    .with_api_version("1.15.0")        // Override protocol version (default: "1.16.1")
    .with_http_client(custom_reqwest);  // Inject a custom reqwest::Client

URL builders

Some methods build URLs without making HTTP requests, useful for passing to audio players:

let stream_url = client.stream_url("song-id", None, None)?;
let cover_url = client.cover_art_url("cover-id", Some(300))?;
let hls_url = client.hls_url("video-id", None, None)?;

Dependencies

  • reqwest 0.13 (async HTTP, rustls TLS)
  • serde / serde_json (JSON serialization)
  • tokio (async runtime, dev-dependency)

Minimum supported Rust version: 1.85 (edition 2024).

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.