Scrobble API

Scrobble playback history to services like Last.fm or ListenBrainz.

Implement ScrobbleAPI to report playback history to scrobbling services. Include "SCROBBLE" in plugin.json abilities.

Interface

interface ScrobbleAPI : ZiplineService {
    suspend fun scrobble(track: ScrobbleTrack)
}

Spotube calls scrobble() when a track finishes playing or meets the scrobble threshold (typically 50% played or 4 minutes, whichever comes first).

ScrobbleTrack

data class ScrobbleTrack(
    val timestamp: Long,              // Unix timestamp
    val trackId: String,
    val artistId: String,
    val albumId: String?,
    val trackName: String,
    val artistName: String,
    val albumName: String?,
    val streamingProvider: String,    // e.g. "youtube"
    val durationMs: Long?,
)

Implementation guide

Most scrobbling services (Last.fm, ListenBrainz) use a similar API pattern: authenticate once to get a session key (store it in PersistedStorageAPI), then send POST requests with track details and the session key.

For a complete working implementation, see the example's RealScrobbleAPI.

Binding

import dev.krtirtho.plugin_interfaces.plugin_apis.scrobble.ScrobbleAPI
import dev.krtirtho.plugin_interfaces.plugin_apis.scrobble.ScrobbleAPI_SERVICE_NAME

zipline.bind<ScrobbleAPI>(ScrobbleAPI_SERVICE_NAME, RealScrobbleAPI())