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
//! Session + playback engine.
//!
//! One process-wide instance, guarded by a mutex. All librespot work happens on
//! a dedicated multi-thread tokio runtime that outlives individual JNI calls;
//! JNI methods only enqueue commands and return immediately, so the Android main
//! thread is never blocked on network I/O.
use jni::objects::{GlobalRef, JObject, JValue};
use jni::JavaVM;
use librespot_connect::{
ConnectConfig, LoadRequest, LoadRequestOptions, PlayingTrack, Spirc,
};
use librespot_core::{
authentication::Credentials, cache::Cache, config::DeviceType, config::SessionConfig,
session::Session, spotify_uri::SpotifyUri,
};
use librespot_playback::{
config::{AudioFormat, Bitrate, NormalisationMethod, PlayerConfig},
mixer::{softmixer::SoftMixer, Mixer, MixerConfig},
player::{Player, PlayerEvent},
};
use crate::events::{self, EndReason, EventService, Listen};
use once_cell::sync::OnceCell;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Duration;
use tokio::runtime::Runtime;
pub(crate) static JAVA_VM: OnceCell<JavaVM> = OnceCell::new();
static ENGINE: Mutex<Option<Engine>> = Mutex::new(None);
static CONTEXT_INITIALIZED: AtomicBool = AtomicBool::new(false);
/// Set when a transport command had to go around Spirc; see [`transport`].
///
/// The engine is still making sound at that point, but the Connect device is
/// gone: the account has a stale idea of this phone, and nothing arriving from
/// another client will be obeyed. Only a rebuild fixes that, and only the Kotlin
/// side can decide when to do it, so this is a flag it can ask about rather than
/// something acted on here.
static SPIRC_LOST: AtomicBool = AtomicBool::new(false);
/// Whether the sink may make sound.
///
/// Every load shuts it, and the track that load asked for opens it again.
///
/// A load is a message to the Connect device, and it returns long before the
/// music changes: about a second passes while the new track is fetched, and the
/// old one is still being decoded throughout. The fade that wraps a skip is over
/// by then, so the volume came back up on the *previous* song, which played on
/// for a moment before the right one cut in.
///
/// Keyed on the track rather than on the load, which is where this was first put
/// and why it did not work: a load has to activate the device before it can hand
/// over a queue, and activating is what makes a freshly built device take up
/// whatever the account still believes this phone was playing.
static PLAYBACK_ARMED: AtomicBool = AtomicBool::new(true);
/// What the output is waiting for, when it is waiting for something.
///
/// A load knows the track it asked for, so it waits for that one. A skip does
/// not: `next` is a message to the Connect device, which picks the track
/// itself, so all this side knows is which one it wants to stop hearing.
enum Gate {
/// Open when this track starts.
Expect(String),
/// Open when anything other than this track starts.
Leave(String),
}
static GATE: Mutex<Option<Gate>> = Mutex::new(None);
/// The track currently being played, so a skip knows what it is leaving.
static CURRENT_URI: Mutex<String> = Mutex::new(String::new());
/// When to give up waiting, in milliseconds since the first call to [`uptime_ms`].
///
/// Silence that outlives its reason is worse than the noise it was there to
/// stop: a command that never lands would otherwise leave the app mute with no
/// way back except a restart.
static ARM_BY_MS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
/// How long the output stays shut while waiting.
const ARM_TIMEOUT_MS: u64 = 15_000;
static STARTED: OnceCell<std::time::Instant> = OnceCell::new();
fn uptime_ms() -> u64 {
STARTED
.get_or_init(std::time::Instant::now)
.elapsed()
.as_millis() as u64
}
/// Whether the sink may write. See [`PLAYBACK_ARMED`].
pub(crate) fn playback_armed() -> bool {
PLAYBACK_ARMED.load(Ordering::SeqCst) || uptime_ms() >= ARM_BY_MS.load(Ordering::SeqCst)
}
/// How a track is fetched, which is most of how long it takes to start.
///
/// While a track is being opened the file is in random-access mode: every read
/// the decoder makes that lands on bytes nobody has yet asks the CDN for a
/// block and waits for it. Symphonia makes several of those — the Ogg headers,
/// Spotify's own normalisation packet, then the seek to the starting position —
/// and with librespot's default block of 64 KiB each one is a separate request
/// with a full round trip in front of it. Measured on this phone, on a healthy
/// connection: the download itself took 300 ms and opening the decoder took two
/// seconds, all of it waiting for those small blocks.
///
/// What is left here are the waits, not the sizes: a phone on wifi is not half
/// a second away from a CDN, and half a second of audio in hand is enough to
/// start on. The block size is the crate's own; see the note beside it.
///
/// Set once for the process; a second call is refused by the crate and ignored
/// here, which is right — the first player's numbers are as good as the next's.
fn tune_fetching() {
use std::time::Duration;
// Back at the crate's own size, and deliberately.
//
// Raising it looked obvious — fewer requests for the same bytes — and made
// things worse: while a track is opening, every read the decoder makes on
// bytes nobody has fetches a whole block and waits for it, so a bigger
// block is a longer wait at each of those. What actually cost the time was
// the seek that is no longer done at all; see the note in player.rs.
let minimum_download_size = 64 * 1024;
let minimum_throughput = 8 * 1024;
let _ = librespot_audio::AudioFetchParams::set(librespot_audio::AudioFetchParams {
minimum_download_size,
minimum_throughput,
// A phone on wifi is not half a second away from a CDN, and assuming it
// is makes the loader hold back on the prefetch that would hide the
// next round trip.
initial_ping_time_estimate: Duration::from_millis(150),
maximum_assumed_ping_time: Duration::from_millis(800),
// What has to be in hand before the first sample is played. A second is
// a second of waiting on every track; half of one is still several
// blocks at this size.
read_ahead_before_playback: Duration::from_millis(500),
// Keep 5 seconds of audio decoded and cached ahead during playback.
read_ahead_during_playback: Duration::from_secs(5),
prefetch_threshold_factor: 4.0,
// A block that has not arrived in fifteen seconds is not going to.
download_timeout: Duration::from_secs(15),
});
}
/// Shuts the output until `gate` is satisfied.
fn shut(gate: Gate) {
if let Ok(mut current) = GATE.lock() {
*current = Some(gate);
}
ARM_BY_MS.store(uptime_ms() + ARM_TIMEOUT_MS, Ordering::SeqCst);
PLAYBACK_ARMED.store(false, Ordering::SeqCst);
}
/// The track this device is on, for a skip to name as the one it is leaving.
fn current_uri() -> String {
CURRENT_URI.lock().map(|uri| uri.clone()).unwrap_or_default()
}
/// Notes which track is playing, and opens the output if this is the one it was
/// waiting for.
fn track_started(uri: &str) {
if let Ok(mut current) = CURRENT_URI.lock() {
*current = uri.to_string();
}
if PLAYBACK_ARMED.load(Ordering::SeqCst) {
return;
}
let satisfied = match GATE.lock().as_deref() {
Ok(Some(Gate::Expect(wanted))) => wanted == uri,
Ok(Some(Gate::Leave(old))) => old != uri,
// Nothing to wait for: whatever shut the output has no opinion left.
_ => true,
};
if satisfied {
log::info!("output open again on {uri}");
PLAYBACK_ARMED.store(true, Ordering::SeqCst);
}
}
/// Set while [`reconnect`] is between two bundles.
///
/// Read without the engine lock, which is the point: the lock is held across a
/// handshake and the questions asked during one must still be answerable.
static RECONNECTING: AtomicBool = AtomicBool::new(false);
pub fn store_java_vm(vm: JavaVM) {
let _ = JAVA_VM.set(vm);
}
/// The parts that outlive a reconnection.
///
/// Split from [`Bundle`] because losing the network costs the session, and
/// getting it back means building another one: librespot hands out the Spirc
/// builder once per session, so nothing short of a new session brings the
/// Connect device back. The two things that must *not* be rebuilt are here.
///
/// The runtime is one of them. Dropping it means `shutdown_timeout` from a JNI
/// thread while librespot's own threads are still inside it, and that aborted
/// the process on a destroyed mutex. The audio output is the other: it belongs
/// to the Android service, not to any session, and clearing it mid-life is the
/// second half of the same crash. Neither is touched by [`reconnect`].
pub struct Engine {
rt: Runtime,
mixer: Arc<SoftMixer>,
/// Everything needed to build another [`Bundle`], kept so a reconnection
/// needs nothing from the Kotlin side.
recipe: Recipe,
/// Where player events go. Owned here so the pump thread, and with it the
/// listener reference, lives as long as the engine rather than as long as
/// any one player.
events_tx: std::sync::mpsc::Sender<Pump>,
/// `None` only while [`reconnect`] is between two of them.
bundle: Option<Bundle>,
}
/// Session, player and Connect device: one network lifetime, thrown away whole.
struct Bundle {
session: Session,
player: Arc<Player>,
/// The Connect device. Every transport command goes through it; see [`load`].
///
/// `None` for an offline bundle: with no connection there is no device to
/// register, no account to publish state to, and nothing on the other end
/// of a command. The player is still there, and a downloaded track still
/// plays through it — which is the whole of what offline means here.
spirc: Option<Spirc>,
}
impl Bundle {
/// The Connect device, or the error a command on a missing one becomes.
///
/// Every transport call goes through this rather than testing for offline
/// first: the callers already handle a Spirc that refuses — that is what a
/// lost device looks like — and refusing is exactly the right answer when
/// there is no device at all.
fn spirc(&self) -> Result<&Spirc, librespot_core::Error> {
self.spirc
.as_ref()
.ok_or_else(|| librespot_core::Error::unavailable("no connect device: offline"))
}
}
/// The inputs to a [`Bundle`], all of them cheap to clone.
#[derive(Clone)]
struct Recipe {
session_config: SessionConfig,
player_config: PlayerConfig,
connect_config: ConnectConfig,
/// The OAuth credentials from the original login, if the caller had a token
/// to give. Only the first login really needs one: the access point answers
/// a successful handshake with a reusable credential, which is kept and used
/// from then on. Empty means "use what was kept".
credentials: Option<Credentials>,
credentials_dir: String,
cache_dir: String,
}
/// What the event pump reads.
///
/// Events are the reason it exists; the session arrives with every new bundle,
/// because listening history is reported through the session and the pump holds
/// one for the life of the engine.
enum Pump {
Event(PlayerEvent),
Session(Session),
/// Something changed on another of the account's devices; see `remote`.
Cluster,
/// Something the engine says that the player did not: download progress.
///
/// The same channel as everything else so it arrives on the same thread and
/// in order with the rest, rather than a second JNI path attaching worker
/// threads of its own.
App { kind: String, uri: String, value: i64 },
}
/// Errors are flattened to a string because they cross the JNI boundary and the
/// Kotlin side only ever surfaces them as a message.
pub type EngineResult<T> = Result<T, String>;
fn with_engine<T>(f: impl FnOnce(&Engine) -> T) -> EngineResult<T> {
let guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_ref().ok_or("engine not started")?;
Ok(f(engine))
}
/// Borrow the current session, player and Connect device together.
///
/// Separate from [`with_engine`] because these three are replaced as a set: a
/// caller holding one of them alongside a stale copy of another would be holding
/// two different network lifetimes.
fn with_bundle<T>(f: impl FnOnce(&Bundle) -> T) -> EngineResult<T> {
let guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_ref().ok_or("engine not started")?;
let bundle = engine.bundle.as_ref().ok_or("engine is reconnecting")?;
Ok(f(bundle))
}
/// Borrow the authenticated session, e.g. to clone it for a catalogue request.
pub fn with_session<T>(f: impl FnOnce(&Session) -> T) -> EngineResult<T> {
with_bundle(|bundle| f(&bundle.session))
}
/// A handle to the engine's runtime.
///
/// Returned by value so callers can release the engine lock before blocking on
/// a request; holding it across an await would serialise playback commands
/// behind network I/O.
pub fn runtime_handle() -> EngineResult<tokio::runtime::Handle> {
with_engine(|engine| engine.rt.handle().clone())
}
/// Publish an application `Context` to `ndk_context` so cpal's AAudio host can
/// resolve the output device. Must run before any playback starts.
///
/// Idempotent. `ndk_context::initialize_android_context` asserts that no context
/// was set before and aborts the process otherwise, and the Android service that
/// calls this can be destroyed and recreated any number of times within one
/// process. The context never changes over that lifetime, so the second and
/// later calls are simply no-ops.
pub fn init_android_context(context: &JObject) -> EngineResult<()> {
if CONTEXT_INITIALIZED.swap(true, Ordering::SeqCst) {
return Ok(());
}
let vm = JAVA_VM.get().ok_or("JNI_OnLoad did not run")?;
let env = vm.get_env().map_err(|e| e.to_string())?;
let global = env
.new_global_ref(context)
.map_err(|e| format!("failed to pin Context: {e}"))?;
// SAFETY: both pointers stay valid for the lifetime of the process — the VM
// is never destroyed on Android, and `global` is deliberately leaked so the
// Context reference is never collected while ndk_context holds it.
#[cfg(target_os = "android")]
unsafe {
ndk_context::initialize_android_context(
vm.get_java_vm_pointer() as *mut _,
global.as_raw() as *mut _,
);
}
std::mem::forget(global);
Ok(())
}
/// Build the session and player, then authenticate with an OAuth access token
/// obtained by the Kotlin side.
///
/// `listener` must implement `dev.lelonio.square.nativecore.NativeEvents`.
pub fn start(
client_id: &str,
device_name: &str,
device_id: &str,
access_token: &str,
credentials_dir: &str,
cache_dir: &str,
language: &str,
bitrate_kbps: i32,
crossfade_ms: i32,
listener: GlobalRef,
) -> EngineResult<()> {
tune_fetching();
// Checked, and let go: the lock is not held across the first handshake.
// See the note where the engine is put in place below.
if ENGINE.lock().map_err(|_| "engine mutex poisoned")?.is_some() {
return Err("engine already started".into());
}
let rt = tokio::runtime::Builder::new_multi_thread()
.worker_threads(2)
.enable_all()
.thread_name("squarecore")
.build()
.map_err(|e| format!("failed to build runtime: {e}"))?;
// An empty `client_id` means "use the platform default", which on Android is
// the client id librespot ships for the official mobile app. login5 only
// grants streaming to ids it recognises, so overriding this with a client id
// registered in the Spotify dashboard will authenticate against the Web API
// but be rejected at the access point.
let mut session_config = SessionConfig::default();
session_config.tmp_dir = std::path::PathBuf::from(cache_dir);
// What Spotify should answer in. Artwork for the generated playlists is
// localised — the language is in the cover's own URL — so a client that
// never says which one it wants gets English tiles.
if !language.is_empty() {
session_config.language = language.to_string();
}
if !client_id.is_empty() {
session_config.client_id = client_id.to_string();
}
// The same id on every launch, chosen by the app and kept by it.
//
// librespot's default is a fresh uuid per session, which is right for a
// daemon started once and wrong for a phone: the account saw a new "A059"
// every time the engine came up, the list filled with ghosts of this same
// device, and nothing could recognise the phone it had been playing on an
// hour earlier.
if !device_id.is_empty() {
session_config.device_id = device_id.to_string();
}
let credentials = if access_token.is_empty() {
None
} else {
Some(Credentials::with_access_token(access_token))
};
let mixer = Arc::new(
SoftMixer::open(MixerConfig::default()).map_err(|e| format!("mixer failed: {e}"))?,
);
// SoftMixer::open starts at an attenuation factor of 0.5 — half amplitude,
// about -6 dB — and nothing else ever sets it, so every track played through
// this engine was quiet by default. The device's own volume keys are the
// right place to control loudness, so the software mixer is left wide open.
mixer.set_volume(u16::MAX);
let player_config = PlayerConfig {
// Downloaded tracks play from the phone. Read on every load rather
// than handed over as a list, since downloads come and go while the
// player is running; see downloads::lookup.
download_lookup: Some(crate::downloads::lookup()),
// And whether anything else may be played at all. Offline — by the
// listener's own switch, or because the engine has no session — a track
// with no file fails to load rather than being fetched.
downloads_only: Some(Arc::new(|| {
OFFLINE_ONLY.load(Ordering::SeqCst) || OFFLINE.load(Ordering::SeqCst)
})),
// Chosen by the caller. The bitrate is read when a track is loaded but
// the player owns its config for its whole life, so changing this means
// building a new engine: see PlaybackService.
bitrate: match bitrate_kbps {
96 => Bitrate::Bitrate96,
160 => Bitrate::Bitrate160,
_ => Bitrate::Bitrate320,
},
// Loudness normalisation, which is what keeps one track from being
// twice as loud as the next.
//
// On its own it made the app quieter than everything else on the phone:
// it pulls every track down towards a target and nothing puts the level
// back. The pregain is what puts it back — Spotify's own "loud" setting
// is about three decibels over its normal one, and a couple more brings
// this level with apps that do no normalisation at all.
normalisation: true,
normalisation_pregain_db: 5.0,
// The limiter, not a flat scale: with five decibels added, the loudest
// moments of a loud master would otherwise clip.
normalisation_method: NormalisationMethod::Dynamic,
// Dithering runs per sample — 88200 times a second at 44.1 kHz stereo —
// for a noise-floor benefit nobody hears on a phone. Off, to leave the
// decoder more headroom against output underruns.
ditherer: None,
// Every update crosses JNI and rebuilds the Media3 state on the main
// thread; once a second is plenty for a seek bar.
position_update_interval: Some(Duration::from_secs(1)),
// How long one track dissolves into the next, chosen by the user. See
// the patch notes in native/vendor/README.md: the player asks for the
// next track a fade early and mixes the one going out underneath it.
// Fixed for the life of the player, like the bitrate, so the service
// builds a new engine when the setting changes.
crossfade_duration_ms: crossfade_ms.max(0) as u32,
..PlayerConfig::default()
};
// Spirc is what makes this a Spotify Connect device: it publishes the
// playback state to the account, which is also the only way plays are
// recorded in listening history — Spotify counts what a device reports, not
// what it decodes. That is why nothing appeared in the history before this
// existed.
//
// It owns the player from here on. Driving the player directly as well would
// play audio the published state knows nothing about, so every transport
// command below goes through the Spirc handle instead.
let connect_config = ConnectConfig {
name: device_name.to_string(),
// Smartphone rather than the librespot default of Speaker: the icon in
// the device list should match what the user is holding.
device_type: DeviceType::Smartphone,
// Full scale, matching the mixer. Loudness belongs to the phone's own
// volume keys.
initial_volume: u16::MAX,
..ConnectConfig::default()
};
let recipe = Recipe {
session_config,
player_config,
connect_config,
credentials,
credentials_dir: credentials_dir.to_string(),
cache_dir: cache_dir.to_string(),
};
// Started before the first bundle, and outliving every one of them: the pump
// owns the listener reference, and that must be dropped on a thread still
// attached to the JVM. Tying it to a player would mean dropping it whenever
// a reconnection replaced one.
let (events_tx, events_rx) = std::sync::mpsc::channel();
// Spotify refusing the keys a song needs, told to the app so it can say so
// rather than sit on a song that never starts. See the patch in audio_key.
librespot_core::audio_key::on_playback_refusal(|what| emit_app("key_refused", "", what));
// A sleep timer set on this device from another of the account's; the
// timer is the app's, see librespot-connect's sleep_timer.
librespot_connect::sleep_timer::on_request(|value| emit_app("sleep_timer", "", value));
spawn_event_pump(
events_rx,
listener,
device_name.to_string(),
cache_dir.to_string(),
);
// In place before the handshake, with no bundle yet, and the handshake
// made without the lock.
//
// It used to hold the engine lock for the whole of the first connection,
// which on a slow network is seconds, and a song tapped in those seconds
// asked the engine for it on the main thread and waited as long: long
// enough for Android to call the app unresponsive (#33). The same was
// true of a reconnection, fixed in #31. Anything that asks in the
// meantime now hears "reconnecting", which every caller already handles.
let handle = rt.handle().clone();
RECONNECTING.store(true, Ordering::SeqCst);
{
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
*guard = Some(Engine {
rt,
mixer: mixer.clone(),
recipe: recipe.clone(),
events_tx: events_tx.clone(),
bundle: None,
});
}
// The handshake, and what to do when it cannot be made.
//
// A failure here used to be the end of the app: no session, no player, no
// sound, whatever was already on the phone. With downloads that is the
// wrong answer — the music is right there — so a failed connection falls
// back to a session that was never connected and a player that only ever
// reads from disk. See [`build_offline_bundle`].
//
// A refused account is not covered: that is Spotify saying no, not the
// network being absent, and starting anyway would hide it behind an app
// that plays a few downloaded songs and explains nothing.
let built = match build_bundle(&handle, &recipe, &mixer, &events_tx) {
Ok(bundle) => {
OFFLINE.store(false, Ordering::SeqCst);
Ok(bundle)
}
Err(e) if e == PREMIUM_REQUIRED => Err(e),
Err(e) if crate::downloads::any() => {
log::warn!("{e}; starting offline with what is on the phone");
OFFLINE.store(true, Ordering::SeqCst);
build_offline_bundle(&handle, &recipe, &mixer, &events_tx)
}
Err(e) => Err(e),
};
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
RECONNECTING.store(false, Ordering::SeqCst);
match built {
Ok(bundle) => {
if let Some(engine) = guard.as_mut() {
engine.bundle = Some(bundle);
}
Ok(())
}
Err(e) => {
// As if it had never started, which is what the caller expects of
// a failed start: the runtime goes with it, off the lock.
let failed = guard.take();
drop(guard);
drop(failed);
Err(e)
}
}
}
/// Builds a session, a player and a Connect device, and wires them to the pump.
///
/// Everything here is disposable. It runs on the caller's thread and blocks on
/// the handshake, so it is only ever reached from a JNI call the Kotlin side
/// makes off the main thread.
fn build_bundle(
rt: &tokio::runtime::Handle,
recipe: &Recipe,
mixer: &Arc<SoftMixer>,
events_tx: &std::sync::mpsc::Sender<Pump>,
) -> EngineResult<Bundle> {
// A credentials cache is not an optimisation here, it is required for
// catalogue access. `connect` persists reusable credentials into it, and
// login5 then issues the access point's HTTP token as a *stored credential*
// request, which it signs with the session's client id. Without a cache it
// falls back to the platform default id instead, which no longer matches the
// id the OAuth token was minted for, and every spclient call fails with
// "Login request was denied: BAD_REQUEST".
//
// Bounded, and swept before it is opened: an audio cache with no limit had
// grown past a gigabyte on the test phone, and the half-finished downloads
// librespot writes next to it — one temporary file per interrupted load, and
// skipping interrupts a lot of loads — were never collected at all.
sweep_stale_downloads(&recipe.cache_dir);
let cache = Cache::new(
Some(std::path::Path::new(&recipe.credentials_dir)),
None,
Some(std::path::Path::new(&recipe.cache_dir)),
Some(AUDIO_CACHE_LIMIT),
)
.map_err(|e| format!("cache failed: {e}"))?;
// Taken before anything can report against it, and before the player exists:
// the sink each player builds carries this number, which is what keeps a
// replaced player's last packets out of the new one's output.
//
// A discarded session does not fall silent the moment it is replaced. Its
// Spirc task ends a little later, and it ends the same way a lost one does;
// without a number to check, that tidy ending would land on the bundle that
// replaced it and mark a device that is perfectly alive as gone.
let generation = GENERATION.fetch_add(1, Ordering::SeqCst) + 1;
// Cloned before the async block takes ownership of the Arc as a `dyn Mixer`.
let mixer_for_spirc: Arc<dyn Mixer> = mixer.clone();
let session_config = recipe.session_config.clone();
let player_config = recipe.player_config.clone();
let connect_config = recipe.connect_config.clone();
// The credential the access point issued the first time this device logged
// in, kept in a directory of its own.
//
// It is the difference between a session that lasts and one that has to be
// renewed. An OAuth access token is good for an hour, and the refresh token
// behind it is rotated on every use and revoked on the first mistake, so an
// engine that needs one at every launch is one bad refresh away from asking
// the listener to sign in again. The blob the handshake answers with has
// neither property: it is what go-librespot writes to `credentials.json` and
// then reuses forever, and it is why signing in there is something you do
// once.
//
// Kept apart from librespot's own credentials file because that file is
// written by the connection itself, and what has to survive is the copy
// nothing else touches.
let kept = Cache::new(
Some(&std::path::Path::new(&recipe.credentials_dir).join("reusable")),
None,
None,
None,
)
.map_err(|e| format!("cache failed: {e}"))?;
// The kept credential first, the token second. A token is only ever the way
// in for a device that has never been in.
let attempts: Vec<(&str, Credentials)> = kept
.credentials()
.into_iter()
.map(|c| ("the kept credential", c))
.chain(recipe.credentials.clone().map(|c| ("an access token", c)))
.collect();
if attempts.is_empty() {
return Err("no credentials".into());
}
// The account's other devices, watched over the same dealer.
//
// Subscribed before the session connects, which is the whole point of doing
// it here rather than after the device is built: Spotify pushes a cluster
// update when this device appears, and that push is the only one that
// arrives without something changing later. Subscribing afterwards meant
// opening the app next to a speaker that was already playing and being told
// nothing until the speaker's track ended.
let watch_tx = events_tx.clone();
let (session, player, spirc, spirc_task) = rt.block_on(async move {
let last = attempts.len() - 1;
let mut failure = String::new();
for (n, (kind, credentials)) in attempts.into_iter().enumerate() {
log::info!("logging in with {kind}");
// Seed the cache, then hand the cached copy to `connect` with
// storing switched off. Letting `connect` store instead would
// overwrite the cache with the handshake's own blob, and what is in
// the cache is what gets sent as the stored credential when login5
// issues the access point's HTTP token.
let cache = cache.clone();
cache.save_credentials(&credentials);
let session = Session::new(session_config.clone(), Some(cache));
let watch_tx = watch_tx.clone();
crate::remote::watch(&session, move || {
let _ = watch_tx.send(Pump::Cluster);
});
// No `session.connect` here: `Spirc::new` registers its dealer
// listeners and then connects the session itself. Connecting first
// authenticated twice and left the second attempt reporting
// "Session is not connected", which is what this looked like from
// the outside.
// Read per attempt: the getter is a box the player takes, so one
// made in advance would be gone by the second time round.
let player = Player::new(
player_config.clone(),
session.clone(),
mixer.get_soft_volume(),
move || Box::new(crate::sink::AndroidSink::new(AudioFormat::S16, generation)),
);
// Given up on when the network goes, or after a while. On mobile
// data with no coverage the handshake neither finishes nor fails:
// the socket opens and nothing comes back. No player exists until
// it ends, so a downloaded song tapped in the meantime was
// refused as "reconnecting" for as long as the phone had no
// signal. Given up on, it fails like any other handshake, and the
// engine starts on what is on the phone.
let handshake = Spirc::new(
connect_config.clone(),
session.clone(),
credentials.clone(),
player.clone(),
mixer_for_spirc.clone(),
);
let connected = tokio::select! {
result = handshake => result.map_err(|e| e.to_string()),
why = handshake_abandoned() => Err(why.to_string()),
};
let (spirc, spirc_task) = match connected {
Ok(pair) => pair,
Err(e) if NETWORK_GONE.load(Ordering::SeqCst) || e == HANDSHAKE_TIMED_OUT => {
// Not the credential's fault: it is kept, and the next
// one is not tried on a network that answers nothing.
session.shutdown();
return Err(format!("connect failed: {e}"));
}
Err(e) => {
session.shutdown();
failure = format!("connect failed: {e}");
// A kept credential the account no longer honours — the
// password changed, the device was removed from the list —
// is a dead end, not a reason to stop: it is thrown away so
// the token behind it gets its turn, and so the next launch
// does not try it again.
if n < last {
log::warn!("{failure}, trying the next credential");
let _ = std::fs::remove_dir_all(
std::path::Path::new(&recipe.credentials_dir).join("reusable"),
);
continue;
}
return Err(failure);
}
};
// Spirc connects with credential storing switched on, so the cache
// now holds the blob the access point answered with. That is the
// one worth keeping, and the seed goes back into the cache after it
// is taken: login5 signs its stored-credential request with the
// session's client id, and the pair that is known to agree is the
// one this session actually logged in with.
if let Some(cache) = session.cache() {
if let Some(reusable) = cache.credentials() {
kept.save_credentials(&reusable);
}
cache.save_credentials(&credentials);
}
// Checked here rather than left to the library. The vendored
// librespot-core used to call exit(1) on a non-premium account,
// which took the app's process down and left Android restarting the
// service in a loop; it now only logs, so the refusal has to be
// made an error the caller can show.
if let Some(account_type) = session.get_user_attribute("type") {
if account_type != "premium" {
session.shutdown();
return Err(PREMIUM_REQUIRED.to_string());
}
}
return Ok::<_, String>((session, player, spirc, spirc_task));
}
Err(failure)
})?;
// The event loop runs for the life of the bundle: it is what answers the
// dealer, so without it the device appears once and then goes stale.
rt.spawn(async move {
spirc_task.await;
if GENERATION.load(Ordering::SeqCst) != generation {
log::info!("connect device {generation} stopped, already replaced");
return;
}
// The authoritative moment the Connect device is gone.
//
// Not a failed command, which is what this used to key off and why the
// repair never fired: when the task ends, its channel still accepts
// messages and nobody reads them. A load sent afterwards returns Ok,
// nothing loads, and the previous track plays on. Watching the task
// itself is the only signal that does not depend on being lucky enough
// to get an error back.
log::info!("connect device stopped");
SPIRC_LOST.store(true, Ordering::SeqCst);
});
// The pump reports listening history through the session, so it is told
// about this one before any of its events can arrive.
let _ = events_tx.send(Pump::Session(session.clone()));
spawn_event_forwarder(rt, player.clone(), events_tx.clone(), generation);
// A fresh bundle has a live Connect device again, whatever the last one
// ended up as.
SPIRC_LOST.store(false, Ordering::SeqCst);
Ok(Bundle {
session,
player,
spirc: Some(spirc),
})
}
/// True while the engine is running on downloads alone.
///
/// An atomic rather than a field of the bundle because it is read from the
/// Kotlin side on any thread, and because it survives the moment between two
/// bundles: a reconnection that fails leaves this on, which is what stops the
/// app from offering music it cannot fetch.
static OFFLINE: AtomicBool = AtomicBool::new(false);
/// Plays one track through the player, with no Connect device in the way.
///
/// The offline half of [`load_queue`]. Nothing about the queue changes: the app
/// still holds the list and still says what comes next, and this is only how
/// the track that was asked for starts.
fn local_load(uris: &[String], index: u32, play: bool, position_ms: u32) -> EngineResult<()> {
let uri = uris
.get(index as usize)
.ok_or_else(|| "nothing at that index".to_string())?;
let parsed = SpotifyUri::from_uri(uri).map_err(|e| format!("bad uri {uri}: {e}"))?;
log::info!("offline: loading {uri} at {position_ms}ms, play={play}");
with_bundle(|e| e.player.load(parsed, play, position_ms))
}
/// Set by the app while it has no network that carries anything.
///
/// What [`handshake_abandoned`] watches. Not [`OFFLINE_ONLY`]: that one is
/// also on while a session is being looked for again, and giving up on that
/// handshake because of it would mean never getting the session back.
static NETWORK_GONE: AtomicBool = AtomicBool::new(false);
/// Told by the app's network watch whether a network is carrying anything.
pub fn set_network_gone(gone: bool) {
if NETWORK_GONE.swap(gone, Ordering::SeqCst) != gone {
log::info!("network {}", if gone { "gone" } else { "back" });
}
}
/// How long a handshake may take before it is given up as going nowhere.
const HANDSHAKE_LIMIT: Duration = Duration::from_secs(15);
const HANDSHAKE_TIMED_OUT: &str = "the handshake timed out";
/// Ends when a handshake is not worth waiting for: the network went, or
/// [`HANDSHAKE_LIMIT`] passed.
async fn handshake_abandoned() -> &'static str {
let started = std::time::Instant::now();
loop {
if NETWORK_GONE.load(Ordering::SeqCst) {
return "the network is gone";
}
if started.elapsed() >= HANDSHAKE_LIMIT {
return HANDSHAKE_TIMED_OUT;
}
tokio::time::sleep(Duration::from_millis(250)).await;
}
}
/// Set by the app when only downloads may be played.
///
/// Distinct from [`OFFLINE`], which is about how the engine started: this is
/// what the listener asked for, or what a connection that has gone means for a
/// session that was built while it was there. Read on every load.
static OFFLINE_ONLY: AtomicBool = AtomicBool::new(false);
/// Says whether the player may reach for the network at all.
pub fn set_offline_only(only: bool) {
if OFFLINE_ONLY.swap(only, Ordering::SeqCst) != only {
log::info!("playing {}", if only { "from downloads only" } else { "from anywhere" });
}
}
/// Whether commands go to the player alone, leaving Connect out of them.
///
/// With no session, with a device that is gone, and also whenever the app is
/// offline, by the listener's switch or because the network stopped carrying
/// anything. That last one was missing: on mobile data with no coverage the
/// session's sockets stay open for minutes with nothing coming through them,
/// so the device did not look lost, the load went to Connect, and Connect
/// waited on Spotify for a downloaded track that needed nothing but its file.
fn player_only() -> bool {
OFFLINE.load(Ordering::SeqCst) || OFFLINE_ONLY.load(Ordering::SeqCst) || spirc_lost()
}
/// Whether the engine came up with no connection; see [`OFFLINE`].
pub fn is_offline() -> bool {
OFFLINE.load(Ordering::SeqCst)
}
/// A player and a session that never connected, for a phone with no network.
///
/// Everything a bundle normally gets from the handshake is missing here, and
/// that is the point: no Connect device to register, no account to publish
/// state to, no catalogue. What remains is the player, which is all a
/// downloaded track needs — [`load_downloaded_track`] reads it off the disk
/// without asking the session for anything.
fn build_offline_bundle(
rt: &tokio::runtime::Handle,
recipe: &Recipe,
mixer: &Arc<SoftMixer>,
events_tx: &std::sync::mpsc::Sender<Pump>,
) -> EngineResult<Bundle> {
let cache = Cache::new(
Some(std::path::Path::new(&recipe.credentials_dir)),
None,
Some(std::path::Path::new(&recipe.cache_dir)),
Some(AUDIO_CACHE_LIMIT),
)
.map_err(|e| format!("cache failed: {e}"))?;
let generation = GENERATION.fetch_add(1, Ordering::SeqCst) + 1;
// Inside the runtime, not beside it. `Session::new` registers tasks of its
// own the moment it is built, and off a runtime thread that is not an error
// but a panic — which, taken while `start` holds the engine lock, poisons it
// and leaves every later call answering "engine mutex poisoned". The online
// path never hit this because it does all of its building inside a
// `block_on`; this one has nothing to await, so it has to say so.
let _runtime = rt.enter();
let session = Session::new(recipe.session_config.clone(), Some(cache));
let player = Player::new(
recipe.player_config.clone(),
session.clone(),
mixer.get_soft_volume(),
move || Box::new(crate::sink::AndroidSink::new(AudioFormat::S16, generation)),
);
// No `Pump::Session`: history is reported over the session, and this one
// cannot carry anything. What was heard offline is kept by the app and
// sent when there is a connection again.
spawn_event_forwarder(rt, player.clone(), events_tx.clone(), generation);
SPIRC_LOST.store(false, Ordering::SeqCst);
Ok(Bundle {
session,
player,
spirc: None,
})
}
/// Which bundle is current. See the note where it is taken.
static GENERATION: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
/// The current bundle's number, for anything holding an older one.
pub(crate) fn live_generation() -> u64 {
GENERATION.load(Ordering::SeqCst)
}
/// Feeds one player's events to the engine-wide pump, and preloads ahead of it.
///
/// Ends on its own when the player is dropped, which is what a reconnection does
/// to it. The generation check is for the events already in flight at that
/// moment: a dying player emits a `Stopped`, and delivered late that would tell
/// Kotlin the new player had stopped before it started.
fn spawn_event_forwarder(
rt: &tokio::runtime::Handle,
player: Arc<Player>,
events_tx: std::sync::mpsc::Sender<Pump>,
generation: u64,
) {
let mut events = player.get_player_event_channel();
rt.spawn(async move {
// The track whose successor has already been fetched.
let mut preloaded: Option<String> = None;
while let Some(event) = events.recv().await {
if GENERATION.load(Ordering::SeqCst) != generation {
break;
}
match &event {
PlayerEvent::Playing { .. } => LOCAL_PLAYING.store(true, Ordering::SeqCst),
PlayerEvent::Paused { .. } | PlayerEvent::Stopped { .. } => {
LOCAL_PLAYING.store(false, Ordering::SeqCst)
}
_ => {}
}
// The track the app asked for is on its way: let it be heard.
// `Loading` rather than `Playing`, so nothing of its opening is lost
// while the two sides agree the silence is over.
if let PlayerEvent::Loading { track_id, .. } | PlayerEvent::Playing { track_id, .. } =
&event
{
track_started(&uri_string(track_id));
}
// Warm up the next track — but not the instant this one starts.
//
// Preloading on the first note meant a run of skips fired a burst
// of audio-key requests, Spotify refused them ("error audio key"),
// and librespot went on to decode the still-encrypted bytes:
// megabytes of noise through the decoder, thousands of log lines,
// and an app that looked frozen. A few seconds in, a track is one
// the listener is actually on, and a skipped-past track asks for
// nothing.
if let PlayerEvent::PositionChanged {
track_id,
position_ms,
..
} = &event
{
let uri = uri_string(track_id);
if *position_ms > PRELOAD_AFTER_MS && preloaded.as_deref() != Some(&uri) {
preload_after(&player, &uri);
preloaded = Some(uri);
}
}
if events_tx.send(Pump::Event(event)).is_err() {
break;
}
}
log::info!("event forwarder {generation} ended");
});
}
/// Changes what the player is built with, and builds it again.
///
/// The bitrate and the crossfade belong to the player's configuration, which is
/// fixed for the life of a player, so a new value means a new player. That used
/// to mean tearing the whole engine down from the Kotlin side, and that is the
/// call that aborted the process on a destroyed mutex: the runtime cannot be
/// dropped from a JNI thread while librespot's own threads are still inside it.
///
/// Replacing the bundle does the same job without touching the runtime or the
/// audio output. The queue is not restored here; the caller owns that.
pub fn set_quality(bitrate_kbps: i32, crossfade_ms: i32) -> EngineResult<()> {
{
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_mut().ok_or("engine not started")?;
engine.recipe.player_config.bitrate = match bitrate_kbps {
96 => Bitrate::Bitrate96,
160 => Bitrate::Bitrate160,
_ => Bitrate::Bitrate320,
};
engine.recipe.player_config.crossfade_duration_ms = crossfade_ms.max(0) as u32;
}
reconnect()
}
/// Changes the quality of what is asked for next, without rebuilding anything.
///
/// The bitrate is read while a track is being loaded, to put the formats it
/// exists in into order of preference, and nowhere else. Rebuilding the session
/// for it — which is what [`set_quality`] does, because the crossfade beside it
/// really is fixed for the life of a player — costs a second of silence, so
/// following a connection as it changes was never worth doing. This is the same
/// change at the cost of a message.
///
/// What is playing keeps the file it started with. The next track gets this.
pub fn set_bitrate(bitrate_kbps: i32) -> EngineResult<()> {
let bitrate = match bitrate_kbps {
96 => Bitrate::Bitrate96,
160 => Bitrate::Bitrate160,
_ => Bitrate::Bitrate320,
};
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_mut().ok_or("engine not started")?;
// Kept on the recipe as well, so a session rebuilt for any other reason
// starts where the listening left it rather than back at the setting.
engine.recipe.player_config.bitrate = bitrate;
if let Some(bundle) = engine.bundle.as_ref() {
bundle.player.set_bitrate(bitrate);
}
Ok(())
}
/// Changes whether trailing silence near the end of a track triggers early crossfade.
pub fn set_trim_silence(enabled: bool) -> EngineResult<()> {
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_mut().ok_or("engine not started")?;
engine.recipe.player_config.trim_silence = enabled;
if let Some(bundle) = engine.bundle.as_ref() {
bundle.player.set_trim_silence(enabled);
}
Ok(())
}
/// Lets the playing track run to its own end rather than crossfading into the
/// next; see `PlayerConfig::hold_end`. Kept in the recipe, so a rebuilt player
/// still holds.
pub fn set_hold_end(enabled: bool) -> EngineResult<()> {
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_mut().ok_or("engine not started")?;
engine.recipe.player_config.hold_end = enabled;
if let Some(bundle) = engine.bundle.as_ref() {
bundle.player.set_hold_end(enabled);
}
Ok(())
}
/// The transition into the next song of a mixed playlist, as JSON
/// `{from, outMs, fadeMs, to, inMs}`, or empty for none; see
/// librespot-playback's MixPlan. Set by the app for the pair that is next.
pub fn set_mix_plan(json: &str) -> EngineResult<()> {
let plan = if json.trim().is_empty() {
None
} else {
let value: serde_json::Value =
serde_json::from_str(json).map_err(|e| format!("bad mix plan: {e}"))?;
let text = |key: &str| value[key].as_str().map(str::to_string);
let number = |key: &str| value[key].as_u64().map(|n| n as u32);
Some(librespot_playback::player::MixPlan {
from: text("from").ok_or("mix plan without from")?,
out_ms: number("outMs").ok_or("mix plan without outMs")?,
fade_ms: number("fadeMs").ok_or("mix plan without fadeMs")?,
to: text("to").ok_or("mix plan without to")?,
in_ms: number("inMs").unwrap_or(0),
speed_in: value["speedIn"].as_f64().map(|v| v as f32).filter(|v| (0.5..2.0).contains(v)).unwrap_or(1.0),
})
};
with_bundle(|bundle| bundle.player.set_mix_plan(plan))
}
/// What the app's sleep timer is doing, for the state other devices read:
/// -1 none, 0 the end of the track, otherwise its end in epoch milliseconds.
/// Kept by the connect crate, so a rebuilt device still publishes it.
pub fn set_sleep_timer(value: i64) -> EngineResult<()> {
librespot_connect::sleep_timer::set(value);
// Put now if there is a device to put it; otherwise with the next state.
let _ = with_bundle(|bundle| bundle.spirc().map(|spirc| spirc.push_state()));
Ok(())
}
/// Which file on the phone each local entry of a playlist is, as the app
/// matched it: a JSON object of `spotify:local:` URIs to file paths. Replaces
/// what was set before; see librespot-playback's local_file.
pub fn set_local_files(json: &str) -> EngineResult<()> {
let files: std::collections::HashMap<String, String> =
serde_json::from_str(json).map_err(|e| format!("local files: {e}"))?;
let files = files
.into_iter()
.filter_map(|(uri, path)| Some((SpotifyUri::from_uri(&uri).ok()?, std::path::PathBuf::from(path))))
.collect();
librespot_playback::local_file::set_app_files(files);
Ok(())
}
/// How long a track the listener changes away from dissolves into the one they
/// asked for; see `PlayerConfig::skip_fade_ms`. Kept in the recipe, so a
/// rebuilt player still fades.
pub fn set_skip_fade(ms: u32) -> EngineResult<()> {
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_mut().ok_or("engine not started")?;
engine.recipe.player_config.skip_fade_ms = ms;
if let Some(bundle) = engine.bundle.as_ref() {
bundle.player.set_skip_fade(ms);
}
Ok(())
}
/// The language Spotify answers in, changed on a session that is already up.
///
/// The language rides on every request the session makes, and it is read once,
/// when the session is built. Someone who changes the app's language then goes
/// on being answered in the old one for as long as the process lives: names
/// that the catalogue holds in more than one script, an artist written in
/// Cyrillic and in Latin, keep arriving in whichever was in force at sign-in.
///
/// The recipe is always updated, so the next session has it whatever happens
/// here. Rebuilding now is the caller's choice, since it takes the player with
/// it and nobody changing a language expects the music to stop.
pub fn set_language(language: &str, rebuild: bool) -> EngineResult<()> {
{
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_mut().ok_or("engine not started")?;
if engine.recipe.session_config.language == language {
return Ok(());
}
engine.recipe.session_config.language = language.to_string();
}
if rebuild { reconnect() } else { Ok(()) }
}
/// Throws away a bundle and builds another one, leaving the runtime and the
/// audio output alone.
///
/// This is the whole answer to a network drop. librespot's Spirc builder is
/// handed out once per session, so a Connect device that has died cannot be
/// replaced on the session it belonged to; go-librespot reaches the same
/// conclusion and discards the session too. Everything that made rebuilding the
/// engine crash, dropping the tokio runtime from a JNI thread and detaching the
/// Android sink, lives in [`Engine`] and is not touched here.
///
/// The engine lock is held throughout, so commands arriving mid-reconnection
/// wait rather than seeing half a bundle.
pub fn reconnect() -> EngineResult<()> {
// Not under the engine lock while the network is being waited on.
//
// A new session is a TCP connection, a handshake and a login, which on a
// bad signal is seconds. The lock was held for all of it, so every other
// call into the engine waited the same seconds — including the main
// thread's, and a phone that has had no answer from the main thread for
// five seconds calls the app unresponsive. A run of skips that lost the
// Connect device did exactly that (#31). The bundle is taken out and what
// building needs is copied under the lock; the slow part runs without it,
// and anyone asking meanwhile hears "reconnecting" at once, which every
// caller already handles; the new bundle is put back under the lock.
if RECONNECTING.swap(true, Ordering::SeqCst) {
// One at a time: a second request would tear down the session the
// first is still building.
return Ok(());
}
let taken = (|| -> EngineResult<_> {
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_mut().ok_or("engine not started")?;
Ok((
engine.bundle.take(),
engine.rt.handle().clone(),
engine.recipe.clone(),
engine.mixer.clone(),
engine.events_tx.clone(),
))
})();
let (old, handle, recipe, mixer, events_tx) = match taken {
Ok(parts) => parts,
Err(e) => {
RECONNECTING.store(false, Ordering::SeqCst);
return Err(e);
}
};
let result = (|| {
// Dropped before the new one is built: two live sessions would be two
// devices in the account's list, and the old one would go on
// publishing state for a player nobody is listening to.
if let Some(old) = old {
log::info!("discarding the old session");
crate::remote::clear();
if let Some(spirc) = old.spirc.as_ref() {
let _ = spirc.disconnect(true);
let _ = spirc.shutdown();
}
old.player.stop();
old.session.shutdown();
// The device is emptied here rather than left to the player's own
// sink: by the time that one is told to stop, the audio it wrote is
// already in the AudioTrack, and that is what plays over the start
// of the next track.
crate::sink::silence();
}
// The same fallback the first start has, and for a sharper reason: the
// old bundle is already gone by this point, so a failure here used to
// leave the engine with no bundle at all — no session and no player,
// which takes the downloads away too. A retry that cannot reach the
// network puts the offline player back instead.
match build_bundle(&handle, &recipe, &mixer, &events_tx) {
Ok(bundle) => {
OFFLINE.store(false, Ordering::SeqCst);
log::info!("reconnected");
Ok(bundle)
}
Err(e) if e == PREMIUM_REQUIRED => Err(e),
Err(e) if crate::downloads::any() => {
log::warn!("{e}; staying offline with what is on the phone");
OFFLINE.store(true, Ordering::SeqCst);
build_offline_bundle(&handle, &recipe, &mixer, &events_tx)
}
Err(e) => Err(e),
}
})();
let installed = result.and_then(|bundle| {
let mut guard = ENGINE.lock().map_err(|_| "engine mutex poisoned")?;
let engine = guard.as_mut().ok_or("engine not started")?;
engine.bundle = Some(bundle);
Ok(())
});
RECONNECTING.store(false, Ordering::SeqCst);
installed
}
/// Forward player events to Kotlin. Runs for the life of the engine.
///
/// Deliberately a dedicated OS thread rather than a tokio task. The thread is
/// attached to the JVM once for its whole life, which avoids attaching and
/// detaching on every event and — more importantly — guarantees the listener's
/// `GlobalRef` is dropped while the thread is still attached. A tokio task
/// migrates between workers, so its `GlobalRef` could be released on a detached
/// thread, where JNI cannot free it ("Dropping a GlobalRef in a detached
/// thread").
/// Runs for the life of the engine, across any number of sessions: whichever
/// player is current has a forwarder feeding this one channel.
fn spawn_event_pump(
events: std::sync::mpsc::Receiver<Pump>,
listener: GlobalRef,
device_name: String,
state_dir: String,
) {
std::thread::Builder::new()
.name("squarecore-events".into())
.spawn(move || {
let vm = match JAVA_VM.get() {
Some(vm) => vm,
None => return,
};
// Permanent attach: detached only when this thread exits, by which
// point `listener` has already been dropped.
if let Err(e) = vm.attach_current_thread_permanently() {
log::error!("event pump could not attach to the JVM: {e}");
return;
}
log::info!("event pump started for device {device_name}");
// What the account's listening history is built from; see events.rs.
// Built on the first session, which arrives before any of its
// events, and rebound to each one after that.
let mut history: Option<History> = None;
while let Ok(message) = events.recv() {
let event = match message {
Pump::Event(event) => event,
// Carries nothing: the Kotlin side reads the state it wants
// when it hears there is a new one, rather than having every
// field of it pushed through this boundary.
Pump::Cluster => {
if let Err(e) = emit(&listener, "cluster", "", 0) {
log::warn!("dropping a cluster update: {e}");
}
continue;
}
Pump::App { kind, uri, value } => {
if let Err(e) = emit(&listener, &kind, &uri, value) {
log::warn!("dropping {kind}: {e}");
}
continue;
}
Pump::Session(session) => {
match history.as_mut() {
// The listen in progress survives: the same person
// is hearing the same track, and only the socket it
// will be reported over has changed.
Some(history) => history.rebind(session),
None => history = Some(History::new(session, state_dir.clone())),
}
continue;
}
};
if let Some(history) = history.as_mut() {
history.observe(&event);
}
let (kind, uri, position_ms) = match event {
PlayerEvent::Playing {
track_id,
position_ms,
..
} => ("playing", uri_string(&track_id), position_ms as i64),
PlayerEvent::Paused {
track_id,
position_ms,
..
} => ("paused", uri_string(&track_id), position_ms as i64),
PlayerEvent::PositionChanged {
track_id,
position_ms,
..
} => ("position", uri_string(&track_id), position_ms as i64),
PlayerEvent::Stopped { track_id, .. } => ("stopped", uri_string(&track_id), 0),
PlayerEvent::EndOfTrack { track_id, .. } => {
("end_of_track", uri_string(&track_id), 0)
}
PlayerEvent::Loading { track_id, .. } => ("loading", uri_string(&track_id), 0),
PlayerEvent::Unavailable { track_id, .. } => {
("unavailable", uri_string(&track_id), 0)
}
// Connect-protocol and volume events are not surfaced yet.
_ => continue,
};
if let Err(e) = emit(&listener, kind, &uri, position_ms) {
log::warn!("dropping event {kind}: {e}");
}
}
// Explicit so the ordering is obvious: the listener must go while
// this thread is still attached to the JVM.
drop(listener);
log::info!("event pump ended");
})
.expect("failed to spawn the event pump thread");
}
/// Turns the player's events into the three Spotify wants for a listen.
///
/// Kept beside the pump rather than inside `events` because only here is the
/// order of things known: a track is "finished" when the next one starts, when
/// the player stops, or when it runs off the end, and only one of those is an
/// event that says so.
struct History {
events: EventService,
/// Where the in-progress listen is kept, so a killed process loses nothing.
state_dir: String,
session_id: String,
/// The context every listen is attributed to, once one has been started.
context_uri: String,
current: Option<Playing>,
/// Durations seen so far, by track URI.
///
/// `TrackChanged` is the only event carrying one and it arrives *before*
/// the track starts, so there is nothing to attach it to yet. Held here
/// until the matching `Playing` shows up. Without this the transition
/// reported the played time as the track's length — a three-minute song
/// skipped at forty seconds went to Spotify as a forty-second song played
/// to the end, and nothing about that was going to be believed.
durations: std::collections::HashMap<String, u32>,
}
struct Playing {
uri: String,
hex: String,
playback_id: String,
start_ms: u32,
position_ms: u32,
duration_ms: u32,
started_at: u128,
reason_start: &'static str,
}
impl History {
fn new(session: Session, state_dir: String) -> Self {
let session_id = session.session_id();
let events = EventService::new(session);
// Whatever the last run was in the middle of when it went away.
events::pending::flush(&state_dir, &events);
History {
events,
state_dir,
session_id: if session_id.is_empty() {
events::random_id()
} else {
session_id
},
context_uri: String::new(),
current: None,
durations: std::collections::HashMap::new(),
}
}
/// Points the reporting at a new session, keeping the listen in progress.
///
/// The session id changes because Spotify's is per connection, and a report
/// carrying the dead one's would be filed against a session the account no
/// longer has. Everything else about the listen is unchanged, which is the
/// point: the network went away, the music did not.
fn rebind(&mut self, session: Session) {
let session_id = session.session_id();
self.events = EventService::new(session);
self.session_id = if session_id.is_empty() {
events::random_id()
} else {
session_id
};
if !self.context_uri.is_empty() {
self.events
.new_session(&self.session_id, &self.context_uri, 1);
}
}
fn observe(&mut self, event: &PlayerEvent) {
match event {
PlayerEvent::TrackChanged { audio_item } => {
// Kept for whenever this track starts; see `durations`. The map
// is bounded by the queue, and a queue is not unbounded.
if audio_item.duration_ms > 0 {
self.durations
.insert(audio_item.uri.clone(), audio_item.duration_ms);
}
if let Some(playing) = self.current.as_mut() {
if playing.uri == audio_item.uri {
playing.duration_ms = audio_item.duration_ms;
}
}
}
PlayerEvent::Playing {
track_id,
position_ms,
..
} => self.start(uri_string(track_id), *position_ms),
PlayerEvent::PositionChanged { position_ms, .. }
| PlayerEvent::Seeked { position_ms, .. } => {
if let Some(playing) = self.current.as_mut() {
playing.position_ms = *position_ms;
}
// Once a second, which is what this event arrives at.
self.remember();
}
// A pause ends the stretch that was being listened to.
//
// Reported straight away rather than held until the track finishes,
// because most of the time it never does: the track is paused, the
// app is left, and the process goes away with the listen still
// sitting in memory. That is why only one of a session's tracks
// ever reached the account's history.
//
// Resuming opens a *new* playback at the position it resumes from,
// so what is reported is always a stretch that really was heard —
// never one invented to make a pause look like a full play.
PlayerEvent::Paused { position_ms, .. } => {
if let Some(playing) = self.current.as_mut() {
playing.position_ms = *position_ms;
}
// Not when the pause is the track running out: the end of a
// track is reported as one, and reporting it here first would
// take the completed listen away and leave a stopped one in its
// place.
let at_end = self
.current
.as_ref()
.map(|playing| {
playing.duration_ms > 0
&& playing.position_ms + END_MARGIN_MS >= playing.duration_ms
})
.unwrap_or(false);
if !at_end {
self.finish(EndReason::EndPlay);
}
}
// Ran to the end: the one that counts as a full listen.
PlayerEvent::EndOfTrack { .. } => self.finish(EndReason::TrackDone),
PlayerEvent::Stopped { .. } => self.finish(EndReason::EndPlay),
_ => {}
}
}
fn start(&mut self, uri: String, position_ms: u32) {
if let Some(playing) = self.current.as_ref() {
// Un-pausing and seeking both arrive as `Playing` on a track that is
// already open, and neither is a new listen.
if playing.uri == uri {
if let Some(playing) = self.current.as_mut() {
playing.position_ms = position_ms;
}
return;
}
// A different track without an end event: something skipped.
self.finish(EndReason::Forward);
}
let hex = hex_id(&uri);
if hex.is_empty() {
return;
}
// The playlist or album this queue came from, or the track itself when
// it came from neither — which is what the official client sends for a
// track played on its own.
let context = match current_context() {
context if context.is_empty() => uri.clone(),
context => context,
};
if self.context_uri != context {
self.context_uri = context;
// A context is a session: leaving one and starting another is a new
// session id, not a continuation of the last.
self.session_id = events::random_id();
self.events
.new_session(&self.session_id, &self.context_uri, 1);
}
let playback_id = events::random_id();
self.events.new_playback(&playback_id, &self.session_id);
let duration_ms = self.durations.get(&uri).copied().unwrap_or(0);
self.current = Some(Playing {
uri,
hex,
playback_id,
start_ms: position_ms,
position_ms,
duration_ms,
started_at: events::now_ms(),
reason_start: "playbtn",
});
self.remember();
}
/// Keeps the in-progress listen on disk; see `events::pending`.
fn remember(&self) {
let Some(playing) = self.current.as_ref() else {
return;
};
events::pending::write(
&self.state_dir,
&events::pending::Pending {
track_hex: playing.hex.clone(),
playback_id: playing.playback_id.clone(),
context_uri: self.context_uri.clone(),
start_ms: playing.start_ms,
position_ms: playing.position_ms,
duration_ms: playing.duration_ms,
started_at: playing.started_at,
},
);
}
fn finish(&mut self, reason: EndReason) {
let Some(playing) = self.current.take() else {
return;
};
// A stretch too short to have been listened to at all — a pause landing
// in the same instant as the start, a track that failed to open.
if playing.position_ms.saturating_sub(playing.start_ms) < MIN_LISTEN_MS
&& !matches!(reason, EndReason::TrackDone)
{
return;
}
// Running off the end means the whole track was heard, whatever the
// last position report happened to say.
let end_ms = match reason {
EndReason::TrackDone if playing.duration_ms > 0 => playing.duration_ms,
_ => playing.position_ms.max(playing.start_ms),
};
let duration_ms = if playing.duration_ms > 0 {
playing.duration_ms
} else {
end_ms
};
// Sent, so it must not be sent again on the next start.
events::pending::clear(&self.state_dir);
self.events.track_transition(&Listen {
track_hex: &playing.hex,
playback_id: &playing.playback_id,
context_uri: &self.context_uri,
start_ms: playing.start_ms,
end_ms,
duration_ms,
reason_start: playing.reason_start,
reason_end: reason,
started_at: playing.started_at,
});
}
}
/// How close to the end counts as the track finishing rather than being paused.
const END_MARGIN_MS: u32 = 2_000;
/// Below this, a stretch is a mis-tap rather than a listen.
const MIN_LISTEN_MS: u32 = 1_000;
/// A track's gid in hex, which is what the events carry — not the base62 id.
fn hex_id(uri: &str) -> String {
match SpotifyUri::from_uri(uri) {
Ok(SpotifyUri::Track { id }) => id.to_base16().unwrap_or_default(),
_ => String::new(),
}
}
fn uri_string(uri: &SpotifyUri) -> String {
uri.to_uri().unwrap_or_default()
}
/// Says something to the Kotlin listener from outside the player.
///
/// Best effort on purpose. A progress tick that cannot be delivered — because
/// the engine is between two sessions, or because the pump has already been
/// torn down — is a ring that does not move for a moment. That is not a reason
/// to fail the download it belongs to.
pub fn emit_app(kind: &str, uri: &str, value: i64) {
let Ok(sender) = with_engine(|engine| engine.events_tx.clone()) else {
return;
};
let _ = sender.send(Pump::App {
kind: kind.to_string(),
uri: uri.to_string(),
value,
});
}
/// Invoke `NativeEvents.onEvent` from a tokio worker thread.
fn emit(listener: &GlobalRef, kind: &str, uri: &str, position_ms: i64) -> Result<(), String> {
let vm = JAVA_VM.get().ok_or("JNI_OnLoad did not run")?;
// Tokio worker threads are not known to the VM, so they must attach. The
// guard detaches on drop, which keeps the thread's local ref table bounded.
let mut env = vm
.attach_current_thread()
.map_err(|e| format!("attach failed: {e}"))?;
let j_kind = env.new_string(kind).map_err(|e| e.to_string())?;
let j_uri = env.new_string(uri).map_err(|e| e.to_string())?;
env.call_method(
listener,
"onEvent",
"(Ljava/lang/String;Ljava/lang/String;J)V",
&[
JValue::Object(&j_kind),
JValue::Object(&j_uri),
JValue::Long(position_ms),
],
)
.map_err(|e| e.to_string())?;
// A Kotlin listener that throws would otherwise leave the exception pending
// and poison every later JNI call on this thread.
if env.exception_check().unwrap_or(false) {
let _ = env.exception_describe();
let _ = env.exception_clear();
return Err("listener threw".into());
}
Ok(())
}
/// Hands a whole queue to the Connect device.
///
/// A list rather than one track at a time, which is what this did before. Spirc
/// publishes the queue as well as the current item, so loading track by track
/// would show the account a device that never has anything coming up — and it
/// is Spirc, not the caller, that advances at the end of a track.
///
/// `index` selects the starting track; anything out of range starts at the
/// beginning, which is librespot's own behaviour rather than an error.
/// The playlist or album the current queue came from, for the listening events.
///
/// A global rather than a field on the engine: the event pump reads it from its
/// own thread, and it changes whenever a queue is loaded — which is a different
/// lock from the one that owns playback.
static CONTEXT_URI: Mutex<String> = Mutex::new(String::new());
/// The queue as the app handed it over, in play order.
///
/// Kept so the engine can fetch the next track before it is asked for; see
/// [`preload_after`].
static QUEUE: Mutex<Vec<String>> = Mutex::new(Vec::new());
/// How much of the phone the cached audio may take: 512 MB.
const AUDIO_CACHE_LIMIT: u64 = 512 * 1024 * 1024;
/// Deletes the temporary files left behind by downloads that never finished.
///
/// librespot writes each download to a `.tmp…` file beside the cache and
/// renames it when it completes; a skip mid-download leaves the temporary file
/// where it is, several megabytes at a time, for ever.
fn sweep_stale_downloads(dir: &str) {
let Ok(entries) = std::fs::read_dir(dir) else {
return;
};
let mut removed = 0;
for entry in entries.flatten() {
let name = entry.file_name();
let Some(name) = name.to_str() else { continue };
if !name.starts_with(".tmp") {
continue;
}
// Only the ones nothing is writing any more. An hour is far longer than
// any download and short enough that they do not pile up.
let stale = entry
.metadata()
.and_then(|meta| meta.modified())
.map(|modified| {
modified
.elapsed()
.map(|age| age.as_secs() > 3600)
.unwrap_or(false)
})
.unwrap_or(false);
if stale && std::fs::remove_file(entry.path()).is_ok() {
removed += 1;
}
}
if removed > 0 {
log::info!("swept {removed} unfinished downloads");
}
}
/// What `start` returns for an account Spotify does not stream to this client.
///
/// Matched by the Kotlin side, so it stays a stable string.
pub const PREMIUM_REQUIRED: &str = "premium account required";
/// How far into a track its successor is fetched, in milliseconds.
const PRELOAD_AFTER_MS: u32 = 5_000;
/// Warms up the track after `uri`, so a skip does not start from nothing.
///
/// librespot preloads on its own, but only in the last thirty seconds of a
/// track — that is for gapless playback, and it does nothing for someone
/// skipping. Between the tap and the first sound there was most of a second of
/// audio key and first chunk; fetched now, while the current track plays, the
/// skip has them already.
fn preload_after(player: &Player, uri: &str) {
let next = {
let Ok(queue) = QUEUE.lock() else { return };
let Some(position) = queue.iter().position(|item| item == uri) else {
return;
};
queue.get(position + 1).cloned()
};
let Some(next) = next else { return };
if let Ok(parsed) = SpotifyUri::from_uri(&next) {
player.preload(parsed);
}
}
pub fn current_context() -> String {
CONTEXT_URI.lock().map(|c| c.clone()).unwrap_or_default()
}
pub fn load_queue(
uris: Vec<String>,
index: u32,
start_playing: bool,
position_ms: u32,
context_uri: String,
play_as_context: bool,
) -> EngineResult<()> {
if uris.is_empty() {
return Err("empty queue".into());
}
for uri in &uris {
let parsed = SpotifyUri::from_uri(uri).map_err(|e| format!("bad uri {uri}: {e}"))?;
if !parsed.is_playable() {
return Err(format!("{uri} is not a playable item"));
}
}
// Read before the request takes the list: what the load asks for is also
// what the output waits for after a reconnection.
let wanted = uris.get(index as usize).cloned().unwrap_or_default();
let context = context_uri.clone();
if let Ok(mut stored) = CONTEXT_URI.lock() {
*stored = context_uri;
}
if let Ok(mut stored) = QUEUE.lock() {
*stored = uris.clone();
}
// Offline there is no Connect device to hand a queue to, so there is no
// queue to hand over: the player is given the one track, and the app comes
// back for the next one when this ends. Everything above still runs, so
// what the app believes about the queue is unchanged either way — the only
// difference is who advances it.
//
// The same road is taken when there is a device but it cannot be reached,
// which is what a connection dropping mid-listen looks like. A load handed
// to Connect is resolved on Spotify's side before the player is ever asked,
// so with the network gone it died there — and a downloaded track, which
// needs nothing but the file, never got the chance to play. The player's
// own loader reads the disk first; it only has to be reached.
if with_bundle(|e| e.spirc.is_none())? || player_only() {
log::info!("no usable connect device; loading through the player");
return local_load(&uris, index, start_playing, position_ms);
}
let options = LoadRequestOptions {
start_playing,
seek_to: position_ms,
playing_track: Some(PlayingTrack::Index(index)),
..LoadRequestOptions::default()
};
// Handed over as the context itself when the queue really is one.
//
// A list of URIs is not a place: played that way, the account sees a queue
// of loose tracks, other devices see no playlist, and the listen has
// nowhere to be filed. The caller says when the two agree — the rows on
// screen being the playlist in its own order — because only it can know.
let request = if play_as_context {
let start = uris
.get(index as usize)
.cloned()
.map(PlayingTrack::Uri)
.or(Some(PlayingTrack::Index(index)));
LoadRequest::from_context_uri(
context,
LoadRequestOptions {
playing_track: start,
..options
},
)
} else if !context.is_empty() {
// The tracks in the order on screen, published under the playlist they
// came from.
//
// Shuffling a playlist, or adding a track to it, makes a queue that is
// the playlist without being the playlist's order, and upstream has no
// shape for that: either the context, whose order is Spotify's, or a
// list of tracks, published as `spotify:web-api`. The second is what
// this app sent nearly always, and it is a context no other device can
// resolve: handing playback to one gave it a queue that would not play,
// and taking it back arrived with a track that could not be found. See
// native/vendor/README.md.
LoadRequest::from_tracks_in(context, uris, options)
} else {
LoadRequest::from_tracks(uris, options)
};
// A queue that nobody asked to hear does not go out while the account is
// playing somewhere else.
//
// A load activates this device, which is right when the listener has just
// tapped a track and wrong every other time. Opening the app restores the
// last queue, paused, and that restore was taking the session away from
// whatever was playing in the other room: Square went silent-but-active and
// the music stopped mid-track.
//
// Refused rather than quietly dropped, so the caller keeps its queue marked
// as one the engine has never seen and hands it over again the moment the
// listener really does ask for it.
if !start_playing && elsewhere_active() {
return Err("another device has playback".into());
}
// Nothing but this track may be heard until it starts; see PLAYBACK_ARMED.
//
// Except while a song playing here is dissolved into it, as for a skip
// (see `leaving`). The tail being faded is the very track this keeps from
// being heard: picking a song from another list cut the dissolve off, and
// the sink, throwing away the tail a packet at a time and waiting out each
// one, stuttered on the way.
let dissolving = start_playing && dissolves() && !current_uri().is_empty();
if !wanted.is_empty() && !dissolving {
shut(Gate::Expect(wanted.clone()));
}
with_bundle(|e| {
// Without this the device is registered but idle, and a load is
// ignored: playback belongs to whichever device the account has
// active, and taking that over is an explicit step.
e.spirc()?.activate()?;
// Shuffle off before the list goes in, every time.
//
// The order handed over here is the order the app is showing, shuffled
// or not: the app draws its own random order and the engine is only
// asked to play the result. But the Connect state carries a shuffle
// flag of the account's, which another client may have set and which
// survives in the state this device restores, and when a context
// resolves with that flag on librespot shuffles it again for itself.
// The engine then played its own order while the screen followed
// another, so a skip stepped somewhere the listener could not see and
// whole tracks appeared to be missed.
e.spirc()?.shuffle(false)?;
e.spirc()?.load(request)
})?
.inspect_err(|_| {
// A load has no way around Spirc: choosing what to decode next is the
// Connect device's job and nothing else can do it. A refused one is a
// second, weaker sign of the same loss the task watcher above catches
// properly, kept because it costs nothing.
SPIRC_LOST.store(true, Ordering::SeqCst);
})
.map_err(|e| format!("load failed: {e}"))
}
/// Runs a transport command through Spirc, and through the player if Spirc is gone.
///
/// Spirc and the player are separate things: the first is the Connect device,
/// the second is what decodes audio and writes it to the sink. Every transport
/// command goes through Spirc so the account sees it, but a Spirc command is a
/// message into a task, and when that task has died the channel is closed and
/// the command comes back an error while the player carries on making sound.
///
/// That is the "pause does nothing and only killing the app stops the music"
/// failure. It cannot be fixed by reporting the error, because the audio is
/// still playing either way: something has to reach the thing making it. So the
/// player is told directly, and the account is left with a stale idea of what
/// this device is doing until the engine is rebuilt. Silence under the user's
/// finger is worth more than a tidy Connect state.
fn transport(
what: &str,
via_spirc: impl FnOnce(&Bundle) -> Result<(), librespot_core::Error>,
via_player: impl FnOnce(&Bundle),
) -> EngineResult<()> {
// LOCAL PATCH: every command this side sends, so a skip nobody asked for
// can be told from one this app asked for. See spirc.rs, which says the
// same about the commands that arrive from the account.
log::info!("this device asks to {what}");
// Asked before trying, not after failing.
//
// A command sent to a Spirc task that has already ended does not come back
// an error: the channel still accepts the message and nobody ever reads it.
// Waiting for a failure meant the fallback almost never ran, which is why
// pause went on doing nothing with the network gone.
// Another device has the account's playback: this one must not reach for it.
//
// Every command here activates the device first, which is right when the
// listener is asking this phone to play and catastrophic when they are not.
// A pause sent while a speaker was playing took the session away from the
// speaker and then stopped it, which is what closing the app did to the
// music in the other room, and what opening it did on the way in.
//
// The player is still told, because the point of a pause is silence here.
// Spirc is not, so nothing is taken from anyone.
if elsewhere_active() {
return with_bundle(|engine| {
log::info!("{what}: another device has playback, keeping this one to itself");
via_player(engine);
});
}
if player_only() {
return with_bundle(|engine| {
log::warn!("{what}: no connect device, going straight to the player");
via_player(engine);
});
}
with_bundle(|engine| match {
// Taken over first, the same way a load does.
//
// A device that is registered but not the account's active one drops
// every transport command on the floor, and says so at warning level:
// "SpircCommand::Play will be ignored while Not Active". Nothing came
// back as an error, so the app saw a pause that had been accepted and a
// player that went on regardless. The load path has taken this step
// since it was written; the transport path never did.
let _ = engine.spirc().map(|spirc| {
if !spirc.is_active() {
let _ = spirc.activate();
}
});
via_spirc(engine)
} {
Ok(()) => Ok(()),
Err(e) => {
log::warn!("{what}: spirc refused it ({e}), going straight to the player");
SPIRC_LOST.store(true, Ordering::SeqCst);
via_player(engine);
Ok(())
}
})?
}
/// Whether this device is decoding audio right now.
///
/// The plainest fact available, and the one that settles the argument when the
/// other two sources disagree; see [`elsewhere_active`].
static LOCAL_PLAYING: AtomicBool = AtomicBool::new(false);
/// Whether the account's playback belongs to another device.
///
/// Asked of librespot rather than of the cluster, because the two disagree for
/// as long as it takes the previous device to let go. After playback is
/// transferred *to* this phone, the account can go on naming the device it came
/// from: trusting that meant refusing to play on a device that was already
/// playing, and every guard in here reading the wrong answer at once.
///
/// The cluster is still the fallback, for the moment before there is a device
/// at all.
/// Initial Connect state before the dealer sends its first change.
pub fn connect_cluster() -> Option<librespot_protocol::connect::Cluster> {
let guard = ENGINE.try_lock().ok()?;
guard.as_ref()?.bundle.as_ref()?.spirc().ok()?.cluster()
}
pub fn elsewhere_active() -> bool {
// Sound coming out of this phone settles it.
//
// The other two answers can both be wrong at once, and were: after
// playback was taken back here, the account still named the device it came
// from and the Connect state had not caught up either, so a pause pressed
// on a phone that was playing went out to a laptop that was not. Whatever
// the bookkeeping says, the device making the sound is the device the
// buttons belong to.
if LOCAL_PLAYING.load(Ordering::SeqCst) {
return false;
}
// Without waiting for the engine. This is asked on the main thread for
// every player event, and the engine lock can be held for a login's worth
// of seconds while it starts: a busy lock means the device is being built,
// and a device being built is not somewhere else playing. See #31.
let Ok(guard) = ENGINE.try_lock() else {
return false;
};
let Some(bundle) = guard.as_ref().and_then(|engine| engine.bundle.as_ref()) else {
return false;
};
if bundle.spirc().map(|spirc| spirc.is_active()).unwrap_or(false) {
return false;
}
let own = bundle.session.device_id().to_string();
drop(guard);
crate::remote::elsewhere_active_for(&own)
}
/// What the Connect state says this device is playing, as JSON.
///
/// `{"contextUri", "trackUri", "index", "tracks"}`, any of which can be empty.
///
/// The track list is the queue as the account handed it over, which is the
/// only copy of it for a context this app cannot read for itself.
///
/// Asked when another client has driven this device somewhere the app did not
/// send it. The account does not push this device a cluster update about its
/// own playing, so there is nothing to read from the outside: this comes from
/// the Connect state itself, which is the same thing the other devices are
/// shown.
pub fn playing_here() -> EngineResult<String> {
let playing = with_bundle(|bundle| {
bundle.spirc().map(|spirc| spirc.playing()).unwrap_or_default()
})?;
let escape = |value: &str| serde_json::to_string(value).unwrap_or_else(|_| "\"\"".into());
let tracks: Vec<String> = playing.tracks.iter().map(|uri| escape(uri)).collect();
// `videoId` rides along rather than getting a call of its own: it changes
// exactly when the track does, and this is already the answer to "what is
// this device playing". Empty for everything without a music video, which
// is almost everything.
Ok(format!(
"{{\"contextUri\":{},\"trackUri\":{},\"index\":{},\"videoId\":{},\"tracks\":[{}]}}",
escape(&playing.context_uri),
escape(&playing.track_uri),
playing.index,
escape(&playing.video_id),
tracks.join(","),
))
}
pub fn play() -> EngineResult<()> {
// Nothing happens here while the music is somewhere else. A play that
// arrives then is Android's, not the listener's: focus coming back, a
// service waking. The listener's own play is sent to the device that is
// actually playing, by the app, and never reaches this.
if elsewhere_active() {
log::info!("play: another device has playback, ignoring");
return Ok(());
}
// The music starts here, for the same reason it stops here in [`pause`].
//
// After a pause the Connect task is still telling Spotify about it, and
// while that request is out it does not read its channel: a play pressed a
// second after a pause waited behind it, about a third of a second on a
// good line and ten on one that was answering 429. Pause already skipped
// that queue, so the button stopped the music at once and then took its
// time to bring it back. The account hears about it whenever it can, and
// the player answers that late play with where the track really is; see
// `handle_play` in player.rs.
let _ = with_bundle(|engine| engine.player.play());
transport("play", |e| e.spirc()?.play(), |e| e.player.play())
}
pub fn pause() -> EngineResult<()> {
// The sound stops here, before anything is asked of the network.
//
// A pause is a message to the Connect task, and that task also talks to
// Spotify: while it is waiting on a request it does not read its own
// channel, so on a weak signal the music went on playing for seconds after
// the button. The player is the thing making the noise and it is right
// here, so it is told first and the account is told whenever it can be.
// Pausing a player that is already paused, or one that was never playing
// because the music is on another device, costs nothing.
let _ = with_bundle(|engine| engine.player.pause());
transport("pause", |e| e.spirc()?.pause(), |e| e.player.pause())
}
pub fn stop() -> EngineResult<()> {
// Disconnecting rather than stopping the player: it tells the account this
// device has given up playback, which is what makes it disappear from the
// device list instead of lingering as a paused phantom. The fallback does
// stop the player, because a stop that leaves audio running is not a stop.
transport("stop", |e| e.spirc()?.disconnect(true), |e| e.player.stop())
}
pub fn seek(position_ms: u32) -> EngineResult<()> {
// The player itself when there is no device to ask.
//
// Every other command already had this fallback; seeking did not, so
// dragging or tapping the progress bar offline reached a Connect device
// that is not there and did nothing at all. What plays is the player's, and
// moving within a track is something it can do on its own.
if player_only() {
return with_bundle(|e| e.player.seek(position_ms));
}
with_bundle(|e| e.spirc()?.set_position_ms(position_ms))?.map_err(|e| format!("seek failed: {e}"))
}
// Skipping is a Spirc command like the rest, and it was the one left out of
// [`transport`]: with the device gone it was accepted, discarded, and the track
// that was already playing carried on. Stopping is the fallback because there
// is nothing better available here. The player owns no queue, so it cannot pick
// the next track itself, and going on with the current one is the one answer
// that is certainly wrong: the listener asked for something else.
pub fn next() -> EngineResult<()> {
leaving();
transport("next", |e| e.spirc()?.next(), |e| e.player.stop())
}
pub fn previous() -> EngineResult<()> {
leaving();
// The track before, never a restart of this one: the app sends this only
// once it has decided to move back, by the position on its own screen,
// and a restart here left it one track behind the speaker. A restart is
// sent as a seek to zero instead.
transport("previous", |e| e.spirc()?.prev_track(), |e| e.player.stop())
}
/// Shuts the output until the track being played is a different one.
///
/// A skip is a message to the Connect device and the music changes about a
/// second later; the old track is decoded for the whole of that second, and the
/// fade the app wraps a skip in is long over by then. That was the previous song
/// coming back at full volume before the new one cut in.
fn leaving() {
// Not while a skip is dissolved: the gate is there to keep the track being
// left from being heard, and that is exactly what a dissolve is made of.
// The player fades it out itself, and what is heard under the new track is
// a second of the old one going, not the wrong song carrying on.
if dissolves() {
return;
}
let current = current_uri();
if !current.is_empty() {
shut(Gate::Leave(current));
}
}
/// Whether a change of track the listener asked for is dissolved rather than
/// cut; see `PlayerConfig::skip_fade_ms`.
fn dissolves() -> bool {
ENGINE
.lock()
.ok()
.and_then(|guard| guard.as_ref().map(|e| e.recipe.player_config.skip_fade_ms > 0))
.unwrap_or(false)
}
/// Republishes what is playing as the context it came from.
///
/// Only useful in one moment, just before playback is handed to another device.
///
/// A queue that is not a playlist in its own order goes to the engine as a bare
/// list of URIs, and librespot has to invent a context for it: `spotify:web-api`,
/// which is what the logs call `type: Default`. That is fine here, where the
/// order on screen is the order that plays, and useless to anyone else: a device
/// receiving the handover gets a context it cannot resolve, so its bar moves and
/// nothing comes out.
///
/// So the same music is loaded once more as the real playlist, at the same track
/// and the same second, and only then is the handover sent. The cost is that a
/// shuffled queue continues over there in Spotify's order rather than in the one
/// that was on screen: the alternative is handing over something that does not
/// play at all.
pub fn publish_context(position_ms: u32) -> EngineResult<bool> {
let current = current_uri();
if current.is_empty() {
return Ok(false);
}
// Nothing to do in the ordinary case, which is what makes a handover quick.
//
// Loads now carry the playlist they came from even when the order is this
// app's own, so the state is already something another device can resolve.
// Reloading anyway cost a restart of the audio and a wait, on every single
// change of device, to republish what was published already.
if !current_context().is_empty() {
return Ok(false);
}
// The track itself, since there is no playlist behind this queue.
//
// A track is a context: it is what the official client publishes when a
// single song is played out of a search, and unlike `spotify:web-api` it is
// something the other end can resolve. Without this a queue with no
// playlist behind it, which is most of what a search produces, handed over
// as a context that answers 400 and left the receiving device with nothing
// to play.
let context = current.clone();
log::info!("republishing {current} as {context} before handing over");
let request = LoadRequest::from_context_uri(
context,
LoadRequestOptions {
start_playing: true,
seek_to: position_ms,
playing_track: Some(PlayingTrack::Uri(current)),
..LoadRequestOptions::default()
},
);
with_bundle(|e| {
e.spirc()?.activate()?;
e.spirc()?.load(request)
})?
.map_err(|e| format!("could not republish the context: {e}"))?;
Ok(true)
}
/// Starts playing here, at the track and second another device was on.
///
/// The whole handover in one call, so it can happen before anything is
/// resolved. The app used to fetch the entire context first, which for a long
/// playlist is a second or two of nothing happening at all, with no way for the
/// listener to tell the request from a request that was lost. The queue on
/// screen catches up afterwards, from the state this load publishes.
pub fn resume_here(context_uri: &str, track_uri: &str, position_ms: u32) -> EngineResult<()> {
if track_uri.is_empty() {
return Err("nothing to resume".into());
}
let context = if context_uri.is_empty() {
track_uri.to_string()
} else {
context_uri.to_string()
};
log::info!("resuming {track_uri} here, from {context} at {position_ms}ms");
// Anything the previous device was decoding stays out until this track
// starts; see PLAYBACK_ARMED.
shut(Gate::Expect(track_uri.to_string()));
let request = LoadRequest::from_context_uri(
context,
LoadRequestOptions {
start_playing: true,
seek_to: position_ms,
playing_track: Some(PlayingTrack::Uri(track_uri.to_string())),
..LoadRequestOptions::default()
},
);
with_bundle(|e| {
e.spirc()?.activate()?;
e.spirc()?.load(request)
})?
.map_err(|e| format!("could not resume here: {e}"))
}
/// Takes the account's playback for this device.
///
/// The local half of the device picker. Choosing another device is a request to
/// the server, addressed from here to there; choosing this one cannot be, since
/// a command sent from a device to itself goes out to the access point and
/// comes back refused. Activating is the same thing done directly.
pub fn take_over() -> EngineResult<()> {
with_bundle(|e| e.spirc()?.activate())?.map_err(|e| format!("could not take over: {e}"))
}
/// Hands the device a new running order without touching what is playing.
///
/// The app owns the order — it draws its own shuffle — and when the listener
/// turns that on or off the list changes under a track that is still playing.
/// Reloading the queue would say the same thing at the cost of a gap in the
/// song, for a change that is only ever about what comes after it.
pub fn set_queue_order(uris: Vec<String>, index: u32) -> EngineResult<()> {
if uris.is_empty() {
return Err("empty queue".into());
}
let at = (index as usize).min(uris.len() - 1);
let prev = uris[..at].to_vec();
let next = uris[at + 1..].to_vec();
if let Ok(mut stored) = QUEUE.lock() {
*stored = uris;
}
with_bundle(|e| e.spirc()?.set_queue_tracks(prev, next))?
.map_err(|e| format!("queue order failed: {e}"))
}
pub fn set_shuffle(shuffle: bool) -> EngineResult<()> {
with_bundle(|e| e.spirc()?.shuffle(shuffle))?.map_err(|e| format!("shuffle failed: {e}"))
}
/// `repeat_track` takes precedence: the two are separate flags in the protocol.
pub fn set_repeat(repeat_context: bool, repeat_track: bool) -> EngineResult<()> {
with_bundle(|e| {
e.spirc()?.repeat_track(repeat_track)?;
e.spirc()?.repeat(repeat_context)
})?
.map_err(|e| format!("repeat failed: {e}"))
}
/// `volume` is the raw 0..=65535 range librespot uses.
pub fn set_volume(volume: u16) -> EngineResult<()> {
with_engine(|e| e.mixer.set_volume(volume))
}
pub fn volume() -> EngineResult<u16> {
with_engine(|e| e.mixer.volume())
}
/// Whether the Connect device is gone and the engine wants rebuilding.
///
/// Two signals, because one of them is late. The flag is authoritative but only
/// rises when the Spirc task has actually finished, and that took ten seconds
/// after a dropped network in the case this was written for: for those ten
/// seconds the device is already unreachable, every command is accepted and
/// discarded, and the listener is pressing skip at a player that will not move.
///
/// An invalid session is the earlier sign of the same thing. It is checked at
/// the moment a command is issued rather than watched, so a connection that
/// drops and comes back on its own between two commands costs nothing: the
/// question is only ever asked when somebody is waiting for an answer.
/// Neither of these takes the engine lock. A reconnection holds it for the whole
/// of a handshake, and both are asked from the playback looper: waiting there
/// would be seconds of a frozen app for a question that has an answer already.
pub fn spirc_lost() -> bool {
// Offline there is no device to lose, and saying one was lost would send
// the Kotlin side off rebuilding a session every thirty seconds against a
// network that is not there. The app is told it is offline instead, which
// is a different question with a different answer; see [`is_offline`].
if OFFLINE.load(Ordering::SeqCst) {
return false;
}
if RECONNECTING.load(Ordering::SeqCst) {
// True in the strict sense: there is no device at this instant. It is
// also the useful answer, because a command issued now would find no
// bundle to run against.
return true;
}
if SPIRC_LOST.load(Ordering::SeqCst) {
return true;
}
session_invalid().unwrap_or(false)
}
pub fn is_connected() -> bool {
!OFFLINE.load(Ordering::SeqCst)
&& !RECONNECTING.load(Ordering::SeqCst)
&& session_invalid().map(|bad| !bad) == Some(true)
}
/// Whether the current session has been invalidated, or `None` if asking would
/// have meant waiting.
fn session_invalid() -> Option<bool> {
let guard = ENGINE.try_lock().ok()?;
let bundle = guard.as_ref()?.bundle.as_ref()?;
Some(bundle.session.is_invalid())
}
/// Tear the engine down. Safe to call when it was never started.
pub fn shutdown() {
let taken = ENGINE.lock().ok().and_then(|mut g| g.take());
if let Some(engine) = taken {
// Nothing may report against a bundle from here on, and the pump is
// about to go with the sender.
GENERATION.fetch_add(1, Ordering::SeqCst);
if let Some(bundle) = engine.bundle {
// Told to the account before the socket goes: a device that
// vanishes without disconnecting stays in the user's list until it
// times out.
if let Some(spirc) = bundle.spirc.as_ref() {
let _ = spirc.disconnect(true);
let _ = spirc.shutdown();
}
bundle.player.stop();
bundle.session.shutdown();
}
// Dropped so the pump thread's loop ends and the listener is released
// while that thread is still attached to the JVM.
drop(engine.events_tx);
crate::sink::clear_output();
// Dropping the runtime from a JNI thread is fine: no tokio context here.
engine.rt.shutdown_timeout(Duration::from_secs(2));
}
}