subsonic-kotlin
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.
- Full OpenSubsonic API coverage (based on API version 1.16.1)
- Kotlin Multiplatform support (JVM, Android, Linux, Windows, macOS, iOS, tvOS, watchOS, JS, Wasm)
- Token-based and API key authentication
- Built on Ktor with kotlinx.serialization
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")
)// 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")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.
A Kotlin Multiplatform client library for the Subsonic API.
- Full OpenSubsonic API coverage (based on API version 1.16.1)
- Kotlin Multiplatform support (JVM, Android, Linux, Windows, macOS, iOS, tvOS, watchOS, JS, Wasm)
- Token-based and API key authentication
- Built on Ktor with kotlinx.serialization
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")
)// 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")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.