Subsonic API client offering full OpenSubsonic coverage, token/API-key authentication, library browsing, search, playlists, streaming and cover-art URLs, scrobbling, rating, and robust error handling.
A Kotlin Multiplatform client library for the Subsonic API.
Add the following to your gradle/libs.versions.toml:
[versions]
subsonicKotlin = "x.y.z" # Replace with latest version
[libraries]
subsonicClient = { module = "dev.zt64.subsonic:subsonic-client", version.ref = "subsonicKotlin" }
Then add the dependency to your module's build.gradle.kts:
dependencies {
implementation(libs.subsonicClient)
}
[!NOTE] A Ktor engine implementation must be included in your dependencies for the client to function.
// Using a username and password
val client = SubsonicClient(
baseUrl = "https://your-server.com",
auth = SubsonicAuth.Token(
username = "your-username",
password = "your-password"
)
)
// Using an API key (not universally supported, check your servers compatible authentication)
val client = SubsonicClient(
baseUrl = "https://your-server.com",
auth = SubsonicAuth.Key(apiKey = "your-api-key")
)
try {
val album = client.getAlbum(id = "invalid-id")
} catch (e: SubsonicException) {
println("${e.code}: ${e.message}")
}
// Use a specific Ktor engine
val client = SubsonicClient(
baseUrl = "https://your-server.com",
auth = SubsonicAuth.Token(username = "user", password = "pass")
) {
// Additional Ktor client configuration
install(HttpTimeout) {
requestTimeoutMillis = 30000
}
}
This library targets Subsonic API version 1.16.1 and supports the Open Subsonic specification. It has been tested with:
Most endpoints should work with any Subsonic-compatible server, though some features may vary by implementation.
Contributions are welcome and encouraged! Please feel free to submit issues or pull requests.
This project is licensed under the MIT License.
// Test connectivity
client.ping()
// Browse library
val artists = client.getArtists()
val artist = client.getArtist(id = "123")
val album = client.getAlbum(id = "456")
// Search
val results = client.searchID3(query = "Beatles")
// Playlists
val playlists = client.getPlaylists()
val newPlaylist = client.createPlaylist(name = "My Mix", songIds = listOf("1", "2", "3"))
// Streaming
val streamUrl = client.getStreamUrl(id = "song-123", maxBitRate = 320)
val coverArtUrl = client.getCoverArtUrl(id = album.coverArt, size = "500")
// Star/Rate
client.star("song-123")
client.setRating(id = "song-123", rating = 5)
// Scrobble
client.scrobble(id = "song-123")
Surfaced from shared tags and platforms — no rankings paid for.