Unofficial YouTube Music / Spotify Premium client for Android, built in Liquid Glass. Audio effects, Spotify Connect, listening history, 8 languages. Rust core on librespot.
Kotlin alternativeandroidandroid-applicationclientglassmorphisminnertubelibrespotliquid-glassspotifyspotify-connectspotifyapiyoutube-musicyoutube-playerytdlnis
package dev.lelonio.square.playback
import android.os.Looper
import android.net.Uri
import androidx.media3.common.MediaItem
import androidx.media3.common.MediaMetadata
import dev.lelonio.square.ui.EXTRA_CONTEXT_LABEL
import androidx.media3.common.Player
import androidx.media3.common.SimpleBasePlayer
import androidx.media3.common.util.UnstableApi
import com.google.common.util.concurrent.Futures
import com.google.common.util.concurrent.ListenableFuture
import dev.lelonio.square.nativecore.NativeBridge
import kotlinx.coroutines.cancel
import kotlinx.coroutines.flow.distinctUntilChanged
import kotlinx.coroutines.flow.drop
import kotlinx.coroutines.launch
import dev.lelonio.square.nativecore.NativeEvents
/**
* Adapts the native librespot engine to the Media3 [Player] interface.
*
* Extending [SimpleBasePlayer] rather than implementing [Player] directly means
* Media3 owns the listener bookkeeping, command masking and threading rules; we
* only describe the current state and handle the four operations the engine
* actually supports. Everything the engine does not support is simply left out
* of the available-commands set, so the notification and any connected
* controller grey out the right buttons instead of failing at runtime.
*
* All mutation happens on [applicationLooper]; native events are marshalled onto
* it before touching state.
*/
@UnstableApi
class LibrespotPlayer(
context: android.content.Context,
looper: Looper,
private val queue: PlayQueue,
/**
* Applies tempo and pitch to the output. Passed in rather than reached for
* because the audio device belongs to the service, not to this adapter.
*/
private val onSpeedAndPitch: (speed: Float, pitch: Float) -> Unit,
/**
* Fades the output down, runs the load, and lets it come back up.
*
* Track changes go through here so a skip dissolves instead of cutting.
* Note this is a fade *through silence*, not a true crossfade: librespot
* decodes one track at a time and the sink carries a single stream, so
* there is no second source to overlap with. Overlapping would mean running
* two engines and mixing them.
*/
private val fadeOutThen: (() -> Unit) -> Unit,
private val fadeIn: () -> Unit,
/**
* Whether the engine dissolves a change of track itself.
*
* When it does, the output must not be touched: the fade above ramps this
* app's own audio track down and *throws away* what the engine produces
* until it is brought back up, which is precisely the second of music the
* dissolve is made of. What was heard was the silence of this fade, then
* the tail of the old song arriving late, then the new one.
*/
private val dissolves: () -> Boolean,
/**
* Told when playback starts and stops.
*
* The output needs this because the reverb sits on the global mix; see
* AudioOutput.setPlaybackActive.
*/
private val onPlaybackActive: (Boolean) -> Unit,
/**
* Holds the reverb down while the music is ducked.
*
* Separate from the volume below because it has to be: the room is an
* effect on the output mix, and its send is fed before the level this
* player sets. See AudioOutput.duckReverb.
*/
private val onDuckReverb: (Float) -> Unit,
) : SimpleBasePlayer(looper), NativeEvents {
/**
* Hands the current queue to the engine, with the fade around it.
*
* The whole list, not the current track: the engine now drives playback
* through Spotify Connect, where the queue is part of the state published
* to the account. Loading one track at a time would show every other device
* a queue with nothing in it, and would take the end-of-track advance away
* from the side that owns it.
*/
private fun pushQueue(startPlaying: Boolean, positionMs: Int = 0) {
val uris = queue.items.map { it.uri }
if (uris.isEmpty()) return
// From here until the engine is on this queue, what it says it is
// playing is the past; see [ownQueuePending].
ownQueuePending = true
handler.removeCallbacks(giveUpOnOwnQueue)
handler.postDelayed(giveUpOnOwnQueue, OWN_QUEUE_MS)
val index = queue.currentIndex
val contextUri = queue.contextUri.orEmpty()
// The DJ's lines are said only over the DJ's own queue; see SpotifyDj.
NativeBridge.djSetActive(
dev.lelonio.square.backend.spotify.SpotifyDj.enabled &&
dev.lelonio.square.backend.spotify.SpotifyDj.isDj(contextUri),
)
// Never as a context, whatever it is.
//
// Handing the engine a playlist URI asks Spotify to resolve the list
// itself, and its copy is not the one on screen: it steps over tracks
// the account is not offered here, quietly and without a word in the
// log, so a song sitting plainly in the list is jumped as if it were
// not there. Liked Songs hit this first and was fixed on its own; the
// same thing happens to any playlist.
//
// What goes over instead is this list, in this order, published under
// the playlist it came from — see native/src/engine.rs, which files it
// with the context so the account still records the listen against the
// playlist and other devices still name it. What is lost is Spotify's
// own ordering of a list the app has already read, which is nothing,
// and what is gained is that the queue plays what it shows.
val asContext = false
// A track picked from a list is not one the engine could see coming,
// and this used to fade the output down over its own half of the
// dissolve while the engine went looking for the context. Two fades
// over one change: the output came back up the moment the load was
// sent, and the engine's tail, which had only just started going down,
// was heard again underneath the new song rising. The engine fades the
// song it is leaving whether or not it has anywhere to go yet, so this
// one leaves the output alone; see handle_command_load in player.rs.
changing {
// Back on the player's looper before anything is read or called.
// The fade runs on its own thread, and everything here — the queue,
// playWhenReady, the engine's own idea of what is loaded — belongs
// to the looper. Reading it from the fade thread is a race, and a
// race in the middle of a track change is exactly the rare crash
// that skipping quickly could produce.
// A load is the one command with no way around the Connect device,
// so when that is gone the track simply never changes. Build a new
// one first and load on the other side of it.
withDevice {
if (released) return@withDevice
// Read now, not when this was scheduled. The fade takes a
// moment, and a tap on a track while paused arrives as "load
// this" followed immediately by "play": with the flag frozen at
// schedule time the load went out as paused, the play landed
// before it, and the track sat there selected and silent.
val wanted = startPlaying || playWhenReady || wantPlay
runCatching {
NativeBridge.loadQueue(
uris,
index,
wanted,
positionMs,
contextUri,
playAsContext = asContext,
)
}
.onFailure { android.util.Log.e("SquarePlayer", "load failed: ${it.message}") }
.onSuccess { engineQueueStale = false }
if (wanted && !dissolves()) fadeIn()
}
}
}
/**
* Runs a change of track, through the output fade or straight through.
*
* Straight through while the engine dissolves: what it mixes has to reach
* the speaker to be heard at all. See [dissolves].
*/
private fun changing(action: () -> Unit) {
if (dissolves()) action() else fadeOutThen(action)
}
/**
* Built here rather than injected because its callbacks have to reach back
* into this player, and passing it in would need the two to be constructed
* in a cycle.
*/
private val focus = AudioFocusController(
context,
onPause = { engine("pause") { NativeBridge.pause() } },
onResume = { engine("play") { NativeBridge.play() } },
onDuck = ::applyDuck,
pauseOnLoss = {
(context.applicationContext as? dev.lelonio.square.SquareApplication)
?.preferences?.pauseForOtherApps?.value != false
},
)
/** Volume before ducking, so it can be put back exactly. */
private var volumeBeforeDuck: Int? = null
/** Mirrors what the engine last told us. Only touched on the app looper. */
private var playbackState: @Player.State Int = Player.STATE_IDLE
private var playWhenReady = false
private var positionMs = 0L
private var released = false
private var repeatMode: @Player.RepeatMode Int = Player.REPEAT_MODE_OFF
/**
* Shuffle as a *mode*, held here rather than inferred from the queue.
*
* The queue loses its shuffled order whenever it is replaced, and every
* play action replaces it — so reading the flag off the queue turned shuffle
* off the moment the user picked a track. Shuffle belongs to the player and
* is re-applied to each new queue by [reapplyShuffle].
*/
private var shuffleEnabled = false
private var playbackParameters = androidx.media3.common.PlaybackParameters.DEFAULT
/** See [playlistSnapshot]; null means "rebuild on next read". */
private var cachedPlaylist: List<MediaItemData>? = null
private val handler = android.os.Handler(looper)
/**
* The quality the listener asked for, which decides whether the one below
* is allowed to have an opinion.
*/
private val quality =
(context.applicationContext as dev.lelonio.square.SquareApplication).quality
/**
* Follows what the connection can actually carry; see [BandwidthWatch].
*
* Only while the setting is automatic. On a fixed choice the listener has
* said which file they want and a stall is their business, not ours.
*/
private val bandwidth = BandwidthWatch { kbps ->
if (quality.quality.value == dev.lelonio.square.data.Quality.Auto) {
runCatching { dev.lelonio.square.nativecore.NativeBridge.setBitrate(kbps) }
}
}
/**
* Fires when the music should have reported progress and did not.
*
* Position arrives once a second from the decoding loop, so silence there
* while the player still means to be playing is the buffer having run dry.
* It is the one measurement of a connection that cannot be argued with.
*/
private val stallWatch = Runnable {
// Not while a track is being fetched: the decoding loop reports nothing
// during a load, so a slow one looks exactly like a buffer that ran dry
// and was being counted twice — once as a slow load, once as a stall.
if (loadInFlight) return@Runnable
if (playWhenReady && playbackState == Player.STATE_READY) bandwidth.stalled()
}
/** True between a track being asked for and that same track playing. */
private var loadInFlight = false
private fun expectProgress() {
handler.removeCallbacks(stallWatch)
if (playWhenReady) handler.postDelayed(stallWatch, STALL_AFTER_MS)
}
/**
* The other device's playback, when the account is playing on one.
*
* Mirrored into this player rather than drawn only by the app, because the
* notification and anything else holding a media controller read this and
* nothing else: a car head unit and the lock screen do not know the app has
* a second idea of what is playing. Fed by the service; see
* PlaybackService.
*/
private var remote: dev.lelonio.square.data.RemotePlayback? = null
val isRemotePlayback: Boolean get() = remote != null
/**
* Called with a track the engine is playing that this queue does not hold.
*
* Another client can point this device at anything: a track from a playlist
* that was never opened here, with no transfer and no cluster update to
* announce it, since the account does not describe a device to itself. The
* engine simply starts playing something else, and this side went on
* showing the track it thought was current. Set by the service, which is
* the half that can resolve a context.
*/
var onUnknownTrack: ((String) -> Unit)? = null
/** The last one handed over, so a run of events asks for it once. */
private var unknownAsked: String? = null
/** The pair the engine was last given a mix transition for, "" for none. */
private var mixPlanFor: String? = null
init {
// A mix switched on, off, or read late: the plan is worked out again
// on this player's own thread.
Mixes.onChange = { handler.post { if (!released) followMix() } }
}
fun showRemote(playback: dev.lelonio.square.data.RemotePlayback?) {
if (released) return
val was = remote
remote = playback
// Rebuilt when what it shows changes — the track, its names, what comes
// next — and not for the position, which moves every second.
val shown = { p: dev.lelonio.square.data.RemotePlayback? -> p?.copy(positionMs = 0, playing = false) }
if (shown(was) != shown(playback)) cachedPlaylist = null
invalidateState()
}
/**
* What the transport buttons act on: the other device, or this one.
*
* A command sent to the wrong end is worse than a command that fails, since
* it moves music the listener is not hearing.
*/
private fun onRemote(what: String, command: (String) -> Unit): Boolean {
val target = remote ?: return false
Thread({
runCatching { command(target.deviceId) }
.onFailure { android.util.Log.w("SquarePlayer", "$what did not reach it", it) }
}, "square-remote").start()
return true
}
override fun getState(): State {
remote?.let { return remoteState(it) }
val items = queue.items
// Media3 refuses a playing state with nothing to play, and says so by
// throwing out of this method: "Empty playlist only allowed in
// STATE_IDLE or STATE_ENDED", on the main thread, taking the app with
// it. The two can come apart for a moment whenever the engine is
// playing something this side has not been told about yet, which is
// what taking playback back from another device does. Idle is the
// honest answer while the queue is empty, and the next event, once the
// queue has arrived, corrects it.
val reportedState = if (items.isEmpty()) Player.STATE_IDLE else playbackState
val builder = State.Builder()
.setAvailableCommands(COMMANDS)
.setPlaybackState(reportedState)
.setPlayWhenReady(playWhenReady, Player.PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
.setContentPositionMs(positionMs)
.setRepeatMode(repeatMode)
.setShuffleModeEnabled(shuffleEnabled)
.setPlaybackParameters(playbackParameters)
if (items.isNotEmpty()) {
builder.setPlaylist(playlistSnapshot())
.setCurrentMediaItemIndex(queue.currentIndex.coerceIn(0, items.lastIndex))
}
return builder.build()
}
/**
* The playlist as Media3 items, rebuilt only when the queue actually changes.
*
* `getState` runs on every `invalidateState`, which includes each position
* update while playing. Rebuilding a 50-track playlist twice a second
* allocates several hundred objects per second describing data that did not
* change — enough GC churn to make the audio stutter. The cache is dropped
* by [onQueueChanged] at the few points that mutate the queue.
*/
/**
* The same shape of state, describing a device in another room.
*
* One item rather than the whole queue: the account publishes what is
* playing, not the list behind it, and inventing the rest would be inventing
* a queue this app cannot skip through anyway.
*/
private fun remoteState(playback: dev.lelonio.square.data.RemotePlayback): State {
fun item(uid: String, uri: String, title: String, artist: String, album: String, cover: String) =
MediaItemData.Builder(uid).setMediaItem(
MediaItem.Builder()
.setMediaId(uri)
.setUri(uri)
.setMediaMetadata(
MediaMetadata.Builder()
.setTitle(title)
.setArtist(artist)
.setAlbumTitle(album)
.setArtworkUri(cover.takeIf { it.isNotEmpty() }?.let(android.net.Uri::parse))
.setIsBrowsable(false)
.setIsPlayable(true)
.build(),
)
.build(),
)
// The track and what comes after it on that device: its own queue,
// rather than one track and nothing after it.
val items = cachedPlaylist ?: buildList {
add(
item("remote:0", playback.uri, playback.title, playback.artist, playback.album, playback.coverUrl)
.setDurationUs(playback.durationMs * 1000)
.build(),
)
playback.next.forEachIndexed { index, track ->
add(item("remote:${index + 1}:${track.uri}", track.uri, track.title, track.artist, "", track.coverUrl).build())
}
}.also { cachedPlaylist = it }
return State.Builder()
.setAvailableCommands(COMMANDS)
.setPlaybackState(Player.STATE_READY)
.setPlayWhenReady(playback.playing, Player.PLAY_WHEN_READY_CHANGE_REASON_REMOTE)
.setContentPositionMs(playback.positionMs)
.setRepeatMode(
when {
playback.repeatTrack -> Player.REPEAT_MODE_ONE
playback.repeatContext -> Player.REPEAT_MODE_ALL
else -> Player.REPEAT_MODE_OFF
},
)
.setShuffleModeEnabled(playback.shuffle)
.setPlaylist(items)
.setCurrentMediaItemIndex(0)
.build()
}
private fun playlistSnapshot(): List<MediaItemData> =
cachedPlaylist ?: queue.items
.mapIndexed { index, track -> toMediaItemData(queue.idAt(index) ?: -1L, track) }
.also { cachedPlaylist = it }
/**
* Puts a saved tempo and pitch back without routing through the output
* again — the service has already applied them there.
*/
fun restorePlaybackParameters(speed: Float, pitch: Float) {
playbackParameters = androidx.media3.common.PlaybackParameters(speed, pitch)
invalidateState()
}
/**
* Tempo and pitch changes.
*
* Note the engine keeps reporting position in *decoded* time, so at a speed
* other than 1.0 the reported position and the wall clock drift apart. Left
* as it is deliberately: the alternative is scaling every position the engine
* sends, which would put the seek bar and the engine's own idea of the track
* out of step and break seeking.
*/
override fun handleSetPlaybackParameters(
playbackParameters: androidx.media3.common.PlaybackParameters,
): ListenableFuture<*> {
this.playbackParameters = playbackParameters
onSpeedAndPitch(playbackParameters.speed, playbackParameters.pitch)
AudioEffects.rememberSpeedAndPitch(playbackParameters.speed, playbackParameters.pitch)
return Futures.immediateVoidFuture()
}
/**
* A command to the engine, whose failure is not the app's death.
*
* These run inside Media3's own call stack — a controller pressing play in
* the notification ends up here — and Media3 does not catch anything. An
* engine that has lost its Connect channel answers "channel closed", the
* JNI boundary turns that into an exception, and the exception came out of
* the main looper with the process behind it. Observed after a skip:
*
* java.lang.IllegalStateException: play failed: Internal error { channel closed }
* at NativeBridge.nativePlay(Native Method)
* at LibrespotPlayer.handleSetPlayWhenReady
*
* A failed transport command should cost the command.
*/
/**
* Sends one command to the engine, and says so loudly when it does not land.
*
* At error level rather than warning, because there is no such thing as a
* harmless transport command that failed: the user pressed something and it
* did not happen. This was a warning, which is how "pause does nothing and
* the music keeps playing" stayed invisible in the log for so long.
*
* The engine itself now falls back to the player when the Connect layer
* refuses a command, so reaching this line means both paths failed and
* playback is genuinely beyond the app's reach.
*/
private inline fun engine(what: String, command: () -> Unit) {
runCatching(command)
.onFailure { android.util.Log.e("SquarePlayer", "$what did not reach the engine", it) }
}
/** Whether the engine says its Connect device is gone; false if it cannot answer. */
/**
* Whether a step command has anything to reach.
*
* Offline counts, and has to: the engine reports no lost device then —
* there is none to lose — so a skip took the ordinary road, was handed to a
* Connect device that does not exist, and fell through to the player, whose
* answer to a step it cannot make is to stop. Skipping simply stopped the
* music, while picking a song by hand worked, because that path rebuilds
* the queue instead of stepping through it.
*
* And so does the app being offline with the session still standing. On
* mobile data with no coverage the session's sockets stay open for minutes
* with nothing coming through, so the device was not "lost", and the engine
* sends everything to the player then anyway; see engine.rs player_only.
*/
private val deviceGone: Boolean
get() = OfflineMode.active.value ||
runCatching { NativeBridge.isOffline }.getOrDefault(false) ||
runCatching { NativeBridge.spircLost }.getOrDefault(false)
/**
* Whether the track playing went into the player around Connect: offline,
* or with the Connect device lost. Its end is then this side's to act on —
* also after the session comes back, which is when the music used to stop:
* online again, the offline advance stood aside, and Connect had never been
* given this queue to advance.
*/
private var outsideSpirc = false
/** Whether the next track is this side's to start rather than the engine's. */
private fun ownsAdvance(): Boolean =
outsideSpirc || runCatching { NativeBridge.isOffline }.getOrDefault(false)
/** Set when the engine stopped its player; a play then has to load again. */
private var engineStopped = false
/** Set while a reconnection is in flight, so a burst of taps starts one. */
private var reconnecting = false
/** How long a track dissolves into the next; the listener's own setting. */
private val crossfade = dev.lelonio.square.data.CrossfadeStore(context)
/** For the notices this says to the listener; see onKeyRefused. */
private val appContext = context.applicationContext
/** Watches the one thing outside this class that changes what it must do. */
private val watch = kotlinx.coroutines.CoroutineScope(
kotlinx.coroutines.SupervisorJob() + kotlinx.coroutines.Dispatchers.Default,
)
// A fast Wi-Fi/cellular handover can invalidate Spirc without ever
// entering OfflineMode. Recover on the player looper, preserving the queue
// and position. Explicit pauses cancel the intent before a rebuild finishes.
private val sessionWatch = object : Runnable {
override fun run() {
if (released) return
if (!reconnecting && !OfflineMode.active.value) {
runCatching { dev.lelonio.square.data.RemoteConnect.refresh() }
}
if (!reconnecting && remote == null && !OfflineMode.active.value &&
(playWhenReady || wantPlay) && queue.items.isNotEmpty() && deviceGone
) {
withDevice {
if (deviceGone) return@withDevice
engineQueueStale = true
pushQueue(startPlaying = wantPlay || playWhenReady, positionMs = positionMs.toInt())
}
}
handler.postDelayed(this, 5_000L)
}
}
private val resumeHereHandler: (dev.lelonio.square.data.RemotePlayback) -> Unit = { target ->
handler.post {
if (!released && focus.requestFocus()) {
Thread({
runCatching {
NativeBridge.resumeHere(target.realContext.orEmpty(), target.uri, target.positionMs.toInt())
}.onFailure {
android.util.Log.e("SquarePlayer", "could not resume Connect playback here", it)
handler.post { focus.abandonFocus() }
}
}, "square-resume-here").start()
}
}
}
init {
dev.lelonio.square.data.RemoteConnect.resumeHereHandler = resumeHereHandler
handler.postDelayed(sessionWatch, 2_000L)
// Coming back online, the engine has to be given this queue again.
//
// Offline the tracks are loaded one at a time, straight into the
// player: the Connect device is not there to be told what the queue is.
// When the network returns that device comes back knowing nothing, and
// the song that was playing ran to its end with nobody to advance it —
// so the music stopped and stayed stopped, on a queue of songs that
// were all sitting on the phone.
watch.launch {
dev.lelonio.square.playback.OfflineMode.active
.drop(1)
.distinctUntilChanged()
.collect { offline ->
if (offline) return@collect
handler.post {
if (released || queue.items.isEmpty()) return@post
withDevice {
val shouldPlay = playWhenReady || wantPlay
if (shouldPlay) playbackState = Player.STATE_BUFFERING
engineQueueStale = true
pushQueue(startPlaying = shouldPlay, positionMs = positionMs.toInt())
invalidateState()
}
}
}
}
}
/**
* The track this side has already moved on from, by uri.
*
* Offline nothing else advances the queue — there is no Connect device to
* own it — so this side does, and it must do it once. Kept as the uri
* rather than a flag so a track that comes round again in a loop is a
* different question each time.
*/
private var advancedFrom: String? = null
/**
* Runs `then` on the looper with a live Connect device, rebuilding one first
* if the engine has lost its.
*
* A dropped network costs the session, and a session takes its Connect
* device with it: librespot hands out the Spirc builder once per session, so
* there is nothing to revive and the engine builds a new session instead.
* That is a handshake, which is why it runs off the looper.
*
* A failed rebuild still runs `then`. There is no state where refusing to
* try is better: the command was going to be ignored either way, and going
* ahead at least reaches the engine's own fallback, which stops the sound.
*/
private fun withDevice(then: () -> Unit) {
// Keep downloaded tracks moving while Spotify is unavailable. A
// reconnect on every skip destroys the working downloads-only player.
// Offline for any reason: bringing the session back is the keeper's
// job, and a handshake tried here, on a network carrying nothing, held
// the downloaded track for as long as the handshake took to give up.
if (OfflineMode.active.value) {
handler.post { if (!released) then() }
return
}
if (!deviceGone) {
handler.post { if (!released) then() }
return
}
if (reconnecting) {
android.util.Log.i("SquarePlayer", "already reconnecting, dropping this one")
return
}
reconnecting = true
Thread({
runCatching { NativeBridge.reconnect() }
.onFailure { android.util.Log.e("SquarePlayer", "reconnect failed", it) }
handler.post {
reconnecting = false
// The new device has never been told what this queue is: its
// predecessor's state went with the session it belonged to.
engineQueueStale = true
if (!released) then()
}
}, "square-reconnect").start()
}
/** Call after any queue mutation, before [invalidateState]. */
private fun onQueueChanged() {
cachedPlaylist = null
}
/**
* Where the engine actually is in the queue; -1 until it says.
*
* Kept apart from [PlayQueue.currentIndex], which now moves as soon as the
* user asks rather than when the engine catches up.
*/
/**
* Whether the listener has asked for sound, as opposed to whether there is
* any yet.
*
* [playWhenReady] cannot answer this: it is only ever set from the engine's
* own events, so that the seek bar never runs ahead of the speaker. But a
* tap on a track sends "load this" and "play" one after the other, the load
* is deferred by the fade, and the play lands on an engine that has not been
* given the new queue yet. With only the reported state to go on the load
* then went out as paused, and the tapped track sat there selected and
* silent.
*/
private var wantPlay = false
private var engineIndex = -1
/**
* Whether the track the queue is on has actually started.
*
* A load is not a change of track. The engine fetches what is coming while
* the current song plays, and each of those arrives here as a load: taken
* as "the engine has moved on", the screen ran forward a song or two and
* the one just started vanished from under the listener.
*
* A load still counts while nothing is sounding, and that case is the one
* loads were followed for: a run of tracks the account cannot play is
* loaded one after another with no play in between, and ignoring those
* left the app behind the speaker.
*/
private var sounding = false
/**
* True when the list the engine was given no longer matches ours.
*
* Spirc holds the track list it was loaded with and advances through it by
* itself; there is no way to hand it an insertion. So a local edit is
* invisible to it until the whole queue is loaded again, and until then its
* "next" is not ours — which is why a skip cannot be delegated while this
* is set.
*/
private var engineQueueStale = false
/** A skip the user has made and the engine has not been told about yet. */
private var skipPending = false
/** A skip already handed to the engine, still to be confirmed by an event. */
private var skipInFlight = false
/**
* A skip made while paused, held until play is pressed.
*
* Every load is an audio key, and Spotify meters those per account: a
* listener paging through the queue with the music paused was spending
* one on every song they passed, none of which they heard, and the
* refusals that followed landed on the song they finally pressed play on.
* The screen moves at once; the engine is told when there is something to
* hear.
*/
private var deferredSkip = false
/**
* Moves to a track, without making the user wait for the engine.
*
* Every skip used to be a command of its own: ten taps were ten loads, each
* behind its own fade, and the engine spent seconds working through a queue
* of decisions the user had already changed their mind about. Worse, the
* screen only moved when the engine did, so a fast run of skips felt stuck.
*
* Now the queue position moves immediately — the screen follows the taps —
* and the engine is told once the tapping stops. What it is told depends on
* where it ended up: one step either way is a real skip, which keeps the
* context playing on the account and on other devices; anything further is
* a load at the target, which is one request instead of a dozen.
*/
private fun requestSkipTo(index: Int, positionMs: Long) {
// A skip on a device in another room is a skip there; the index this
// side would step through means nothing to it.
if (remote != null) {
val forward = index >= queue.currentIndex
onRemote(if (forward) "next" else "previous") { id ->
if (forward) dev.lelonio.square.data.RemoteConnect.next(id) else dev.lelonio.square.data.RemoteConnect.previous(id)
}
return
}
queue.currentIndex = index.coerceIn(0, maxOf(0, queue.items.lastIndex))
// A skip starts the new track at its beginning. Media3 sends
// C.TIME_UNSET for "wherever it starts", which as a number is very
// negative and made the bar draw itself backwards.
this.positionMs = positionMs.coerceAtLeast(0)
// Paused: nothing is loaded until play; see deferredSkip. Held as a
// pending skip so what the engine says about the track it is still on
// does not pull the screen back to it.
if (!playWhenReady && !deviceGone && engineIndex >= 0) {
deferredSkip = queue.currentIndex != engineIndex || this.positionMs > 0
skipPending = deferredSkip
handler.removeCallbacks(settleSkip)
handler.removeCallbacks(skipGaveUp)
playbackState = Player.STATE_READY
invalidateState()
return
}
playbackState = Player.STATE_BUFFERING
skipPending = true
invalidateState()
// The first skip of a burst goes out at once; only the ones on top of
// it wait. Waiting for the first was a fifth of a second between the
// tap and anything happening at all — the delay this settle exists to
// avoid, spent on the one skip that never needed it.
//
// Unless the change is dissolved, where nothing is waiting: the song
// being left goes on playing through it, and the fade starts when the
// engine takes the load. What the wait buys is one load instead of two
// for a double tap, and a load is an audio key: Spotify meters those
// per session and answers a burst by refusing everything for up to
// half a minute; see audio_key.rs.
val delay = if (skipInFlight || dissolves()) SKIP_SETTLE_MS else 0L
skipInFlight = true
handler.removeCallbacks(settleSkip)
handler.postDelayed(settleSkip, delay)
// Held until the engine says it is on the track that was asked for.
//
// Cleared as soon as the command went out, the events still coming in
// about the track being left were taken as the truth, and the screen
// walked backwards to the song the listener had just skipped. The
// timeout is the way out of a command that never lands.
handler.removeCallbacks(skipGaveUp)
handler.postDelayed(skipGaveUp, SKIP_CONFIRM_MS)
}
/** The engine never confirmed the skip; stop ignoring what it says. */
private val skipGaveUp = Runnable {
skipPending = false
skipInFlight = false
// And stop contradicting it.
//
// Clearing the flags was not enough: the queue kept the track that was
// asked for, so a skip the engine turned into something else left the
// screen on one song and the speaker on another, and every step after
// that was measured from the wrong place. A next pressed then asked for
// the track already playing, so nothing was sent and the old song went
// on. What the engine last said it was on is where the queue goes back
// to. A load on its way still counts, since it names the track asked
// for.
if (engineIndex >= 0 && engineIndex != queue.currentIndex && engineIndex <= queue.items.lastIndex) {
android.util.Log.w(
"SquarePlayer",
"skip to ${queue.currentIndex} never confirmed, back to the engine's $engineIndex",
)
queue.currentIndex = engineIndex
invalidateState()
}
}
private val settleSkip = Runnable {
if (released) return@Runnable
val target = queue.currentIndex
val from = engineIndex
when {
from == target -> {
if (positionMs > 0) engine("seek") { NativeBridge.seek(positionMs) }
}
// Nothing is listening for a skip: a step command would be
// accepted by a dead device and discarded, and the old track would
// play on. The queue is pushed instead, which rebuilds the device
// first and then loads the track that was asked for.
deviceGone -> {
pushQueue(startPlaying = playWhenReady, positionMs = 0)
}
// A step either way is a skip, and Spirc has to be the one making
// it: reloading the queue for a skip would restart the context and
// show up on other devices as a new session rather than a next.
!engineQueueStale && from >= 0 && target == from + 1 -> changing {
handler.post {
if (released) return@post
runCatching { NativeBridge.next() }
if (!dissolves()) fadeIn()
}
}
!engineQueueStale && from >= 0 && target == from - 1 -> changing {
handler.post {
if (released) return@post
runCatching { NativeBridge.previous() }
if (!dissolves()) fadeIn()
}
}
else -> {
pushQueue(startPlaying = playWhenReady, positionMs = positionMs.toInt())
}
}
}
/**
* Restores the shuffled order after the queue has been rebuilt.
*
* A new queue arrives unshuffled, and the mode has to be stamped back onto
* it or turning shuffle on would last exactly until the next tap.
*/
private fun reapplyShuffle() {
if (shuffleEnabled && !queue.isShuffled) queue.setShuffled(true)
}
/**
* There is nothing to prepare: the engine buffers on load. Reporting the
* state the caller expects is enough, and without this override
* [SimpleBasePlayer] throws for the advertised [Player.COMMAND_PREPARE].
*/
override fun handlePrepare(): ListenableFuture<*> {
if (playbackState == Player.STATE_IDLE && queue.items.isNotEmpty()) {
playbackState = Player.STATE_BUFFERING
invalidateState()
}
return Futures.immediateVoidFuture()
}
override fun handleStop(): ListenableFuture<*> {
engine("stop") { NativeBridge.stop() }
wantPlay = false
focus.abandonFocus()
playbackState = Player.STATE_IDLE
playWhenReady = false
invalidateState()
return Futures.immediateVoidFuture()
}
override fun handleSetPlayWhenReady(playWhenReady: Boolean): ListenableFuture<*> {
// The buttons follow the music. Everything below drives this phone's
// own engine, which is silent while another device is playing.
val wanted = playWhenReady
if (onRemote(if (wanted) "play" else "pause") { id ->
if (wanted) dev.lelonio.square.data.RemoteConnect.play(id) else dev.lelonio.square.data.RemoteConnect.pause(id)
}
) {
return Futures.immediateVoidFuture()
}
if (playWhenReady) {
// Refusing focus means something else owns the output — starting
// anyway would talk over it.
if (!focus.requestFocus()) return Futures.immediateVoidFuture()
wantPlay = true
this.playWhenReady = true
if (playbackState == Player.STATE_IDLE) {
playbackState = Player.STATE_READY
}
invalidateState()
// Pressed before there is an engine to press it on. Remembered
// rather than sent: the queue goes over the moment the access point
// answers, and it goes over playing.
if (awaitingEngine) {
playbackState = Player.STATE_BUFFERING
onPlaybackActive(true)
invalidateState()
return Futures.immediateVoidFuture()
}
// A skip made while paused goes out now, playing: the track the
// engine holds is not the one on the screen. One load for however
// many songs were passed.
if (deferredSkip) {
deferredSkip = false
if (queue.currentIndex == engineIndex && positionMs == 0L) {
skipPending = false
} else {
playbackState = Player.STATE_BUFFERING
skipInFlight = true
invalidateState()
handler.removeCallbacks(skipGaveUp)
handler.postDelayed(skipGaveUp, SKIP_CONFIRM_MS)
pushQueue(startPlaying = true, positionMs = positionMs.toInt())
return Futures.immediateVoidFuture()
}
}
// If no track is currently loaded but queue exists, load the queue.
// Otherwise, unpause the existing loaded track immediately via NativeBridge.play().
//
// Also when the engine has stopped the player under the paused
// track — which Spotify does to a device left paused and inactive
// for a few seconds. A stopped player refuses "play" (it only logs
// it), so the button spun forever; the track is loaded again where
// it was paused instead.
if ((currentMediaItem == null || engineStopped || engineQueueStale) && queue.items.isNotEmpty()) {
engineStopped = false
playbackState = Player.STATE_BUFFERING
invalidateState()
pushQueue(startPlaying = true, positionMs = positionMs.toInt())
} else {
var playFailed = false
engine("play") {
try {
NativeBridge.play()
} catch (e: Throwable) {
playFailed = true
throw e
}
}
if (playFailed && queue.items.isNotEmpty()) {
pushQueue(startPlaying = true, positionMs = positionMs.toInt())
}
}
// After the engine, not before: waking the output is a call into
// the audio server that took most of a tenth of a second here, and
// it stood between the button and the command that brings the
// music back.
onPlaybackActive(true)
} else {
wantPlay = false
this.playWhenReady = false
onPlaybackActive(false)
focus.abandonFocus()
engine("pause") { NativeBridge.pause() }
invalidateState()
}
return Futures.immediateVoidFuture()
}
/**
* Lower the volume for a transient interruption instead of pausing.
*
* librespot's volume is a raw 0..65535 value, so the previous one is kept
* verbatim and restored rather than recomputed.
*/
private fun applyDuck(ducked: Boolean) {
onDuckReverb(if (ducked) DUCK_FACTOR.toFloat() else 1f)
if (ducked) {
if (volumeBeforeDuck != null) return
val current = runCatching { NativeBridge.volume }.getOrNull() ?: return
volumeBeforeDuck = current
engine("duck") { NativeBridge.volume = (current * DUCK_FACTOR).toInt() }
} else {
volumeBeforeDuck?.let { level -> engine("unduck") { NativeBridge.volume = level } }
volumeBeforeDuck = null
}
}
override fun handleSeek(
mediaItemIndex: Int,
newPositionMs: Long,
seekCommand: @Player.Command Int,
): ListenableFuture<*> {
// Seeking, skipping and stopping all belong to whichever device is
// playing; see onRemote.
if (remote != null) {
when (seekCommand) {
Player.COMMAND_SEEK_TO_NEXT,
Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM,
-> onRemote("next", dev.lelonio.square.data.RemoteConnect::next)
Player.COMMAND_SEEK_TO_PREVIOUS,
Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM,
-> onRemote("previous", dev.lelonio.square.data.RemoteConnect::previous)
else -> onRemote("seek") { id -> dev.lelonio.square.data.RemoteConnect.seek(id, newPositionMs) }
}
return Futures.immediateVoidFuture()
}
queue.items.getOrNull(mediaItemIndex) ?: return Futures.immediateVoidFuture()
if (mediaItemIndex == queue.currentIndex && !skipPending) {
engine("seek") { NativeBridge.seek(newPositionMs) }
positionMs = newPositionMs
invalidateState()
return Futures.immediateVoidFuture()
}
requestSkipTo(mediaItemIndex, newPositionMs)
positionMs = newPositionMs
return Futures.immediateVoidFuture()
}
override fun handleSetMediaItems(
mediaItems: List<MediaItem>,
startIndex: Int,
startPositionMs: Long,
): ListenableFuture<*> {
// Choosing a track here is the listener asking for this phone, and it
// is the only moment in the app where taking the account's playback is
// what they meant. Everything else that reaches the engine leaves the
// other device alone; see engine.rs.
if (runCatching { NativeBridge.playbackElsewhere }.getOrDefault(false)) {
android.util.Log.i("SquarePlayer", "taking playback back for this device")
runCatching { NativeBridge.takeOver() }
.onFailure { android.util.Log.w("SquarePlayer", "could not take over", it) }
}
android.util.Log.i(
"SquarePlayer",
"queue set: ${mediaItems.size} items at $startIndex, " +
"first=${mediaItems.getOrNull(startIndex)?.mediaId}",
)
queue.replaceFromMediaItems(mediaItems, startIndex)
// A new queue: whatever the engine was playing is no longer at any
// index of this one.
engineIndex = -1
sounding = false
// Shuffle before picking the track to load: with the mode on, the tapped
// track moves to the front and the rest are reordered behind it.
reapplyShuffle()
onQueueChanged()
val first = queue.items.getOrNull(queue.currentIndex) ?: run {
// Every item was rejected for lacking a Spotify URI as its media id.
android.util.Log.w(
"SquarePlayer",
"nothing playable in ${mediaItems.size} items; " +
"first id=${mediaItems.firstOrNull()?.mediaId}",
)
return Futures.immediateVoidFuture()
}
// Starts only if playback was already meant to be running. Loading with
// startPlaying always true would make a restored session play by itself
// on launch; when the user taps a track, Media3 follows this with
// play(), which resumes the loaded-but-paused engine.
// Report the start position immediately. Leaving it at zero makes the
// seek bar read 0:00 while the engine is already further in, and nothing
// corrects it until the first position event — which never arrives at
// all while paused.
positionMs = startPositionMs
playbackState = Player.STATE_BUFFERING
// `first` is only read to check there is something playable; the engine
// is handed the whole list.
check(first.uri.isNotEmpty())
pushQueue(startPlaying = playWhenReady, positionMs = startPositionMs.toInt())
invalidateState()
return Futures.immediateVoidFuture()
}
/**
* The next three exist because [Player.COMMAND_CHANGE_MEDIA_ITEMS] is
* advertised. They only reorder the queue — the engine plays one track at a
* time and is untouched unless the current track itself moved out from under
* it, which [PlayQueue] follows by entry rather than by index.
*/
override fun handleAddMediaItems(
index: Int,
mediaItems: List<MediaItem>,
): ListenableFuture<*> {
queue.addFromMediaItems(index, mediaItems)
reapplyShuffle()
// The engine is told now, not at the end of the song.
//
// Left for later, the track a listener queued was not in the engine's
// list when the current one ended: the engine moved to its own next
// track and this side had to skip to the queued one after the fact,
// which is a cut — the change of track the listener hears when they
// press skip, in the middle of a crossfade they did not. Handed over as
// an order, the queued track simply *is* what comes next, and the end
// of the song dissolves into it like any other.
pushOrder()
onQueueChanged()
invalidateState()
return Futures.immediateVoidFuture()
}
override fun handleRemoveMediaItems(fromIndex: Int, toIndex: Int): ListenableFuture<*> {
queue.remove(fromIndex, toIndex)
reapplyShuffle()
// A track taken out of the queue is gone from the engine's list too, and
// for the same reason as above: otherwise it plays anyway when the
// current song ends, and this side skips past it afterwards.
pushOrder()
onQueueChanged()
invalidateState()
return Futures.immediateVoidFuture()
}
override fun handleMoveMediaItems(
fromIndex: Int,
toIndex: Int,
newIndex: Int,
): ListenableFuture<*> {
queue.move(fromIndex, toIndex, newIndex)
reapplyShuffle()
// Told now, as for an add or a remove: a track dragged to play next
// has to be what the engine plays next.
pushOrder()
onQueueChanged()
invalidateState()
return Futures.immediateVoidFuture()
}
/**
* Puts a saved session back: queue, order, position and modes at once.
*
* Deliberately not expressed as a sequence of ordinary commands. Setting the
* shuffle flag before the queue exists is a no-op, and setting it after
* would draw a fresh random order instead of the one that was saved, so the
* whole thing has to be applied as a unit.
*/
/**
* Empties the player so a rebuilt engine can be restored into it.
*
* Not a stop: nothing is sent to the engine, which by this point no longer
* exists. It clears what the app believes about it, so the queue coming
* back from storage is loaded rather than skipped as "already playing".
*/
/**
* Hands the queue back to an engine that has just been rebuilt.
*
* Everything on this side is still true — the list, the order, the track —
* and only the engine's copy went away with its session, so this pushes it
* again at the position it had reached rather than starting anything over.
*/
fun reloadQueue(playing: Boolean, positionMs: Long) {
if (released || queue.items.isEmpty()) return
engineQueueStale = true
engineIndex = -1
sounding = false
this.positionMs = positionMs
wantPlay = playing
pushQueue(startPlaying = playing, positionMs = positionMs.toInt())
invalidateState()
}
fun clearForRestart() {
queue.replace(emptyList(), 0)
wantPlay = false
engineIndex = -1
sounding = false
engineQueueStale = false
skipPending = false
skipInFlight = false
handler.removeCallbacks(settleSkip)
positionMs = 0
playWhenReady = false
playbackState = Player.STATE_IDLE
onQueueChanged()
invalidateState()
}
/**
* True while the queue on screen is one the engine has not been given yet.
*
* See [restore]: the saved queue is put back before there is an access point
* to hand it to, so this is the window between the two.
*/
private var awaitingEngine = false
/**
* True between handing the engine a queue and it playing from that queue.
*
* A queue takes a moment to land, and in that moment the engine goes on
* reporting the track it is still on — the one being replaced. That track
* is not in the new queue, which reads exactly like another device having
* chosen something this app knows nothing about, and the answer to that is
* to adopt what the engine is playing. So opening the app on a paused song
* and tapping a track in a playlist wiped the queue just chosen and put the
* old one back: the new song played, and the screen showed the old one.
*
* Nothing is adopted while this is set. It is only ever the app's own queue
* arriving, and there is nothing to learn from it.
*/
private var ownQueuePending = false
/** A push that never landed must not switch adoption off for good. */
private val giveUpOnOwnQueue = Runnable { ownQueuePending = false }
fun restore(
tracks: List<PlayQueue.Track>,
shuffleOrder: List<Int>?,
index: Int,
positionMs: Long,
repeatMode: @Player.RepeatMode Int,
/** The playlist or album the queue came from; see PlayQueue. */
contextUri: String?,
contextIsOrdered: Boolean,
contextLabel: String,
/**
* Whether the engine can be handed the queue now.
*
* False when the app has only just started. Authenticating takes a
* handshake and a catalogue call, and none of that is a reason to leave
* the screen blank in the meantime: what was paused is known from disk,
* so it is put back straight away and shown as loading, and
* [handOverToEngine] gives it to the access point once there is one.
* The alternative, which is what this used to do, was an app that came
* back looking as though nothing had ever been playing.
*/
handOverNow: Boolean = true,
smartShuffle: Boolean = false,
) {
if (tracks.isEmpty()) return
// Put back before the queue is loaded: the load itself hands the
// context to the engine, and a restored session with no context is one
// whose listens are filed under nothing and whose player has no source
// to show.
queue.restoreContext(contextUri, contextIsOrdered, contextLabel)
// A queue put back after a restart says what it plays before any
// event from the engine does; see Mixes.playing.
Mixes.follow(queue.contextUri)
queue.replace(tracks, 0)
engineIndex = -1
sounding = false
shuffleOrder?.let(queue::applyShuffleOrder)
queue.smartShuffle = smartShuffle && shuffleOrder != null
queue.currentIndex = index.coerceIn(0, queue.items.lastIndex)
shuffleEnabled = shuffleOrder != null
this.repeatMode = repeatMode
this.positionMs = positionMs
playWhenReady = false
wantPlay = false
awaitingEngine = !handOverNow
// Loading, not ready: there is a track and a position to show, and
// nothing that could answer a tap on play yet. Buffering is what the
// mini player already draws a spinner for.
playbackState = if (handOverNow) Player.STATE_READY else Player.STATE_BUFFERING
onQueueChanged()
// Paused: an app that starts playing by itself when opened is worse
// than one that forgets where it was.
//
// The load also takes over the Connect device, which is why it is not
// done here at all when there is nothing to restore — activating on
// launch would pull playback away from whatever the account is actually
// playing on.
engineQueueStale = true
invalidateState()
}
/**
* Gives the engine the queue that was put back before it existed.
*
* Carries [wantPlay] with it, so a listener who pressed play while the app
* was still connecting gets the track they asked for rather than a button
* that did nothing.
*/
fun handOverToEngine() {
if (!awaitingEngine) return
awaitingEngine = false
android.util.Log.i(
"SquarePlayer",
"handing over ${queue.items.size} tracks at ${queue.currentIndex}, play=$wantPlay",
)
if (queue.items.isEmpty()) {
playbackState = Player.STATE_IDLE
invalidateState()
return
}
playbackState = if (wantPlay) Player.STATE_BUFFERING else Player.STATE_READY
engineQueueStale = true
// Restoring the screen must not activate this device. The initial
// Connect cluster may still be arriving, so an "elsewhere" guard is
// too early here. Only a Play pressed by the listener loads the queue.
if (wantPlay) pushQueue(startPlaying = true, positionMs = positionMs.toInt())
invalidateState()
}
/**
* Takes on a queue the engine is already playing.
*
* The other half of Connect, and the one this app was missing. Another
* client can hand playback to this phone from its own device list: Spotify
* sends the engine a transfer, the engine starts playing, and nothing here
* is asked or told. What was left was a track playing with an empty queue,
* so there was nothing after it and nothing on screen.
*
* Unlike [restore] this loads nothing. The engine already has the queue and
* the position; the point is only that this side stops disagreeing.
*/
fun adopt(
tracks: List<PlayQueue.Track>,
index: Int,
positionMs: Long,
contextUri: String?,
contextLabel: String,
playing: Boolean,
) {
if (tracks.isEmpty()) return
// The second line of the same defence as [ownQueuePending]: reading a
// context takes seconds, and a listener who has chosen something in
// those seconds has said what they want more recently than the engine
// has.
if (ownQueuePending) {
android.util.Log.i("SquarePlayer", "not adopting: a queue of ours is on its way")
return
}
android.util.Log.i("SquarePlayer", "adopting ${tracks.size} tracks at $index")
queue.restoreContext(contextUri, contextUri != null, contextLabel)
queue.replace(tracks, 0)
queue.currentIndex = index.coerceIn(0, queue.items.lastIndex)
// The engine is playing this queue; it is this side that has just
// learned of it.
engineIndex = queue.currentIndex
engineQueueStale = false
this.positionMs = positionMs
playWhenReady = playing
wantPlay = playing
playbackState = Player.STATE_READY
onQueueChanged()
invalidateState()
}
/**
* Reorders the queue rather than only recording a flag; see [PlayQueue].
*/
private var smartLoading = false
private var smartUnavailableContext: String? = null
suspend fun cycleShuffle() {
if (smartLoading || released || isRemotePlayback) return
if (queue.smartShuffle) {
queue.disableSmartShuffle()
shuffleEnabled = false
onQueueChanged()
pushOrder()
invalidateState()
return
}
if (!shuffleEnabled) {
shuffleModeEnabled = true
return
}
val context = queue.contextUri
if (context != null && smartUnavailableContext == context) {
smartUnavailableContext = null
shuffleModeEnabled = false
return
}
if (context == null || !(context.startsWith("spotify:playlist:") || context.endsWith(":collection"))) {
shuffleModeEnabled = false
return
}
smartLoading = true
val initialTracks = queue.items.toList()
try {
val recommendations = dev.lelonio.square.data.SmartShuffle.recommendations(context, initialTracks.mapTo(mutableSetOf()) { it.uri })
// A new playlist, a reorder, a remote transfer or shuffle off cancels this result.
if (released || isRemotePlayback || queue.contextUri != context || queue.items != initialTracks || !shuffleEnabled) return
check(recommendations.isNotEmpty()) { "No enhanced recommendations returned" }
queue.enableSmartShuffle(recommendations.map { track -> PlayQueue.Track(
uri = track.uri, title = track.name, artist = track.artist,
artistUri = track.artistUri, artists = track.artists,
album = track.album, albumUri = track.albumUri,
durationMs = track.durationMs, artworkUri = track.artworkUrl?.let(Uri::parse),
explicit = track.explicit, recommended = true,
) })
onQueueChanged()
pushOrder()
invalidateState()
android.util.Log.i("SquareSmartShuffle", "enabled, queue=${queue.items.size}")
} catch (e: Exception) {
if (e !is kotlinx.coroutines.CancellationException) smartUnavailableContext = context
throw e
} finally { smartLoading = false }
}
override fun handleSetShuffleModeEnabled(shuffleModeEnabled: Boolean): ListenableFuture<*> {
if (queue.smartShuffle) queue.disableSmartShuffle()
shuffleEnabled = shuffleModeEnabled
queue.setShuffled(shuffleModeEnabled)
onQueueChanged()
// Deliberately not passed on to the Connect device, and its own shuffle
// is held off instead.
//
// Both sides can shuffle, and both doing it is one shuffle too many: the
// queue on screen is this list in this order, and the device was being
// handed that list and then reordering it again for itself. A track put
// up next landed somewhere else entirely, the engine played whatever its
// own permutation said, and what came back looked like the queue being
// thrown away and rebuilt.
//
// The order on screen is the one the user arranged, so it wins. The cost
// is that the account shows this device as not shuffling.
runCatching { NativeBridge.setShuffle(false) }
// And the engine is given the new order at once.
//
// Reordering only this side is what made shuffling break playback: the
// engine went on playing the list it was handed, the screen followed
// the tracks the engine announced, and the two orders no longer agreed
// on what came next. A skip then asked for the track after the one on
// screen while the engine stepped through its own list, so tracks
// appeared to be missed — and it survived shuffle being turned off
// again, because turning it off is another reorder this side only.
//
// Handed over as an order rather than as a load. A load would restart
// the decoder, and a reordering of what comes later has no business
// interrupting the song that is playing.
pushOrder()
invalidateState()
return Futures.immediateVoidFuture()
}
/**
* Hands the engine the running order, without touching what is playing.
*
* A load would restart the decoder; a change to what comes *after* the
* current track has no business interrupting it. When it cannot be sent the
* queue is marked stale, and the next skip rebuilds it wholesale — better a
* load then than a wrong order now.
*/
private fun pushOrder() {
if (queue.items.isEmpty()) return
engineIndex = queue.currentIndex
runCatching {
NativeBridge.setQueueOrder(queue.items.map { it.uri }, queue.currentIndex)
}.onFailure {
android.util.Log.w("SquarePlayer", "could not reorder: ${it.message}")
engineQueueStale = true
}
}
override fun handleSetRepeatMode(repeatMode: @Player.RepeatMode Int): ListenableFuture<*> {
this.repeatMode = repeatMode
engine("repeat") {
NativeBridge.setRepeat(
repeatContext = repeatMode == Player.REPEAT_MODE_ALL,
repeatTrack = repeatMode == Player.REPEAT_MODE_ONE,
)
}
invalidateState()
return Futures.immediateVoidFuture()
}
override fun handleRelease(): ListenableFuture<*> {
released = true
if (dev.lelonio.square.data.RemoteConnect.resumeHereHandler === resumeHereHandler) {
dev.lelonio.square.data.RemoteConnect.resumeHereHandler = null
}
watch.cancel()
handler.removeCallbacks(sessionWatch)
handler.removeCallbacks(settleSkip)
focus.release()
engine("shutdown") { NativeBridge.shutdown() }
return Futures.immediateVoidFuture()
}
// --- NativeEvents: arrives on a tokio worker thread ---
override fun onEvent(type: String, uri: String, positionMs: Long) {
// Downloads travel on this channel because the engine has one listener
// and one JVM attachment, not because they have anything to do with
// what is playing. Taken off here rather than posted to the player's
// handler, where a progress tick several times a second would queue
// behind whatever the player is in the middle of.
if (dev.lelonio.square.download.DownloadEvents.accept(type, uri, positionMs)) return
if (type == "key_refused") {
handler.post { onKeyRefused(positionMs) }
return
}
// Set on this device from another of the account's; the timer is the
// app's own, so the screen and the countdown are the ones it always has.
if (type == "sleep_timer") {
handler.post {
when {
positionMs < 0 -> SleepTimer.cancel()
positionMs == 0L -> SleepTimer.atEndOfTrack()
else -> SleepTimer.inSeconds(positionMs)
}
}
return
}
handler.post { applyEvent(type, uri, positionMs) }
}
/** Whether the listener has been told Spotify is refusing songs. */
private var refusalShown = false
/**
* Where it is remembered that Spotify refuses this account every song,
* across restarts: a fresh start would otherwise tell them to try again in
* a few minutes all over again. Forgotten when a song plays.
*/
private val keyNotes by lazy {
appContext.getSharedPreferences("square_keys", android.content.Context.MODE_PRIVATE)
}
/**
* Spotify refusing the key a song needs to play, or giving them again: 0
* over, 1 refused, 2 refused to this account whatever is tried; see
* audio_key.rs.
*
* Said in words for the listener rather than the reason: otherwise the
* song sits at the start with no time on it, and what that looks like is
* the app broken. Once for a run of refusals, and once more if the run
* turns out to be the account's, since the advice is not the same.
*/
private fun onKeyRefused(what: Long) {
if (what == 0L) {
refusalShown = false
keyNotes.edit().remove(ACCOUNT_REFUSED).apply()
dev.lelonio.square.playback.websdk.WebSdkRecovery.refresh(appContext)
return
}
val account = what == 2L || keyNotes.getBoolean(ACCOUNT_REFUSED, false)
if (what == 2L) {
keyNotes.edit().putBoolean(ACCOUNT_REFUSED, true).apply()
dev.lelonio.square.playback.websdk.WebSdkRecovery.refresh(appContext)
} else if (refusalShown) {
return
}
refusalShown = true
// Said first, whatever happens next: an account refused every key was
// otherwise left with the advice to wait a few minutes, which cannot
// help, or with only the web player's setup and no reason for it.
android.widget.Toast.makeText(
appContext,
appContext.getString(
if (account) {
dev.lelonio.square.R.string.playback_refused_account
} else {
dev.lelonio.square.R.string.playback_refused
},
),
android.widget.Toast.LENGTH_LONG,
).show()
// The whole account refused: there is another way to play it.
if (account) {
dev.lelonio.square.backend.spotify.SpotifyWebPlayback.reportAccountRefused()
}
}
/**
* Jumps to the next track if it is one the engine cannot know about.
*
* Called as the current track ends, not when the track was queued: a reload
* mid-playback restarts what is playing, while here there is a moment of
* silence to do it in anyway.
*/
private fun takeOverForQueued(): Boolean {
val next = queue.currentIndex + 1
if (!engineQueueStale || next > queue.items.lastIndex) return false
if (!queue.items[next].queued) return false
requestSkipTo(next, 0L)
return true
}
/**
* Moves to the next track, offline, where nothing else will.
*
* With a connection the Connect device owns the queue: it loads the next
* track while the current one is still sounding, and that overlap is what
* the crossfade is made of. Offline there is no device, so the app has to
* be the one that looks ahead — otherwise a track ends, the player stops,
* and the next one is loaded into silence. That is why offline had no
* dissolve at all, and why the queue stopped at the end of every song
* unless somebody pressed skip.
*
* @param early true when this is the run-up to a crossfade rather than the
* end of the track, which is the only difference between a dissolve and a
* plain advance.
*/
private fun advanceOffline(early: Boolean) {
val from = queue.currentIndex
val current = queue.items.getOrNull(from) ?: return
if (advancedFrom == current.uri) return
val next = from + 1
// The end of the queue is the end. Repeat is the engine's own setting
// and it is not reachable from here; a queue that restarted itself
// offline would be doing something the listener did not ask for.
if (next > queue.items.lastIndex) return
advancedFrom = current.uri
android.util.Log.i(
"SquarePlayer",
"offline: ${if (early) "dissolving into" else "advancing to"} track $next",
)
requestSkipTo(next, 0L)
}
/**
* Gives the engine the transition into the song after this one, when the
* playlist playing is mixed and has one for exactly this pair; takes it
* away otherwise. See Mixes and librespot-playback's MixPlan.
*
* Asked on every event, since the pair changes with the song, a skip, a
* reorder or the mix being switched off, and the answer is a lookup;
* the engine is only told when it changes.
*/
private fun followMix() {
Mixes.follow(queue.contextUri)
val current = queue.items.getOrNull(queue.currentIndex)?.uri
val next = queue.items.getOrNull(queue.currentIndex + 1)?.uri
val transition = if (current != null && next != null && repeatMode != Player.REPEAT_MODE_ONE) {
Mixes.transition(queue.contextUri, current, next)
} else {
null
}
val key = transition?.let { "${it.from}>${it.to}" }.orEmpty()
if (key == mixPlanFor) return
mixPlanFor = key
android.util.Log.i("SquarePlayer", "mix plan: ${transition?.planJson() ?: "none"} (context ${queue.contextUri})")
NativeBridge.setMixPlan(transition?.planJson().orEmpty())
}
private fun applyEvent(type: String, uri: String, eventPositionMs: Long) {
if (released) return
// One line per track change, and nothing for the events that arrive
// several times a second. What a skip that nobody asked for looks like
// afterwards is a sequence of these, and without them the only record
// of it is the engine's own log — which says what the engine did, not
// what this side made of it.
if (type != "position" && type != "progress") {
android.util.Log.i(
"SquarePlayer",
"engine $type $uri at ${eventPositionMs}ms " +
"(queue ${queue.currentIndex}/${queue.items.size}, engine $engineIndex, " +
"sounding=$sounding, skipPending=$skipPending, own=$ownQueuePending)",
)
}
// A song playing is the account being given keys after all.
if (type == "playing" && keyNotes.contains(ACCOUNT_REFUSED)) {
keyNotes.edit().remove(ACCOUNT_REFUSED).apply()
dev.lelonio.square.playback.websdk.WebSdkRecovery.refresh(appContext)
}
// Nothing is coming out of the speaker any more, so the next load is a
// real move rather than a head start on what is coming.
if (type == "stopped" || type == "end_of_track" || type == "unavailable") {
sounding = false
}
// The engine decides what plays next now, so the current index is
// followed rather than set: an advance, a remote skip from another
// device and a local one all arrive here the same way.
if (uri.isNotEmpty()) {
val index = queue.nearestIndexOf(uri, engineIndex.takeIf { it >= 0 } ?: queue.currentIndex)
if (
index < 0 && !ownQueuePending &&
(type == "playing" || type == "loading") && unknownAsked != uri
) {
// Not ours: somebody else chose it. Asked for once per track,
// and only on a track that is actually starting, so a position
// report on a queue mid-rebuild does not set this going.
android.util.Log.i(
"SquarePlayer",
"engine is $type $uri, which is not in this queue of ${queue.items.size}",
)
unknownAsked = uri
onUnknownTrack?.invoke(uri)
}
if (index >= 0) {
unknownAsked = null
ownQueuePending = false
handler.removeCallbacks(giveUpOnOwnQueue)
engineIndex = index
if (index == queue.currentIndex) {
// The engine is where it was asked to be.
skipPending = false
handler.removeCallbacks(skipGaveUp)
skipInFlight = false
if (type == "playing") sounding = true
if (type == "playing" || type == "loading") positionMs = 0
} else if (!skipPending && (type == "playing" || type == "paused")) {
// The engine is the truth about what is coming out of the
// speaker. While a skip is on its way its events are about
// the track being left, and following them dragged the
// screen backwards — but once nothing is outstanding, the
// screen was simply wrong to disagree.
//
// Only what is playing. A load is not a track change:
// the engine fetches what is coming next while the current
// song plays, and following those walked the screen one or
// two songs ahead of the speaker. A run of tracks the
// account cannot play still lands here, because each of
// those ends in the engine playing something and that is
// the event this follows.
queue.currentIndex = index
skipInFlight = false
sounding = type == "playing"
positionMs = 0
}
}
}
if (uri.isNotEmpty()) followMix()
when (type) {
"loading" -> {
engineStopped = false
playbackState = Player.STATE_BUFFERING
if (uri.isNotEmpty()) bandwidth.loading(uri)
// Loaded straight into the player, around Connect: nobody but
// this side will move on from it, even once the session is back.
outsideSpirc = deviceGone
loadInFlight = true
handler.removeCallbacks(stallWatch)
}
"playing" -> {
wantPlay = true
// A new track to watch, and one this side has not moved on
// from yet.
if (uri != advancedFrom) advancedFrom = null
playbackState = Player.STATE_READY
playWhenReady = true
if (uri.isNotEmpty()) bandwidth.playing(uri)
loadInFlight = false
expectProgress()
if (!skipInFlight) positionMs = eventPositionMs
// Here as well as in handleSetPlayWhenReady: a pause can arrive
// from the notification, from a headset button or from another
// Connect device, and only this path sees all of them.
onPlaybackActive(true)
}
"paused" -> {
if (!reconnecting && !deviceGone) wantPlay = false
playbackState = Player.STATE_READY
playWhenReady = false
// A pause is not a stall.
handler.removeCallbacks(stallWatch)
if (!skipInFlight) positionMs = eventPositionMs
onPlaybackActive(false)
}
"position" -> {
// Progress arrived, so the stream is keeping up: the watch is
// wound again rather than left to fire.
expectProgress()
// The old track goes on reporting until the new one starts.
// Taking those would run the bar forward on a song that is no
// longer the one on screen.
if (skipPending || skipInFlight) return
positionMs = eventPositionMs
// Offline, the run-up to the next track is this side's job.
//
// Started exactly one crossfade before the end, so the two
// tracks overlap by the length the listener asked for. With the
// setting at zero there is nothing to run up to, and the track
// is left to end on its own.
if (ownsAdvance()) {
val length = queue.items.getOrNull(queue.currentIndex)?.durationMs ?: 0L
val fade = crossfade.durationMs().toLong()
if (fade > 0 && length > 0 && length - eventPositionMs in 1..fade) {
advanceOffline(early = true)
}
}
}
"stopped" -> {
if (!reconnecting && !deviceGone) wantPlay = false
playbackState = Player.STATE_IDLE
playWhenReady = false
engineStopped = true
onPlaybackActive(false)
}
// Both used to advance the queue from here. The engine does it now
// — it owns the queue — so acting on them as well would skip two
// tracks for every one that ended.
//
// Except for a track put here by "add to queue": the engine's list
// does not contain it, so left alone it would play the playlist's
// own next one and the queued track would never be heard. Taking
// over reloads the queue, which is the only way to tell Spirc about
// an insertion.
// Something changed on another of the account's devices. Nothing
// here plays, so nothing here has to react: the state is read and
// published, and whoever is showing it redraws.
"cluster" -> {
dev.lelonio.square.data.RemoteConnect.refresh()
// And again shortly after.
//
// A handover is two facts arriving separately: the account says
// which device is active, and the engine works out whether that
// is this one. They settle a moment apart, and whichever is
// read first leaves the screen describing the wrong device
// until something else happens to change it, which can be
// never. The second look costs two reads of memory.
handler.postDelayed({ dev.lelonio.square.data.RemoteConnect.refresh() }, 700)
handler.postDelayed({ dev.lelonio.square.data.RemoteConnect.refresh() }, 2_000)
return
}
"end_of_track" -> {
if (takeOverForQueued()) return
// Offline the engine has no queue to advance, so a track that
// ran to its end without a crossfade — because the setting is
// off, or because it was shorter than one — stops here unless
// this side moves on.
//
// Except when this is the end of the track already being
// dissolved out of. That event belongs to the song being left,
// and it arrives milliseconds after the crossfade has started —
// by which point the queue has moved on, so advancing again
// stepped over the track that was just beginning. One song in
// two was skipped without ever being heard, which is what "it
// sometimes jumps straight to the next one" was.
if (uri == advancedFrom) return
if (ownsAdvance()) advanceOffline(early = false)
return
}
// A track the engine could not load, after it has already tried
// again a few times. Only ever acted on for the track that is
// actually playing: the same event is sent when the *next* track
// fails to preload, and taking that as "move on" skipped the song
// the listener was in the middle of because a later one was slow to
// arrive.
"unavailable" -> {
val current = queue.items.getOrNull(queue.currentIndex)?.uri
if (uri.isEmpty() || uri == current) takeOverForQueued()
return
}
else -> return
}
// Whether the music is here or somewhere else can change without any
// word from the account: taking playback back starts this player, and
// the cluster may say nothing for a minute afterwards. The screen was
// deciding with an answer from before the handover, which is how a
// pause pressed here went out to a laptop.
if (type == "playing" || type == "paused" || type == "stopped") {
dev.lelonio.square.data.RemoteConnect.refresh()
}
invalidateState()
}
/**
* @param id the queue entry's own id, as the uid: unique even when the same
* track is in the queue twice (the URI alone crashes with "Duplicate
* MediaItemData UID in playlist"), and the same wherever the entry is
* moved. The position used to be part of it, so a move gave every item
* between the two places a new uid, and Media3 saw tracks replaced rather
* than one track moved.
*/
private fun toMediaItemData(id: Long, track: PlayQueue.Track) =
MediaItemData.Builder("q$id smart=${queue.smartShuffle}")
.setMediaItem(
MediaItem.Builder()
.setMediaId(track.uri)
.setMediaMetadata(
MediaMetadata.Builder()
.setTitle(track.title)
.setArtist(track.artist)
.setAlbumTitle(track.album.takeIf { it.isNotEmpty() })
.setArtworkUri(track.artworkUri)
// Put back, because this item is rebuilt rather than
// passed through: whatever is not restored here is
// lost to everything reading the player, which is
// how the artist's name stopped being a link the
// moment the queue was rebuilt.
.setExtras(
android.os.Bundle().apply {
putBoolean(dev.lelonio.square.data.SmartShuffle.MODE, queue.smartShuffle)
putBoolean(dev.lelonio.square.data.SmartShuffle.RECOMMENDED, track.recommended)
queue.contextLabel.takeIf { it.isNotEmpty() }?.let {
putString(EXTRA_CONTEXT_LABEL, it)
}
queue.contextUri?.let {
putString(dev.lelonio.square.ui.EXTRA_CONTEXT_URI, it)
}
track.artistUri?.let {
putString(dev.lelonio.square.ui.EXTRA_ARTIST_URI, it)
}
track.albumUri?.let {
putString(dev.lelonio.square.ui.EXTRA_ALBUM_URI, it)
}
if (track.explicit) {
putBoolean(dev.lelonio.square.ui.EXTRA_EXPLICIT, true)
}
val credited = track.artists.filter { it.uri != null }
if (credited.isNotEmpty()) {
putStringArrayList(
dev.lelonio.square.ui.EXTRA_ARTIST_NAMES,
ArrayList(credited.map { it.name }),
)
putStringArrayList(
dev.lelonio.square.ui.EXTRA_ARTIST_URIS,
ArrayList(credited.map { it.uri!! }),
)
}
},
)
.build(),
)
.build(),
)
.setDurationUs(track.durationMs * 1_000)
.setIsSeekable(true)
.setIsDynamic(false)
.build()
private companion object {
/**
* How long the music may go without reporting progress before the
* buffer is taken to have run dry.
*
* Progress arrives once a second, so three is a gap and not a jitter.
*/
const val STALL_AFTER_MS = 3_500L
/**
* How long skips are gathered for before the engine is told.
*
* Long enough that a run of taps becomes one decision, short enough
* that a single skip does not feel delayed.
*/
const val SKIP_SETTLE_MS = 220L
/** Set while Spotify is refusing this account every song; see onKeyRefused. */
const val ACCOUNT_REFUSED = "account_refused"
/**
* How long a skip is given to land before its events count again.
*
* Long enough for a slow load — the network is the reason this exists —
* and short enough that a command lost on the way does not leave the
* screen ignoring the engine for ever.
*/
const val SKIP_CONFIRM_MS = 8_000L
/**
* How long a queue is given to reach the engine; see [ownQueuePending].
*
* Measured at about seven hundred milliseconds from the tap to the
* first event about the new track, on a cold session that was still
* connecting. This is that with room to spare, and short enough that a
* queue which never arrived leaves adoption working again.
*/
const val OWN_QUEUE_MS = 6_000L
/** Ducked volume, as a fraction of the current one. */
const val DUCK_FACTOR = 0.3
/** Everything the engine and this queue can actually carry out. */
val COMMANDS: Player.Commands = Player.Commands.Builder()
.addAll(
Player.COMMAND_PLAY_PAUSE,
Player.COMMAND_PREPARE,
Player.COMMAND_STOP,
Player.COMMAND_SEEK_TO_NEXT,
Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM,
Player.COMMAND_SEEK_TO_PREVIOUS,
Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM,
Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM,
Player.COMMAND_SEEK_TO_MEDIA_ITEM,
Player.COMMAND_SET_MEDIA_ITEM,
// Required for setMediaItems(list, index, position). Without it
// SimpleBasePlayer drops the call silently, so the queue is
// never handed over and the following play() reaches a stopped
// engine: "Player::play called from invalid state: Stopped".
Player.COMMAND_CHANGE_MEDIA_ITEMS,
Player.COMMAND_GET_CURRENT_MEDIA_ITEM,
Player.COMMAND_GET_TIMELINE,
Player.COMMAND_GET_METADATA,
Player.COMMAND_SET_SHUFFLE_MODE,
Player.COMMAND_SET_REPEAT_MODE,
// Speed and pitch are done by the platform's time stretcher in
// AudioOutput, not by the engine, so this is genuinely supported.
Player.COMMAND_SET_SPEED_AND_PITCH,
Player.COMMAND_RELEASE,
)
.build()
}
}