Skip to content

Unofficial YouTube Music / Spotify Premium client for Android, built in Liquid Glass. Audio effects, Spotify Connect, listening history, 8 languages. Rust core on librespot.

13.0 KB
Raw Blame
//! Telling Spotify what was listened to.
//!
//! Playback through librespot never appeared in the account's history, and the
//! reason is not a setting: Spotify builds "recently played" from *events* the
//! client posts, and librespot posts none. It publishes its Connect state, so
//! the servers know the device exists and what it is doing, but nothing in that
//! path counts as a listen — verified on the device by starting a track through
//! the Web API and watching the history stay unchanged while the audio played.
//!
//! The wire format is not documented by Spotify. It is taken from
//! librespot-java's `EventService` (Apache-2.0, by devgianlu), reimplemented
//! here rather than copied: events are Mercury POSTs to
//! `hm://event-service/v1/events`, whose body is a list of fields separated by
//! `0x09` and beginning with a numeric event id and a second constant nobody
//! has a name for.
//!
//! Three events make up one listen:
//!
//! * `557` — a new *session*, meaning a context was started.
//! * `558` — a new *playback*, meaning a track began within it.
//! * `12` — the transition off that track, carrying how far it got. This is the
//!   one Spotify counts.
//!
//! The Rust Mercury client has neither POST nor header fields, so both were
//! added to the vendored copy of librespot-core; see native/vendor/README.md.
//! An event that fails is a missing history entry, never a failed playback, so
//! nothing here is allowed to break anything.

use librespot_core::session::Session;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};

/// Separates fields in an event body.
const SEP: u8 = 0x09;

const EVENT_URI: &str = "hm://event-service/v1/events";

/// One event, built field by field.
struct Event {
    body: Vec<u8>,
}

impl Event {
    /// `id` and `unknown` identify the kind; see the module note.
    fn new(id: &str, unknown: &str) -> Self {
        let mut event = Event {
            body: id.as_bytes().to_vec(),
        };
        event.field(unknown);
        event
    }

    fn field(&mut self, value: &str) -> &mut Self {
        self.body.push(SEP);
        self.body.extend_from_slice(value.as_bytes());
        self
    }

    fn number(&mut self, value: impl ToString) -> &mut Self {
        self.field(&value.to_string())
    }
}

/// What ended a track, in Spotify's own vocabulary.
#[derive(Clone, Copy)]
pub enum EndReason {
    /// Played to the end.
    TrackDone,
    /// Skipped forwards.
    Forward,
    /// Skipped backwards.
    Backward,
    /// Playback stopped without another track following.
    EndPlay,
}

impl EndReason {
    fn as_str(self) -> &'static str {
        match self {
            EndReason::TrackDone => "trackdone",
            EndReason::Forward => "fwdbtn",
            EndReason::Backward => "backbtn",
            EndReason::EndPlay => "endplay",
        }
    }
}

/// Everything one finished track needs to be reported.
pub struct Listen<'a> {
    /// The track's id in hex — its gid, not the base62 in the URI.
    pub track_hex: &'a str,
    pub playback_id: &'a str,
    pub context_uri: &'a str,
    /// Where playback started within the track, in milliseconds.
    pub start_ms: u32,
    /// Where it stopped. This is what decides whether it counts as a listen.
    pub end_ms: u32,
    pub duration_ms: u32,
    pub reason_start: &'a str,
    pub reason_end: EndReason,
    /// Wall clock at the moment the track started, in milliseconds.
    pub started_at: u128,
}

/// Posts the events that make up the account's listening history.
pub struct EventService {
    session: Session,
    transitions: AtomicU64,
}

impl EventService {
    pub fn new(session: Session) -> Self {
        EventService {
            session,
            transitions: AtomicU64::new(0),
        }
    }

    /// A context was started — a playlist, an album, a single track.
    pub fn new_session(&self, session_id: &str, context_uri: &str, context_size: usize) {
        let mut event = Event::new("557", "3");
        event
            .field(session_id)
            .field(context_uri)
            .field(context_uri)
            .number(now_ms())
            .field("")
            .number(context_size)
            // The context's own URL, which the client uses to page through it.
            .field(&format!("context://{context_uri}"));
        self.post(event);
    }

    /// A track began within that context.
    pub fn new_playback(&self, playback_id: &str, session_id: &str) {
        let mut event = Event::new("558", "1");
        event.field(playback_id).field(session_id).number(now_ms());
        self.post(event);
    }

    /// A track ended. The one event Spotify turns into history.
    pub fn track_transition(&self, listen: &Listen) {
        let device_id = self.session.device_id().to_string();
        let count = self.transitions.fetch_add(1, Ordering::Relaxed);

        // Several of these are timings the official client measures and we do
        // not: how long the audio key took, how much was decrypted, how far the
        // decoder read ahead. Zero is what librespot-java sends when it has no
        // figure either, and Spotify has never rejected an event over them —
        // what it reads is the track, the context and how much was played.
        let mut event = Event::new("12", "38");
        event
            .number(count)
            .field(&device_id)
            .field(listen.playback_id)
            .field("00000000000000000000000000000000")
            // How playback began, and how it ended.
            .field("unknown")
            .field(listen.reason_start)
            .field("unknown")
            .field(listen.reason_end.as_str())
            // Bytes decoded, bytes total.
            .number(0)
            .number(0)
            // Where it stopped, twice.
            .number(listen.end_ms)
            .number(listen.end_ms)
            .number(listen.duration_ms)
            // Decrypt time, crossfade overlap, and two constants.
            .number(0)
            .number(0)
            .field("0")
            .field("0")
            // Whether it started from the beginning, and where from.
            .field(if listen.start_ms == 0 { "0" } else { "1" })
            .number(listen.start_ms)
            .field("0")
            .field("-1")
            .field("context")
            // Audio key timing.
            .number(0)
            .field("0")
            .field("0")
            .field("0")
            .field("0")
            .field("0")
            .number(listen.end_ms)
            .number(listen.end_ms)
            .field("0")
            .number(BITRATE)
            .field(listen.context_uri)
            .field(ENCODING)
            .field(listen.track_hex)
            .field("")
            .field("0")
            .number(listen.started_at)
            .field("0")
            .field("context")
            .field(REFERRER)
            .field(FEATURE_VERSION)
            .field("com.spotify")
            .field("none")
            .field("none")
            // Which device sent the last command. Ours: playback is started
            // here, not by a phone across the room.
            .field(&device_id)
            .field("na")
            .field("none");
        self.post(event);
    }

    /// Posts the event and logs what Spotify made of it.
    ///
    /// The reply matters more than it looks: a well-formed packet the server
    /// silently drops and a rejected one are indistinguishable without it, and
    /// this whole format is reverse-engineered. Upstream's Mercury client has
    /// neither POST nor header fields, so both were added to the vendored copy.
    fn post(&self, event: Event) {
        let body = event.body;
        let fields = vec![
            ("Accept-Language".to_string(), b"en".to_vec()),
            (
                "X-ClientTimeStamp".to_string(),
                now_ms().to_string().into_bytes(),
            ),
        ];

        let request = match self.session.mercury().post(EVENT_URI, body.clone(), fields) {
            Ok(request) => request,
            Err(e) => {
                log::warn!("event not sent: {e}");
                return;
            }
        };

        // Waited for on the engine's runtime rather than on the caller's
        // thread: this is called from the player's event pump, and blocking
        // there would hold up every other event behind a network round trip.
        // The event's kind, never its body. The body carries the track, the
        // context and the time — the user's listening, in a log any app holding
        // READ_LOGS can read.
        let kind = kind_of(&body);
        let Ok(handle) = crate::engine::runtime_handle() else {
            return;
        };
        handle.spawn(async move {
            match request.await {
                Ok(response) if response.status_code == 200 => {
                    log::debug!("event {kind} accepted")
                }
                Ok(response) => log::warn!("event {kind} refused: {}", response.status_code),
                Err(e) => log::warn!("event {kind} failed: {e}"),
            }
        });
    }
}

/// The event's numeric kind, which is all that may be logged; see [EventService::post].
fn kind_of(body: &[u8]) -> String {
    body.split(|byte| *byte == SEP)
        .next()
        .map(|id| String::from_utf8_lossy(id).to_string())
        .unwrap_or_default()
}

/// A listen interrupted by the process going away.
///
/// Written to disk while a track plays and cleared as soon as the transition is
/// sent. A phone kills a music app the moment it needs the memory, and until
/// this existed everything heard since the last pause went with it: the event
/// only ever left at a boundary, and being killed is not a boundary.
///
/// Reported on the next start, with the position it had reached and its
/// original timestamp. Late, but true — the alternative was silence.
pub mod pending {
    use super::{EndReason, EventService, Listen};
    use std::path::{Path, PathBuf};

    const FILE_NAME: &str = "pending-listen";

    pub struct Pending {
        pub track_hex: String,
        pub playback_id: String,
        pub context_uri: String,
        pub start_ms: u32,
        pub position_ms: u32,
        pub duration_ms: u32,
        pub started_at: u128,
    }

    fn path(dir: &str) -> PathBuf {
        Path::new(dir).join(FILE_NAME)
    }

    /// Tab-separated and hand-parsed: six values, written once a second.
    pub fn write(dir: &str, listen: &Pending) {
        let line = format!(
            "{}\t{}\t{}\t{}\t{}\t{}\t{}",
            listen.track_hex,
            listen.playback_id,
            listen.context_uri,
            listen.start_ms,
            listen.position_ms,
            listen.duration_ms,
            listen.started_at,
        );
        let _ = std::fs::write(path(dir), line);
    }

    pub fn clear(dir: &str) {
        let _ = std::fs::remove_file(path(dir));
    }

    /// Sends whatever the last run was in the middle of, and forgets it.
    pub fn flush(dir: &str, events: &EventService) {
        let Ok(raw) = std::fs::read_to_string(path(dir)) else {
            return;
        };
        clear(dir);

        let parts: Vec<&str> = raw.split('\t').collect();
        if parts.len() != 7 {
            return;
        }
        let number = |index: usize| parts[index].parse().unwrap_or(0);
        let position_ms: u32 = number(4);
        let start_ms: u32 = number(3);
        if position_ms <= start_ms {
            return;
        }

        log::info!("reporting a listen the last run did not finish");
        events.track_transition(&Listen {
            track_hex: parts[0],
            playback_id: parts[1],
            context_uri: parts[2],
            start_ms,
            end_ms: position_ms,
            duration_ms: number(5),
            reason_start: "playbtn",
            reason_end: EndReason::EndPlay,
            started_at: parts[6].parse().unwrap_or(0),
        });
    }
}

pub fn now_ms() -> u128 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_millis())
        .unwrap_or(0)
}

/// A 32-character hex id, which is the shape Spotify uses for both of these.
pub fn random_id() -> String {
    let mut id = String::with_capacity(32);
    for _ in 0..4 {
        // Exactly eight characters per part: Spotify's ids are 32 long, and a
        // u64 printed as hex ran to sixteen when the value was large enough,
        // which made every id a different length.
        let part = (SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map(|d| d.subsec_nanos() as u64)
            .unwrap_or(0)
            ^ rand_seed()) as u32;
        id.push_str(&format!("{part:08x}"));
    }
    id
}

fn rand_seed() -> u64 {
    use std::collections::hash_map::RandomState;
    use std::hash::{BuildHasher, Hasher};
    RandomState::new().build_hasher().finish()
}

/// 160 kbps, the ordinary quality this client asks for.
const BITRATE: u32 = 160_000;
const ENCODING: &str = "vorbis";

/// Where the play came from, in the client's own vocabulary.
const REFERRER: &str = "unknown";
const FEATURE_VERSION: &str = "harmony:4.21.0";