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.

164 KB
Raw Blame
use std::{
    collections::HashMap,
    fmt, fs,
    fs::File,
    future::Future,
    io::{self, Read, Seek, SeekFrom},
    mem,
    pin::Pin,
    process::exit,
    sync::Mutex,
    sync::{
        Arc,
        atomic::{AtomicUsize, Ordering},
    },
    task::{Context, Poll},
    thread,
    time::{Duration, Instant},
};

#[cfg(feature = "passthrough-decoder")]
use crate::decoder::PassthroughDecoder;
use crate::{
    audio::{AudioDecrypt, AudioFetchParams, AudioFile, StreamLoaderController},
    audio_backend::Sink,
    config::{Bitrate, NormalisationMethod, NormalisationType, PlayerConfig},
    convert::Converter,
    core::{Error, Session, SpotifyId, SpotifyUri, util::SeqGenerator},
    decoder::{AudioDecoder, AudioPacket, AudioPacketPosition, SymphoniaDecoder},
    local_file::{LocalFileLookup, create_local_file_lookup},
    metadata::audio::{AudioFileFormat, AudioFiles, AudioItem},
    mixer::VolumeGetter,
};
use futures_util::{
    FutureExt, StreamExt, TryFutureExt, future, future::FusedFuture,
    stream::futures_unordered::FuturesUnordered,
};
use librespot_metadata::{audio::UniqueFields, track::Tracks};

use symphonia::core::io::MediaSource;
use symphonia::core::probe::Hint;
use tokio::sync::{mpsc, oneshot};

use crate::{NUM_CHANNELS, SAMPLE_RATE, SAMPLES_PER_SECOND};

/// LOCAL PATCH: Spotify's DJ, talking around the tracks it plays.
///
/// A DJ session gives some tracks a line before them and some a line after,
/// which the app has synthesised into audio by the time they play. The player
/// is the only place that knows where one track's sound ends and the next
/// one's begins, so this is where the lines are put: written to the sink
/// before the track's first packet and after its last, one after the other,
/// never mixed, as the official client does. The app says what to say; the
/// player only asks it, at those two moments, through [`set_narration_provider`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum NarrationMoment {
    /// Before the track's first packet.
    Before,
    /// After its last, before its end is announced.
    After,
}

/// What the app answers with: interleaved stereo at [`SAMPLE_RATE`], already
/// at the level it should be heard at, or nothing to say.
pub type NarrationProvider =
    dyn Fn(&str, NarrationMoment) -> Option<Arc<Vec<f64>>> + Send + Sync;

static NARRATION_PROVIDER: std::sync::OnceLock<Box<NarrationProvider>> = std::sync::OnceLock::new();

/// Whether a line comes at the end of a track: its own closing one, or the
/// opening one of the track after it. Asked without taking either.
pub type NarrationFollows = dyn Fn(&str) -> bool + Send + Sync;

static NARRATION_FOLLOWS: std::sync::OnceLock<Box<NarrationFollows>> = std::sync::OnceLock::new();

/// Installs the question above. Once, like the provider.
pub fn set_narration_follows(follows: Box<NarrationFollows>) {
    let _ = NARRATION_FOLLOWS.set(follows);
}

/// Whether [track_id] ends in a line, so it must not dissolve into the next
/// track: a crossfade would run the music under the DJ talking.
fn narration_follows(track_id: &SpotifyUri) -> bool {
    narrating()
        && track_id
            .to_uri()
            .ok()
            .zip(NARRATION_FOLLOWS.get())
            .is_some_and(|(uri, follows)| follows(&uri))
}

/// Whether a narrated session is playing: the player asks for lines only then,
/// and does not dissolve a track into the next where a line comes between
/// them; see [`narration_follows`].
static NARRATING: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// Installs where the lines come from. Once: the app has one.
pub fn set_narration_provider(provider: Box<NarrationProvider>) {
    let _ = NARRATION_PROVIDER.set(provider);
}

/// Turns the narrated session on or off; see [`NARRATING`].
pub fn set_narrating(on: bool) {
    NARRATING.store(on, Ordering::SeqCst);
}

fn narrating() -> bool {
    NARRATING.load(Ordering::SeqCst)
}

/// True while the samples being written to the sink are a line rather than
/// music: the sink hands them on separately, so the app's effects, made for
/// the music, leave the voice alone.
static SPEAKING: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// Whether the packet the sink is being given is the DJ's voice.
pub fn speaking() -> bool {
    SPEAKING.load(Ordering::SeqCst)
}

fn narration_for(track_id: &SpotifyUri, moment: NarrationMoment) -> Option<Arc<Vec<f64>>> {
    if !narrating() {
        return None;
    }
    let uri = track_id.to_uri().ok()?;
    NARRATION_PROVIDER.get()?(&uri, moment).filter(|samples| !samples.is_empty())
}

/// LOCAL PATCH: a line being spoken, and how far into it.
struct Narration {
    samples: Arc<Vec<f64>>,
    at: usize,
    /// A closing line: the track's end is announced once it has been said.
    then_end: bool,
}

/// LOCAL PATCH: how much of a line is written at a time, in interleaved
/// samples: about a twentieth of a second, so a pause or a skip is answered
/// between two of them.
const NARRATION_CHUNK: usize = 4096;

/// LOCAL PATCH: a track that starts further in than this was resumed, not
/// arrived at, and is not introduced.
const NARRATION_START_WINDOW_MS: u32 = 1500;

/// LOCAL PATCH: how many times a failed load is tried again before the track is
/// called unavailable, and how long the first wait is (it doubles each time).
///
/// Four attempts over about seven seconds. Long enough to ride out a lift, a
/// tunnel or a handover between cells, short enough that a track which really
/// is gone does not hold the queue for a minute.
const MAX_LOAD_ATTEMPTS: u8 = 3;
const LOAD_RETRY_BACKOFF: Duration = Duration::from_millis(900);

const PRELOAD_NEXT_TRACK_BEFORE_END_DURATION_MS: u32 = 30000;

/// LOCAL PATCH: how far from the end of a track its stream can run out and
/// still count as the track having ended.
///
/// Three seconds. Decoders and metadata disagree about the last fraction of a
/// second, and a track cut three seconds short is something a listener hears.
const SHORT_END_TOLERANCE_MS: i64 = 3_000;



/// LOCAL PATCH: how many times a track whose stream keeps running out early is
/// put back on before it is allowed to end. See [SHORT_END_TOLERANCE_MS].
const MAX_SHORT_END_RELOADS: u8 = 2;



/// LOCAL PATCH: the largest value that survives conversion to signed 16 bit.
///
/// Full scale is asymmetric: -32768 exists, +32768 does not, so a mix that
/// reaches 1.0 on the way up wraps around to the bottom and is heard as a click.
const MAX_SAMPLE: f64 = 32767.0 / 32768.0;

/// LOCAL PATCH: smooth soft-knee saturation limiter to prevent digital clipping (0 dBFS overflow)
/// while maintaining bit-perfect audio transparency below 0.85 (~ -1.4 dBFS).
#[inline]
fn soft_limit(x: f64) -> f64 {
    const THRESHOLD: f64 = 0.85;
    let abs_x = x.abs();
    if abs_x <= THRESHOLD {
        x
    } else {
        let sign = x.signum();
        let excess = abs_x - THRESHOLD;
        let margin = 1.0 - THRESHOLD;
        let limited = THRESHOLD + margin * (excess / margin).tanh();
        (sign * limited).clamp(-1.0, MAX_SAMPLE)
    }
}
pub const DB_VOLTAGE_RATIO: f64 = 20.0;
pub const PCM_AT_0DBFS: f64 = 1.0;

// Spotify inserts a custom Ogg packet at the start with custom metadata values, that you would
// otherwise expect in Vorbis comments. This packet isn't well-formed and players may balk at it.
const SPOTIFY_OGG_HEADER_END: u64 = 0xa7;

const LOAD_HANDLES_POISON_MSG: &str = "load handles mutex should not be poisoned";

pub type PlayerResult = Result<(), Error>;

pub struct Player {
    commands: Option<mpsc::UnboundedSender<PlayerCommand>>,
    thread_handle: Option<thread::JoinHandle<()>>,
}

#[derive(PartialEq, Eq, Debug, Clone, Copy)]
pub enum SinkStatus {
    Running,
    Closed,
    TemporarilyClosed,
}

pub type SinkEventCallback = Box<dyn Fn(SinkStatus) + Send>;

/// LOCAL PATCH: one transition of a mixed playlist, from the song playing
/// into the one after it.
///
/// A playlist mixed in Spotify's own app keeps, on the row a transition starts
/// from, where the song starts handing over (`out_ms`), where the next one
/// comes in (`in_ms`) and how long the two overlap (`fade_ms`). The player
/// announces the end at `out_ms` instead of a crossfade's length before the
/// end, fades over `fade_ms`, and starts `to` at `in_ms` when it is loaded
/// from the start. Set for the pair that is actually next, and only that one:
/// a shuffled queue or a skip has no use for it, and it does nothing to any
/// other song.
#[derive(Clone, Debug)]
pub struct MixPlan {
    pub from: String,
    pub out_ms: u32,
    pub fade_ms: u32,
    pub to: String,
    pub in_ms: u32,
    /// How fast `to` plays while the two overlap, to put its beats on the
    /// outgoing song's: 1.0 for a transition that is not beatmatched. It
    /// eases back to 1.0 after the overlap; see [TempoRamp].
    pub speed_in: f32,
}

/// LOCAL PATCH: the incoming song of a beatmatched mix transition, played a
/// little faster or slower so its beats land on the outgoing one's.
///
/// Resampled, the way a turntable's pitch fader does it: the key moves with
/// the tempo, by about a semitone at the 6% a typical transition asks for.
/// Held at [MixPlan::speed_in] for the overlap, then eased back to normal
/// over [TEMPO_RETURN_MS], so the song settles into its own tempo rather than
/// jumping to it.
struct TempoRamp {
    speed_in: f64,
    /// Output frames still to come at `speed_in`, then over the return.
    hold: usize,
    ramp: usize,
    done: usize,
    /// Input frames not yet used, interleaved, and where in them the next
    /// output frame is read from.
    carry: Vec<f64>,
    position: f64,
}

/// LOCAL PATCH: how long the incoming song takes to come back to its own
/// tempo after a beatmatched transition.
const TEMPO_RETURN_MS: u32 = 8000;

impl TempoRamp {
    fn new(speed_in: f32, hold_ms: u32) -> Self {
        let frames = |ms: u32| ms as usize * SAMPLE_RATE as usize / 1000;
        Self {
            speed_in: speed_in as f64,
            hold: frames(hold_ms),
            ramp: frames(TEMPO_RETURN_MS),
            done: 0,
            carry: Vec::new(),
            position: 0.0,
        }
    }

    fn speed(&self) -> f64 {
        if self.done < self.hold {
            return self.speed_in;
        }
        let x = ((self.done - self.hold) as f64 / self.ramp.max(1) as f64).min(1.0);
        // Eased, so the tempo leaves the matched speed and arrives at its own
        // without a corner either end.
        let eased = x * x * (3.0 - 2.0 * x);
        self.speed_in + (1.0 - self.speed_in) * eased
    }

    fn finished(&self) -> bool {
        self.done >= self.hold + self.ramp
    }

    /// The packet's samples at the speed of the moment, read between frames.
    fn process(&mut self, data: &[f64]) -> Vec<f64> {
        let channels = NUM_CHANNELS as usize;
        self.carry.extend_from_slice(data);
        let frames = self.carry.len() / channels;
        let mut out = Vec::with_capacity(data.len() + channels * 2);
        while !self.finished() {
            let at = self.position.floor() as usize;
            if at + 1 >= frames {
                break;
            }
            let t = self.position - at as f64;
            for c in 0..channels {
                let a = self.carry[at * channels + c];
                let b = self.carry[(at + 1) * channels + c];
                out.push(a + (b - a) * t);
            }
            self.position += self.speed();
            self.done += 1;
        }
        if self.finished() {
            // Back at its own speed: what is left goes out as it is.
            let at = (self.position.round() as usize).min(frames);
            out.extend_from_slice(&self.carry[at * channels..]);
            self.carry.clear();
            self.position = 0.0;
        } else {
            let used = (self.position.floor() as usize).min(frames);
            self.carry.drain(..used * channels);
            self.position -= used as f64;
        }
        out
    }
}

struct PlayerInternal {
    session: Session,
    config: PlayerConfig,
    commands: mpsc::UnboundedReceiver<PlayerCommand>,
    load_handles: Arc<Mutex<HashMap<thread::ThreadId, thread::JoinHandle<()>>>>,

    state: PlayerState,
    preload: PlayerPreload,
    sink: Box<dyn Sink>,
    sink_status: SinkStatus,
    sink_event_callback: Option<SinkEventCallback>,
    volume_getter: Box<dyn VolumeGetter + Send>,
    event_senders: Vec<mpsc::UnboundedSender<PlayerEvent>>,
    converter: Converter,

    normalisation_integrators: [f64; 2],
    normalisation_peaks: [f64; 2],
    normalisation_channel: usize,
    normalisation_knee_factor: f64,

    auto_normalise_as_album: bool,

    player_id: usize,
    play_request_id_generator: SeqGenerator<u64>,
    last_progress_update: Instant,

    local_file_lookup: Arc<LocalFileLookup>,

    /// LOCAL PATCH: the track being dissolved out of, if there is one.
    fade_out: Option<FadeOut>,
    /// LOCAL PATCH: the play request whose end has already been announced early.
    early_end: Option<u64>,
    /// LOCAL PATCH: the transition into the next song, when a mixed playlist
    /// names one; see [MixPlan].
    mix_plan: Option<MixPlan>,
    /// LOCAL PATCH: the length of the fade an announced mix transition owes,
    /// in milliseconds, taken by the load that answers the announcement.
    mix_fade_ms: Option<u32>,
    /// LOCAL PATCH: the incoming song of a beatmatched transition, while it
    /// plays off its own tempo; see [TempoRamp].
    tempo: Option<TempoRamp>,
    /// LOCAL PATCH: the play request that has been heard playing before its own
    /// fade window, and so may have its end announced early. See the use of it.
    fade_armed: Option<u64>,
    /// LOCAL PATCH: consecutive silent samples observed near end of track for silence trimming.
    consecutive_silent_samples: usize,
    /// LOCAL PATCH: how many times a play request has had its stream run out
    /// before the end of the track, so a stream that never completes gives up
    /// instead of putting the same song back on for ever.
    short_end: Option<(u64, u8)>,
    /// LOCAL PATCH: the play request whose end has already been announced, by
    /// whichever of the paths announces one. See `announce_end`.
    ended: Option<u64>,
    /// LOCAL PATCH: how many times the track being loaded has been retried, and
    /// from what position, so a retry resumes the same load. See the failure
    /// branch of the loading state in `poll`.
    load_attempt: u8,
    load_position_ms: u32,
    /// LOCAL PATCH: the DJ's line being spoken, if one is; see [`Narration`].
    narration: Option<Narration>,
    /// LOCAL PATCH: the play requests already asked for their opening and
    /// closing lines, so each is asked once.
    narrated_before: Option<u64>,
    narrated_after: Option<u64>,
}

/// LOCAL PATCH: the outgoing half of a crossfade.
///
/// A track that is on its way out is no longer the player's state: the state
/// holds the track coming in. Its decoder is kept here instead and read for as
/// long as the fade lasts, then dropped, which closes the stream behind it.
struct FadeOut {
    decoder: Decoder,
    /// The gain the outgoing track was being played at.
    ///
    /// Its own factor, not the incoming track's: normalisation exists so that
    /// two tracks mastered at different levels sound alike, and a fade is the
    /// one moment both are audible at once.
    normalisation_factor: f64,
    /// Length of the fade in samples, so the gain curve knows its own scale.
    total: usize,
    /// How much of it has been mixed.
    done: usize,
    /// Decoded samples not yet used, since a packet rarely lands exactly on the
    /// boundary of what the incoming packet needs.
    spare: std::collections::VecDeque<f64>,
    /// Set when the outgoing track runs out before the fade does.
    drained: bool,
    /// LOCAL PATCH: for a fade the listener started, how far the incoming
    /// track has risen, counted from when it started making a sound. `None`
    /// at the end of a track, where both halves move on the one clock.
    ///
    /// A song picked from a list is not loaded yet when the one playing starts
    /// to go, and the outgoing half runs on through the load. On one clock the
    /// incoming song then came in most of the way up already, which is a cut
    /// with a fade in front of it.
    rising: Option<usize>,
    /// LOCAL PATCH: the limiter the outgoing track was being played through,
    /// carried on for its tail; see [`TailLimiter`].
    limiter: TailLimiter,
}

/// LOCAL PATCH: the dynamic limiter, for the tail of a crossfade.
///
/// A track plays through the limiter after its normalisation gain, and the
/// tail of one being faded out used to be given the gain alone. Where the gain
/// is above unity — a quiet local file brought up to the level of the streamed
/// tracks, plus the pregain — the tail came out far louder than the song had
/// been a second before. This is the same limiter, picking up from where the
/// main one was when the fade began, so the tail stays at its own level.
#[derive(Clone, Copy)]
struct TailLimiter {
    integrators: [f64; 2],
    peaks: [f64; 2],
    channel: usize,
}

/// LOCAL PATCH: what [`TailLimiter`] needs from the configuration, copied out
/// so it can be read while the fade is borrowed.
#[derive(Clone, Copy)]
struct LimiterParams {
    dynamic: bool,
    threshold_db: f64,
    knee_db: f64,
    knee_factor: f64,
    attack_cf: f64,
    release_cf: f64,
}

impl TailLimiter {
    /// The main limiter's step, on one sample already scaled by its gain.
    fn limit(&mut self, sample: f64, params: &LimiterParams) -> f64 {
        if !params.dynamic {
            return sample;
        }
        let sample = sample + f64::MIN_POSITIVE;
        let bias_db = ratio_to_db(sample.abs()) - params.threshold_db;
        let knee_boundary_db = bias_db * 2.0;
        let limiter_db = if knee_boundary_db < -params.knee_db {
            0.0
        } else if knee_boundary_db.abs() <= params.knee_db {
            let term = knee_boundary_db + params.knee_db;
            term * term * params.knee_factor
        } else {
            bias_db
        };
        let channel = self.channel;
        self.channel ^= 1;
        let integrator = &mut self.integrators[channel];
        *integrator = f64::max(
            limiter_db,
            params.release_cf * *integrator + (1.0 - params.release_cf) * limiter_db,
        );
        let peak = &mut self.peaks[channel];
        *peak = params.attack_cf * *peak + (1.0 - params.attack_cf) * *integrator;
        sample * db_to_ratio(-f64::max(self.peaks[0], self.peaks[1]))
    }
}

static PLAYER_COUNTER: AtomicUsize = AtomicUsize::new(0);

enum PlayerCommand {
    Load {
        track_id: SpotifyUri,
        play: bool,
        position_ms: u32,
    },
    Preload {
        track_id: SpotifyUri,
    },
    Play,
    Pause,
    Stop,
    Seek(u32),
    SetSession(Session),
    AddEventSender(mpsc::UnboundedSender<PlayerEvent>),
    SetSinkEventCallback(Option<SinkEventCallback>),
    EmitVolumeChangedEvent(u16),
    SetAutoNormaliseAsAlbum(bool),
    /// LOCAL PATCH: the quality to ask for from the next load onwards.
    SetBitrate(Bitrate),
    /// LOCAL PATCH: whether trailing silence triggers early crossfade.
    SetTrimSilence(bool),
    /// LOCAL PATCH: see PlayerConfig::hold_end.
    SetHoldEnd(bool),
    /// LOCAL PATCH: see [MixPlan].
    SetMixPlan(Option<MixPlan>),
    /// LOCAL PATCH: see PlayerConfig::skip_fade_ms.
    SetSkipFade(u32),
    EmitSessionDisconnectedEvent {
        connection_id: String,
        user_name: String,
    },
    EmitSessionConnectedEvent {
        connection_id: String,
        user_name: String,
    },
    EmitSessionClientChangedEvent {
        client_id: String,
        client_name: String,
        client_brand_name: String,
        client_model_name: String,
    },
    EmitFilterExplicitContentChangedEvent(bool),
    EmitShuffleChangedEvent(bool),
    EmitRepeatChangedEvent {
        context: bool,
        track: bool,
    },
    EmitAutoPlayChangedEvent(bool),
}

#[derive(Debug, Clone)]
pub enum PlayerEvent {
    // Play request id changed
    PlayRequestIdChanged {
        play_request_id: u64,
    },
    // Fired when the player is stopped (e.g. by issuing a "stop" command to the player).
    Stopped {
        play_request_id: u64,
        track_id: SpotifyUri,
    },
    // The player is delayed by loading a track.
    Loading {
        play_request_id: u64,
        track_id: SpotifyUri,
        position_ms: u32,
    },
    // The player is preloading a track.
    Preloading {
        track_id: SpotifyUri,
    },
    // The player is playing a track.
    // This event is issued at the start of playback of whenever the position must be communicated
    // because it is out of sync. This includes:
    // start of a track
    // un-pausing
    // after a seek
    // after a buffer-underrun
    Playing {
        play_request_id: u64,
        track_id: SpotifyUri,
        position_ms: u32,
    },
    // The player entered a paused state.
    Paused {
        play_request_id: u64,
        track_id: SpotifyUri,
        position_ms: u32,
    },
    // The player thinks it's a good idea to issue a preload command for the next track now.
    // This event is intended for use within spirc.
    TimeToPreloadNextTrack {
        play_request_id: u64,
        track_id: SpotifyUri,
    },
    // The player reached the end of a track.
    // This event is intended for use within spirc. Spirc will respond by issuing another command.
    EndOfTrack {
        play_request_id: u64,
        track_id: SpotifyUri,
    },
    // The player was unable to load the requested track.
    Unavailable {
        play_request_id: u64,
        track_id: SpotifyUri,
    },
    // The mixer volume was set to a new level.
    VolumeChanged {
        volume: u16,
    },
    PositionCorrection {
        play_request_id: u64,
        track_id: SpotifyUri,
        position_ms: u32,
    },
    /// Requires `PlayerConfig::position_update_interval` to be set to Some.
    /// Once set this event will be sent periodically while playing the track to inform about the
    /// current playback position
    PositionChanged {
        play_request_id: u64,
        track_id: SpotifyUri,
        position_ms: u32,
    },
    Seeked {
        play_request_id: u64,
        track_id: SpotifyUri,
        position_ms: u32,
    },
    TrackChanged {
        audio_item: Box<AudioItem>,
    },
    SessionConnected {
        connection_id: String,
        user_name: String,
    },
    SessionDisconnected {
        connection_id: String,
        user_name: String,
    },
    SessionClientChanged {
        client_id: String,
        client_name: String,
        client_brand_name: String,
        client_model_name: String,
    },
    ShuffleChanged {
        shuffle: bool,
    },
    RepeatChanged {
        context: bool,
        track: bool,
    },
    AutoPlayChanged {
        auto_play: bool,
    },
    FilterExplicitContentChanged {
        filter: bool,
    },
}

impl PlayerEvent {
    pub fn get_play_request_id(&self) -> Option<u64> {
        use PlayerEvent::*;
        match self {
            Loading {
                play_request_id, ..
            }
            | Unavailable {
                play_request_id, ..
            }
            | Playing {
                play_request_id, ..
            }
            | TimeToPreloadNextTrack {
                play_request_id, ..
            }
            | EndOfTrack {
                play_request_id, ..
            }
            | Paused {
                play_request_id, ..
            }
            | Stopped {
                play_request_id, ..
            }
            | PositionCorrection {
                play_request_id, ..
            }
            | Seeked {
                play_request_id, ..
            } => Some(*play_request_id),
            _ => None,
        }
    }
}

pub type PlayerEventChannel = mpsc::UnboundedReceiver<PlayerEvent>;

#[inline]
pub fn db_to_ratio(db: f64) -> f64 {
    f64::powf(10.0, db / DB_VOLTAGE_RATIO)
}

#[inline]
pub fn ratio_to_db(ratio: f64) -> f64 {
    ratio.log10() * DB_VOLTAGE_RATIO
}

pub fn duration_to_coefficient(duration: Duration) -> f64 {
    f64::exp(-1.0 / (duration.as_secs_f64() * SAMPLES_PER_SECOND as f64))
}

pub fn coefficient_to_duration(coefficient: f64) -> Duration {
    Duration::from_secs_f64(-1.0 / f64::ln(coefficient) / SAMPLES_PER_SECOND as f64)
}

#[derive(Clone, Copy, Debug)]
pub struct NormalisationData {
    // Spotify provides these as `f32`, but audio metadata can contain up to `f64`.
    // Also, this negates the need for casting during sample processing.
    pub track_gain_db: f64,
    pub track_peak: f64,
    pub album_gain_db: f64,
    pub album_peak: f64,
}

impl Default for NormalisationData {
    fn default() -> Self {
        Self {
            track_gain_db: 0.0,
            track_peak: 1.0,
            album_gain_db: 0.0,
            album_peak: 1.0,
        }
    }
}

impl NormalisationData {
    fn parse_from_ogg<T: Read + Seek>(mut file: T) -> io::Result<NormalisationData> {
        const SPOTIFY_NORMALIZATION_HEADER_START_OFFSET: u64 = 144;
        const NORMALISATION_DATA_SIZE: usize = 16;

        let newpos = file.seek(SeekFrom::Start(SPOTIFY_NORMALIZATION_HEADER_START_OFFSET))?;
        if newpos != SPOTIFY_NORMALIZATION_HEADER_START_OFFSET {
            error!(
                "NormalisationData::parse_from_file seeking to {SPOTIFY_NORMALIZATION_HEADER_START_OFFSET} but position is now {newpos}"
            );

            error!("Falling back to default (non-track and non-album) normalisation data.");

            return Ok(NormalisationData::default());
        }

        let mut buf = [0u8; NORMALISATION_DATA_SIZE];

        file.read_exact(&mut buf)?;

        let track_gain_db = f32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]) as f64;
        let track_peak = f32::from_le_bytes([buf[4], buf[5], buf[6], buf[7]]) as f64;
        let album_gain_db = f32::from_le_bytes([buf[8], buf[9], buf[10], buf[11]]) as f64;
        let album_peak = f32::from_le_bytes([buf[12], buf[13], buf[14], buf[15]]) as f64;

        Ok(Self {
            track_gain_db,
            track_peak,
            album_gain_db,
            album_peak,
        })
    }

    fn get_factor(config: &PlayerConfig, data: NormalisationData) -> f64 {
        if !config.normalisation {
            return 1.0;
        }

        let (gain_db, gain_peak) = if config.normalisation_type == NormalisationType::Album {
            (data.album_gain_db, data.album_peak)
        } else {
            (data.track_gain_db, data.track_peak)
        };

        // As per the ReplayGain 1.0 & 2.0 (proposed) spec:
        // https://wiki.hydrogenaud.io/index.php?title=ReplayGain_1.0_specification#Clipping_prevention
        // https://wiki.hydrogenaud.io/index.php?title=ReplayGain_2.0_specification#Clipping_prevention
        let normalisation_factor = if config.normalisation_method == NormalisationMethod::Basic {
            // For Basic Normalisation, factor = min(ratio of (ReplayGain + PreGain), 1.0 / peak level).
            // https://wiki.hydrogenaud.io/index.php?title=ReplayGain_1.0_specification#Peak_amplitude
            // https://wiki.hydrogenaud.io/index.php?title=ReplayGain_2.0_specification#Peak_amplitude
            // We then limit that to 1.0 as not to exceed dBFS (0.0 dB).
            let factor = f64::min(
                db_to_ratio(gain_db + config.normalisation_pregain_db),
                PCM_AT_0DBFS / gain_peak,
            );

            if factor > PCM_AT_0DBFS {
                info!(
                    "Lowering gain by {:.2} dB for the duration of this track to avoid potentially exceeding dBFS.",
                    ratio_to_db(factor)
                );

                PCM_AT_0DBFS
            } else {
                factor
            }
        } else {
            // For Dynamic Normalisation it's up to the player to decide,
            // factor = ratio of (ReplayGain + PreGain).
            // We then let the dynamic limiter handle gain reduction.
            let factor = db_to_ratio(gain_db + config.normalisation_pregain_db);
            let threshold_ratio = db_to_ratio(config.normalisation_threshold_dbfs);

            if factor > PCM_AT_0DBFS {
                let factor_db = gain_db + config.normalisation_pregain_db;
                let limiting_db = factor_db + config.normalisation_threshold_dbfs.abs();

                warn!(
                    "This track may exceed dBFS by {factor_db:.2} dB and be subject to {limiting_db:.2} dB of dynamic limiting at its peak."
                );
            } else if factor > threshold_ratio {
                let limiting_db = gain_db
                    + config.normalisation_pregain_db
                    + config.normalisation_threshold_dbfs.abs();

                info!(
                    "This track may be subject to {limiting_db:.2} dB of dynamic limiting at its peak."
                );
            }

            factor
        };

        debug!("Normalisation Data: {data:?}");
        debug!(
            "Calculated Normalisation Factor for {:?}: {:.2}%",
            config.normalisation_type,
            normalisation_factor * 100.0
        );

        normalisation_factor
    }
}

impl Player {
    pub fn new<F>(
        config: PlayerConfig,
        session: Session,
        volume_getter: Box<dyn VolumeGetter + Send>,
        sink_builder: F,
    ) -> Arc<Self>
    where
        F: FnOnce() -> Box<dyn Sink> + Send + 'static,
    {
        let (cmd_tx, cmd_rx) = mpsc::unbounded_channel();

        if config.normalisation {
            debug!("Normalisation Type: {:?}", config.normalisation_type);
            debug!(
                "Normalisation Pregain: {:.1} dB",
                config.normalisation_pregain_db
            );
            debug!(
                "Normalisation Threshold: {:.1} dBFS",
                config.normalisation_threshold_dbfs
            );
            debug!("Normalisation Method: {:?}", config.normalisation_method);

            if config.normalisation_method == NormalisationMethod::Dynamic {
                // as_millis() has rounding errors (truncates)
                debug!(
                    "Normalisation Attack: {:.0} ms",
                    coefficient_to_duration(config.normalisation_attack_cf).as_secs_f64() * 1000.
                );
                debug!(
                    "Normalisation Release: {:.0} ms",
                    coefficient_to_duration(config.normalisation_release_cf).as_secs_f64() * 1000.
                );
                debug!("Normalisation Knee: {} dB", config.normalisation_knee_db);
            }
        }

        let handle = thread::spawn(move || {
            let player_id = PLAYER_COUNTER.fetch_add(1, Ordering::AcqRel);
            debug!("new Player [{player_id}]");

            let converter = Converter::new(config.ditherer);
            let normalisation_knee_factor = 1.0 / (8.0 * config.normalisation_knee_db);

            // TODO: it would be neat if we could watch for added or modified files in the
            // specified directories, and dynamically update the lookup. Currently, a new player
            // must be created for any new local files to be playable.
            let local_file_lookup =
                create_local_file_lookup(config.local_file_directories.as_slice());

            let internal = PlayerInternal {
                session,
                config,
                commands: cmd_rx,
                load_handles: Arc::new(Mutex::new(HashMap::new())),

                state: PlayerState::Stopped,
                preload: PlayerPreload::None,
                sink: sink_builder(),
                sink_status: SinkStatus::Closed,
                sink_event_callback: None,
                volume_getter,
                event_senders: vec![],
                converter,

                fade_out: None,
                early_end: None,
                mix_plan: None,
                mix_fade_ms: None,
                tempo: None,
                fade_armed: None,
                consecutive_silent_samples: 0,
                short_end: None,
                ended: None,
                load_attempt: 0,
                load_position_ms: 0,
                narration: None,
                narrated_before: None,
                narrated_after: None,
                normalisation_peaks: [0.0; 2],
                normalisation_integrators: [0.0; 2],
                normalisation_channel: 0,
                normalisation_knee_factor,

                auto_normalise_as_album: false,

                player_id,
                play_request_id_generator: SeqGenerator::new(0),
                last_progress_update: Instant::now(),

                local_file_lookup: Arc::new(local_file_lookup),
            };

            // While PlayerInternal is written as a future, it still contains blocking code.
            // It must be run by using block_on() in a dedicated thread.
            let runtime = tokio::runtime::Runtime::new().expect("Failed to create Tokio runtime");
            runtime.block_on(internal);

            debug!("PlayerInternal thread finished.");
        });

        Arc::new(Self {
            commands: Some(cmd_tx),
            thread_handle: Some(handle),
        })
    }

    pub fn is_invalid(&self) -> bool {
        if let Some(handle) = self.thread_handle.as_ref() {
            return handle.is_finished();
        }
        true
    }

    fn command(&self, cmd: PlayerCommand) {
        if let Some(commands) = self.commands.as_ref() {
            if let Err(e) = commands.send(cmd) {
                error!("Player Commands Error: {e}");
            }
        }
    }

    pub fn load(&self, track_id: SpotifyUri, start_playing: bool, position_ms: u32) {
        self.command(PlayerCommand::Load {
            track_id,
            play: start_playing,
            position_ms,
        });
    }

    pub fn preload(&self, track_id: SpotifyUri) {
        self.command(PlayerCommand::Preload { track_id });
    }

    pub fn play(&self) {
        self.command(PlayerCommand::Play)
    }

    pub fn pause(&self) {
        self.command(PlayerCommand::Pause)
    }

    pub fn stop(&self) {
        self.command(PlayerCommand::Stop)
    }


    pub fn seek(&self, position_ms: u32) {
        self.command(PlayerCommand::Seek(position_ms));
    }

    pub fn set_session(&self, session: Session) {
        self.command(PlayerCommand::SetSession(session));
    }

    pub fn get_player_event_channel(&self) -> PlayerEventChannel {
        let (event_sender, event_receiver) = mpsc::unbounded_channel();
        self.command(PlayerCommand::AddEventSender(event_sender));
        event_receiver
    }

    pub async fn await_end_of_track(&self) {
        let mut channel = self.get_player_event_channel();
        while let Some(event) = channel.recv().await {
            if matches!(
                event,
                PlayerEvent::EndOfTrack { .. } | PlayerEvent::Stopped { .. }
            ) {
                return;
            }
        }
    }

    pub fn set_sink_event_callback(&self, callback: Option<SinkEventCallback>) {
        self.command(PlayerCommand::SetSinkEventCallback(callback));
    }

    pub fn emit_volume_changed_event(&self, volume: u16) {
        self.command(PlayerCommand::EmitVolumeChangedEvent(volume));
    }

    pub fn set_auto_normalise_as_album(&self, setting: bool) {
        self.command(PlayerCommand::SetAutoNormaliseAsAlbum(setting));
    }

    /// LOCAL PATCH: change the quality without building another player.
    ///
    /// The bitrate is only ever read while a track is being loaded, to put the
    /// available formats in order of preference, so there is nothing about it
    /// that has to be fixed for the life of the player. Upstream keeps it in
    /// the immutable config anyway, which meant that following a connection as
    /// it changed cost a whole new session and a second of silence. What is
    /// playing keeps the file it started with; the next track gets this.
    pub fn set_bitrate(&self, bitrate: Bitrate) {
        self.command(PlayerCommand::SetBitrate(bitrate));
    }

    /// LOCAL PATCH: whether trailing silence triggers early crossfade.
    pub fn set_trim_silence(&self, enabled: bool) {
        self.command(PlayerCommand::SetTrimSilence(enabled));
    }

    /// LOCAL PATCH: see PlayerConfig::hold_end.
    pub fn set_hold_end(&self, enabled: bool) {
        self.command(PlayerCommand::SetHoldEnd(enabled));
    }

    /// LOCAL PATCH: see [MixPlan]. None goes back to the ordinary crossfade.
    pub fn set_mix_plan(&self, plan: Option<MixPlan>) {
        self.command(PlayerCommand::SetMixPlan(plan));
    }

    /// LOCAL PATCH: see PlayerConfig::skip_fade_ms.
    pub fn set_skip_fade(&self, ms: u32) {
        self.command(PlayerCommand::SetSkipFade(ms));
    }

    pub fn emit_filter_explicit_content_changed_event(&self, filter: bool) {
        self.command(PlayerCommand::EmitFilterExplicitContentChangedEvent(filter));
    }

    pub fn emit_session_connected_event(&self, connection_id: String, user_name: String) {
        self.command(PlayerCommand::EmitSessionConnectedEvent {
            connection_id,
            user_name,
        });
    }

    pub fn emit_session_disconnected_event(&self, connection_id: String, user_name: String) {
        self.command(PlayerCommand::EmitSessionDisconnectedEvent {
            connection_id,
            user_name,
        });
    }

    pub fn emit_session_client_changed_event(
        &self,
        client_id: String,
        client_name: String,
        client_brand_name: String,
        client_model_name: String,
    ) {
        self.command(PlayerCommand::EmitSessionClientChangedEvent {
            client_id,
            client_name,
            client_brand_name,
            client_model_name,
        });
    }

    pub fn emit_shuffle_changed_event(&self, shuffle: bool) {
        self.command(PlayerCommand::EmitShuffleChangedEvent(shuffle));
    }

    pub fn emit_repeat_changed_event(&self, context: bool, track: bool) {
        self.command(PlayerCommand::EmitRepeatChangedEvent { context, track });
    }

    pub fn emit_auto_play_changed_event(&self, auto_play: bool) {
        self.command(PlayerCommand::EmitAutoPlayChangedEvent(auto_play));
    }
}

impl Drop for Player {
    fn drop(&mut self) {
        debug!("Shutting down player thread ...");
        self.commands = None;
        if let Some(handle) = self.thread_handle.take() {
            if let Err(e) = handle.join() {
                error!("Player thread Error: {e:?}");
            }
        }
    }
}

struct PlayerLoadedTrackData {
    decoder: Decoder,
    normalisation_data: NormalisationData,
    stream_loader_controller: StreamLoaderController,
    audio_item: AudioItem,
    bytes_per_second: usize,
    duration_ms: u32,
    stream_position_ms: u32,
    is_explicit: bool,
}

enum PlayerPreload {
    None,
    Loading {
        track_id: SpotifyUri,
        loader: Pin<Box<dyn FusedFuture<Output = Result<PlayerLoadedTrackData, ()>> + Send>>,
    },
    Ready {
        track_id: SpotifyUri,
        loaded_track: Box<PlayerLoadedTrackData>,
    },
}

type Decoder = Box<dyn AudioDecoder + Send>;

enum PlayerState {
    Stopped,
    Loading {
        track_id: SpotifyUri,
        play_request_id: u64,
        start_playback: bool,
        loader: Pin<Box<dyn FusedFuture<Output = Result<PlayerLoadedTrackData, ()>> + Send>>,
    },
    Paused {
        track_id: SpotifyUri,
        play_request_id: u64,
        decoder: Decoder,
        audio_item: AudioItem,
        normalisation_data: NormalisationData,
        normalisation_factor: f64,
        stream_loader_controller: StreamLoaderController,
        bytes_per_second: usize,
        duration_ms: u32,
        stream_position_ms: u32,
        suggested_to_preload_next_track: bool,
        is_explicit: bool,
    },
    Playing {
        track_id: SpotifyUri,
        play_request_id: u64,
        decoder: Decoder,
        normalisation_data: NormalisationData,
        audio_item: AudioItem,
        normalisation_factor: f64,
        stream_loader_controller: StreamLoaderController,
        bytes_per_second: usize,
        duration_ms: u32,
        stream_position_ms: u32,
        reported_nominal_start_time: Option<Instant>,
        suggested_to_preload_next_track: bool,
        is_explicit: bool,
    },
    EndOfTrack {
        track_id: SpotifyUri,
        play_request_id: u64,
        loaded_track: PlayerLoadedTrackData,
    },
    Invalid,
}

impl PlayerState {
    /// LOCAL PATCH: where the track had got to, for reloading it after a
    /// failure. Zero when nothing is loaded, which is the right answer for a
    /// reload that will start from the beginning anyway.
    /// LOCAL PATCH: what is playing, where it is, and how long it is.
    /// LOCAL PATCH: which play request this state belongs to, if any.
    fn play_request_id(&self) -> Option<u64> {
        use self::PlayerState::*;
        match *self {
            Loading {
                play_request_id, ..
            }
            | Paused {
                play_request_id, ..
            }
            | Playing {
                play_request_id, ..
            }
            | EndOfTrack {
                play_request_id, ..
            } => Some(play_request_id),
            Stopped | Invalid => None,
        }
    }

    fn playing_progress(&self) -> Option<(SpotifyUri, u64, u32, u32)> {
        match *self {
            PlayerState::Playing {
                ref track_id,
                play_request_id,
                stream_position_ms,
                duration_ms,
                ..
            } => Some((
                track_id.clone(),
                play_request_id,
                stream_position_ms,
                duration_ms,
            )),
            _ => None,
        }
    }

    fn stream_position_ms(&self) -> u32 {
        use self::PlayerState::*;
        match *self {
            Playing {
                stream_position_ms, ..
            }
            | Paused {
                stream_position_ms, ..
            } => stream_position_ms,
            _ => 0,
        }
    }

    fn is_playing(&self) -> bool {
        use self::PlayerState::*;
        match *self {
            Stopped | EndOfTrack { .. } | Paused { .. } | Loading { .. } => false,
            Playing { .. } => true,
            Invalid => {
                error!("PlayerState::is_playing in invalid state");
                exit(1);
            }
        }
    }

    #[allow(dead_code)]
    fn is_stopped(&self) -> bool {
        use self::PlayerState::*;
        matches!(self, Stopped)
    }

    #[allow(dead_code)]
    fn is_loading(&self) -> bool {
        use self::PlayerState::*;
        matches!(self, Loading { .. })
    }

    fn decoder(&mut self) -> Option<&mut Decoder> {
        use self::PlayerState::*;
        match *self {
            Stopped | EndOfTrack { .. } | Loading { .. } => None,
            Paused {
                ref mut decoder, ..
            }
            | Playing {
                ref mut decoder, ..
            } => Some(decoder),
            Invalid => {
                error!("PlayerState::decoder in invalid state");
                exit(1);
            }
        }
    }

    fn playing_to_end_of_track(&mut self) {
        use self::PlayerState::*;
        let new_state = mem::replace(self, Invalid);
        match new_state {
            Playing {
                track_id,
                play_request_id,
                decoder,
                duration_ms,
                bytes_per_second,
                normalisation_data,
                stream_loader_controller,
                stream_position_ms,
                is_explicit,
                audio_item,
                ..
            } => {
                *self = EndOfTrack {
                    track_id,
                    play_request_id,
                    loaded_track: PlayerLoadedTrackData {
                        decoder,
                        normalisation_data,
                        stream_loader_controller,
                        audio_item,
                        bytes_per_second,
                        duration_ms,
                        stream_position_ms,
                        is_explicit,
                    },
                };
            }
            _ => {
                error!("Called playing_to_end_of_track in non-playing state: {new_state:?}");
                exit(1);
            }
        }
    }

    fn paused_to_playing(&mut self) {
        use self::PlayerState::*;
        let new_state = mem::replace(self, Invalid);
        match new_state {
            Paused {
                track_id,
                play_request_id,
                decoder,
                audio_item,
                normalisation_data,
                normalisation_factor,
                stream_loader_controller,
                duration_ms,
                bytes_per_second,
                stream_position_ms,
                suggested_to_preload_next_track,
                is_explicit,
            } => {
                *self = Playing {
                    track_id,
                    play_request_id,
                    decoder,
                    audio_item,
                    normalisation_data,
                    normalisation_factor,
                    stream_loader_controller,
                    duration_ms,
                    bytes_per_second,
                    stream_position_ms,
                    reported_nominal_start_time: Instant::now()
                        .checked_sub(Duration::from_millis(stream_position_ms as u64)),
                    suggested_to_preload_next_track,
                    is_explicit,
                };
            }
            _ => {
                error!("PlayerState::paused_to_playing in invalid state: {new_state:?}");
                exit(1);
            }
        }
    }

    fn playing_to_paused(&mut self) {
        use self::PlayerState::*;
        let new_state = mem::replace(self, Invalid);
        match new_state {
            Playing {
                track_id,
                play_request_id,
                decoder,
                audio_item,
                normalisation_data,
                normalisation_factor,
                stream_loader_controller,
                duration_ms,
                bytes_per_second,
                stream_position_ms,
                suggested_to_preload_next_track,
                is_explicit,
                ..
            } => {
                *self = Paused {
                    track_id,
                    play_request_id,
                    decoder,
                    audio_item,
                    normalisation_data,
                    normalisation_factor,
                    stream_loader_controller,
                    duration_ms,
                    bytes_per_second,
                    stream_position_ms,
                    suggested_to_preload_next_track,
                    is_explicit,
                };
            }
            _ => {
                error!("PlayerState::playing_to_paused in invalid state: {new_state:?}");
                exit(1);
            }
        }
    }
}

struct PlayerTrackLoader {
    session: Session,
    config: PlayerConfig,
    local_file_lookup: Arc<LocalFileLookup>,
}

impl PlayerTrackLoader {
    async fn find_available_alternative(&self, audio_item: AudioItem) -> Option<AudioItem> {
        if let Err(e) = audio_item.availability {
            error!("Track is unavailable: {e}");
            None
        } else if !audio_item.files.is_empty() {
            Some(audio_item)
        } else if let Some(alternatives) = audio_item.alternatives {
            let Tracks(alternatives_vec) = alternatives; // required to make `into_iter` able to move

            let alternatives: FuturesUnordered<_> = alternatives_vec
                .into_iter()
                .map(|alt_id| AudioItem::get_file(&self.session, alt_id))
                .collect();

            alternatives
                .filter_map(|x| future::ready(x.ok()))
                .filter(|x| future::ready(x.availability.is_ok()))
                .next()
                .await
        } else {
            error!("Track should be available, but no alternatives found.");
            None
        }
    }

    fn stream_data_rate(&self, format: AudioFileFormat) -> Option<usize> {
        let kbps = match format {
            AudioFileFormat::OGG_VORBIS_96 => 12.,
            AudioFileFormat::OGG_VORBIS_160 => 20.,
            AudioFileFormat::OGG_VORBIS_320 => 40.,
            AudioFileFormat::MP3_256 => 32.,
            AudioFileFormat::MP3_320 => 40.,
            AudioFileFormat::MP3_160 => 20.,
            AudioFileFormat::MP3_96 => 12.,
            AudioFileFormat::MP3_160_ENC => 20.,
            AudioFileFormat::AAC_24 => 3.,
            AudioFileFormat::AAC_48 => 6.,
            AudioFileFormat::AAC_160 => 20.,
            AudioFileFormat::AAC_320 => 40.,
            AudioFileFormat::MP4_128 => 16.,
            AudioFileFormat::OTHER5 => 40.,
            AudioFileFormat::FLAC_FLAC => 112., // assume 900 kbit/s on average
            AudioFileFormat::XHE_AAC_12 => 1.5,
            AudioFileFormat::XHE_AAC_16 => 2.,
            AudioFileFormat::XHE_AAC_24 => 3.,
            AudioFileFormat::FLAC_FLAC_24BIT => 3.,
        };
        let data_rate: f32 = kbps * 1024.;
        Some(data_rate.ceil() as usize)
    }

    async fn load_track(
        &self,
        track_uri: SpotifyUri,
        position_ms: u32,
    ) -> Option<PlayerLoadedTrackData> {
        match track_uri {
            SpotifyUri::Track { .. } | SpotifyUri::Episode { .. } => {
                // LOCAL PATCH: a downloaded track is played from disk.
                //
                // Before anything else, because the point of the branch is that
                // it touches nothing: no metadata request, no storage resolve,
                // no audio key, no CDN. That is what makes a downloaded track
                // start instantly on a bad connection and play at all on none.
                //
                // A failure here falls through to the network rather than
                // failing the load. The file could have been removed between
                // the lookup and the open, or be a truncated leftover from a
                // crash mid-write; either way the track is still playable the
                // ordinary way, and the alternative is a song that refuses to
                // play because of a housekeeping problem the listener cannot
                // see.
                if let Some(loaded) = self.load_downloaded_track(&track_uri, position_ms) {
                    return Some(loaded);
                }
                // LOCAL PATCH: offline, there is no second chance.
                //
                // Streaming this would be the app quietly using the network the
                // listener asked it not to use — on a metered connection, or on
                // none, where it fails after a wait instead. A track with no
                // file simply does not load, and the queue was built out of the
                // ones that have one.
                if self
                    .config
                    .downloads_only
                    .as_ref()
                    .map(|only| only())
                    .unwrap_or(false)
                {
                    warn!("<{track_uri}> is not downloaded and this player is offline");
                    return None;
                }
                self.load_remote_track(track_uri, position_ms).await
            }
            SpotifyUri::Local { .. } => self.load_local_track(track_uri, position_ms).await,
            _ => {
                error!("Cannot handle load of track with URI: <{track_uri}>",);
                None
            }
        }
    }

    /// LOCAL PATCH: loads a track from the copy the engine has downloaded.
    ///
    /// Deliberately not `async`: there is nothing here to await. Every step is
    /// a local file operation, which is the whole reason this path exists.
    ///
    /// Below the first few lines it is the streaming path, unchanged — and it
    /// is unchanged on purpose. The downloaded file is the file the CDN served,
    /// still encrypted, so the same `AudioDecrypt` runs over it, the Ogg header
    /// still ends at the same offset, and the normalisation packet is still
    /// read out of the same place. Anything that behaved differently when a
    /// track is downloaded would be a bug the listener hears.
    ///
    /// Returns `None` when there is no download for this track — the ordinary
    /// answer — and also when there is one that cannot be read, so the caller
    /// falls back to the network.
    fn load_downloaded_track(
        &self,
        track_uri: &SpotifyUri,
        position_ms: u32,
    ) -> Option<PlayerLoadedTrackData> {
        let lookup = self.config.download_lookup.as_ref()?;
        let track_id: SpotifyId = track_uri.try_into().ok()?;
        let downloaded = lookup(&track_id)?;

        let began = Instant::now();

        let file = match File::open(&downloaded.path) {
            Ok(file) => file,
            Err(e) => {
                warn!(
                    "download for <{}> could not be opened, fetching it instead: {e}",
                    downloaded.name
                );
                return None;
            }
        };
        let file_size = match file.metadata() {
            Ok(meta) => meta.len(),
            Err(e) => {
                warn!("download for <{}> has no size: {e}", downloaded.name);
                return None;
            }
        };

        let key = downloaded.key.map(librespot_core::audio_key::AudioKey);
        let mut decrypted_file = AudioDecrypt::new(key, file);

        let is_ogg_vorbis = AudioFiles::is_ogg_vorbis(downloaded.format);
        let (offset, mut normalisation_data) = if is_ogg_vorbis {
            let normalisation_data = NormalisationData::parse_from_ogg(&mut decrypted_file).ok();
            (SPOTIFY_OGG_HEADER_END, normalisation_data)
        } else {
            (0, None)
        };

        let audio_file = match Subfile::new(decrypted_file, offset, file_size) {
            Ok(audio_file) => audio_file,
            Err(e) => {
                warn!("download for <{}> is too short to play: {e}", downloaded.name);
                return None;
            }
        };

        let mut hint = Hint::new();
        if let Some(mime_type) = AudioFiles::mime_type(downloaded.format) {
            hint.mime_type(mime_type);
        }

        let mut decoder: Decoder = match SymphoniaDecoder::new(audio_file, hint) {
            Ok(mut decoder) => {
                // Same as the streaming path: outside Ogg Vorbis the loudness
                // comes from ReplayGain tags rather than Spotify's own packet.
                if normalisation_data.is_none() {
                    normalisation_data = decoder.normalisation_data();
                }
                Box::new(decoder)
            }
            Err(e) => {
                // A file that will not decode is a broken download, not a
                // broken track. Say so and let the caller stream it.
                warn!(
                    "download for <{}> will not decode, fetching it instead: {e}",
                    downloaded.name
                );
                return None;
            }
        };

        let duration_ms = downloaded.duration_ms;
        let position_ms = if position_ms > duration_ms {
            warn!(
                "Invalid start position of {position_ms} ms exceeds track's duration of {duration_ms} ms, starting track from the beginning"
            );
            0
        } else {
            position_ms
        };

        // Unlike the streaming path this seek is cheap — symphonia's bisection
        // reads from disk, not from the CDN — but it is still skipped at the
        // start of a track, where a fresh decoder already sits on the first
        // audio packet.
        let stream_position_ms = if position_ms == 0 {
            0
        } else {
            match decoder.seek(position_ms) {
                Ok(new_position_ms) => new_position_ms,
                Err(e) => {
                    error!(
                        "PlayerTrackLoader::load_downloaded_track error seeking to starting position {position_ms}: {e}"
                    );
                    return None;
                }
            }
        };

        // Only used to pace the fetcher, which has nothing to fetch here. Kept
        // honest anyway because the sink reads it, and guarded because a
        // sub-second track would divide by zero.
        let bytes_per_second = if duration_ms > 0 {
            (file_size as u128 * 1000 / duration_ms as u128) as usize
        } else {
            file_size as usize
        };

        info!(
            "<{}> ({} ms) loaded in {} ms, from a download",
            downloaded.name,
            duration_ms,
            began.elapsed().as_millis(),
        );

        Some(PlayerLoadedTrackData {
            decoder,
            normalisation_data: normalisation_data.unwrap_or_else(|| {
                warn!("Unable to get normalisation data, continuing with defaults.");
                NormalisationData::default()
            }),
            stream_loader_controller: StreamLoaderController::from_local_file(file_size),
            bytes_per_second,
            duration_ms,
            stream_position_ms,
            is_explicit: downloaded.is_explicit,
            audio_item: AudioItem {
                duration_ms,
                uri: track_uri.to_uri().unwrap_or_default(),
                track_id: track_uri.clone(),
                // Empty because this item is never fetched: naming the files
                // the track exists in would describe what is on the CDN, not
                // what is being played.
                files: Default::default(),
                name: downloaded.name,
                covers: vec![],
                language: vec![],
                is_explicit: downloaded.is_explicit,
                availability: Ok(()),
                alternatives: None,
                unique_fields: UniqueFields::Track {
                    // Names only, and the roles are not kept: the app draws its
                    // track lists from its own catalogue rather than from the
                    // player, and the one field anything downstream reads out
                    // of an `AudioItem` is the duration.
                    artists: Default::default(),
                    album: downloaded.album,
                    album_artists: downloaded.album_artists,
                    popularity: 0,
                    number: downloaded.number,
                    disc_number: downloaded.disc_number,
                },
            },
        })
    }

    async fn load_remote_track(
        &self,
        track_uri: SpotifyUri,
        position_ms: u32,
    ) -> Option<PlayerLoadedTrackData> {
        let track_id: SpotifyId = match (&track_uri).try_into() {
            Ok(id) => id,
            Err(_) => {
                warn!("<{track_uri}> could not be converted to a base62 ID");
                return None;
            }
        };

        let began = Instant::now();
        let audio_item = match AudioItem::get_file(&self.session, track_uri).await {
            Ok(audio) => match self.find_available_alternative(audio).await {
                Some(audio) => audio,
                None => {
                    warn!(
                        "spotify:track:<{}> is not available",
                        track_id.to_base62().unwrap_or_default()
                    );
                    return None;
                }
            },
            Err(e) => {
                error!("Unable to load audio item: {e:?}");
                return None;
            }
        };

        info!(
            "Loading <{}> with Spotify URI <{}>",
            audio_item.name, audio_item.uri
        );
        // LOCAL PATCH: where the wait before a song starts actually goes.
        let after_metadata = began.elapsed();

        // (Most) podcasts seem to support only 96 kbps Ogg Vorbis, so fall back to it
        let formats = match self.config.bitrate {
            Bitrate::Bitrate96 => [
                AudioFileFormat::OGG_VORBIS_96,
                AudioFileFormat::MP3_96,
                AudioFileFormat::OGG_VORBIS_160,
                AudioFileFormat::MP3_160,
                AudioFileFormat::MP3_256,
                AudioFileFormat::OGG_VORBIS_320,
                AudioFileFormat::MP3_320,
            ],
            Bitrate::Bitrate160 => [
                AudioFileFormat::OGG_VORBIS_160,
                AudioFileFormat::MP3_160,
                AudioFileFormat::OGG_VORBIS_96,
                AudioFileFormat::MP3_96,
                AudioFileFormat::MP3_256,
                AudioFileFormat::OGG_VORBIS_320,
                AudioFileFormat::MP3_320,
            ],
            Bitrate::Bitrate320 => [
                AudioFileFormat::OGG_VORBIS_320,
                AudioFileFormat::MP3_320,
                AudioFileFormat::MP3_256,
                AudioFileFormat::OGG_VORBIS_160,
                AudioFileFormat::MP3_160,
                AudioFileFormat::OGG_VORBIS_96,
                AudioFileFormat::MP3_96,
            ],
        };

        let (format, file_id) =
            match formats
                .iter()
                .find_map(|format| match audio_item.files.get(format) {
                    Some(&file_id) => Some((*format, file_id)),
                    _ => None,
                }) {
                Some(t) => t,
                None => {
                    warn!(
                        "<{}> is not available in any supported format",
                        audio_item.name
                    );
                    return None;
                }
            };

        // LOCAL PATCH: says which file is actually being streamed.
        //
        // The bitrate setting picks an order of preference, not a file: what
        // arrives depends on what the track is offered in, and a track already
        // in the cache is played from disk whatever the setting now says. With
        // nothing in the log naming the format, "the quality setting does
        // nothing" could not be told apart from "this track only exists at
        // that quality" or "you have heard this one before".
        info!("<{}> streaming as {:?}", audio_item.name, format);

        let bytes_per_second = self.stream_data_rate(format)?;

        // This is only a loop to be able to reload the file if an error occurred
        // while opening a cached file.
        loop {
            let encrypted_file = AudioFile::open(&self.session, file_id, bytes_per_second);

            let encrypted_file = match encrypted_file.await {
                Ok(encrypted_file) => encrypted_file,
                Err(e) => {
                    error!("Unable to load encrypted file: {e:?}");
                    return None;
                }
            };

            let is_cached = encrypted_file.is_cached();
            let after_open = began.elapsed();

            let stream_loader_controller = encrypted_file.get_stream_loader_controller().ok()?;

            // Not all audio files are encrypted. If we can't get a key, try loading the track
            // without decryption. If the file was encrypted after all, the decoder will fail
            // parsing and bail out, so we should be safe from outputting ear-piercing noise.
            //
            // LOCAL PATCH: a refused key ends the load instead.
            //
            // Spotify refuses keys when it is throttling a session, and the
            // refusal says nothing about the track. Carrying on without one
            // means handing the decoder an encrypted file: it dies on the first
            // frame, the track "ends" in half a second, and the engine moves to
            // the next one — which is refused too. The listener sees the whole
            // queue flick past in silence, with nothing in the log but a
            // decoder complaining about the end of the stream.
            //
            // Failing the load here puts it on the retry path instead (see
            // MAX_LOAD_ATTEMPTS above), which waits and tries again, and says
            // so plainly if it still cannot. Only a refusal or a timeout is
            // treated this way; any other key failure keeps upstream's
            // behaviour, since a file that is genuinely unencrypted has to go
            // on playing.
            // LOCAL PATCH: said before asking, so a download queue running
            // alongside knows to keep out of the way. Audio keys are limited
            // per session, and a queue spending that allowance is a queue
            // stopping the music from starting; see `downloads.rs`.
            librespot_core::audio_key::note_playback_request();
            let key = match self.session.audio_key().request(track_id, file_id).await {
                Ok(key) => Some(key),
                Err(e) => {
                    // A key that never came because the session went away
                    // counts too: the connection dropping mid-request answers
                    // "channel closed", and the file is no less encrypted for
                    // it. Played anyway, it was a decoder error and a skip.
                    let refused = matches!(
                        e.error.downcast_ref::<librespot_core::audio_key::AudioKeyError>(),
                        Some(librespot_core::audio_key::AudioKeyError::AesKey)
                            | Some(librespot_core::audio_key::AudioKeyError::Timeout)
                    ) || self.session.is_invalid();
                    if refused {
                        warn!("no key for <{track_id:?}>, not playing it undecrypted: {e}");
                        return None;
                    }
                    warn!("Unable to load key, continuing without decryption: {e}");
                    None
                }
            };

            let after_key = began.elapsed();
            let mut decrypted_file = AudioDecrypt::new(key, encrypted_file);

            let is_ogg_vorbis = AudioFiles::is_ogg_vorbis(format);
            let (offset, mut normalisation_data) = if is_ogg_vorbis {
                // Spotify stores normalisation data in a custom Ogg packet instead of Vorbis comments.
                let normalisation_data =
                    NormalisationData::parse_from_ogg(&mut decrypted_file).ok();
                (SPOTIFY_OGG_HEADER_END, normalisation_data)
            } else {
                (0, None)
            };

            let audio_file = match Subfile::new(
                decrypted_file,
                offset,
                stream_loader_controller.len() as u64,
            ) {
                Ok(audio_file) => audio_file,
                Err(e) => {
                    error!("PlayerTrackLoader::load_track error opening subfile: {e}");
                    return None;
                }
            };

            let mut symphonia_decoder = |audio_file, format| {
                SymphoniaDecoder::new(audio_file, format).map(|mut decoder| {
                    // For formats other that Vorbis, we'll try getting normalisation data from
                    // ReplayGain metadata fields, if present.
                    if normalisation_data.is_none() {
                        normalisation_data = decoder.normalisation_data();
                    }
                    Box::new(decoder) as Decoder
                })
            };

            let mut hint = Hint::new();
            if let Some(mime_type) = AudioFiles::mime_type(format) {
                hint.mime_type(mime_type);
            }

            #[cfg(feature = "passthrough-decoder")]
            let decoder_type = if self.config.passthrough {
                PassthroughDecoder::new(audio_file, format).map(|x| Box::new(x) as Decoder)
            } else {
                symphonia_decoder(audio_file, hint)
            };

            #[cfg(not(feature = "passthrough-decoder"))]
            let decoder_type = { symphonia_decoder(audio_file, hint) };

            let normalisation_data = normalisation_data.unwrap_or_else(|| {
                warn!("Unable to get normalisation data, continuing with defaults.");
                NormalisationData::default()
            });

            let mut decoder = match decoder_type {
                Ok(decoder) => decoder,
                Err(e) if is_cached => {
                    warn!("Unable to read cached audio file: {e}. Trying to download it.");

                    match self.session.cache() {
                        Some(cache) => {
                            if cache.remove_file(file_id).is_err() {
                                error!("Error removing file from cache");
                                return None;
                            }
                        }
                        None => {
                            error!("If the audio file is cached, a cache should exist");
                            return None;
                        }
                    }

                    // Just try it again
                    continue;
                }
                Err(e) => {
                    error!("Unable to read audio file: {e}");
                    return None;
                }
            };

            let duration_ms = audio_item.duration_ms;
            // Don't try to seek past the track's duration.
            // If the position is invalid just start from
            // the beginning of the track.
            let position_ms = if position_ms > duration_ms {
                warn!(
                    "Invalid start position of {position_ms} ms exceeds track's duration of {duration_ms} ms, starting track from the beginning"
                );
                0
            } else {
                position_ms
            };

            // Ensure the starting position. Even when we want to play from the beginning,
            // the cursor may have been moved by parsing normalisation data. This may not
            // matter for playback (but won't hurt either), but may be useful for the
            // passthrough decoder.
            // LOCAL PATCH: a track that starts at the beginning is already there.
            //
            // Upstream seeks unconditionally, and the note above says why: the
            // cursor may have moved while the normalisation packet was read.
            // That read happens on the stream *before* the decoder is built,
            // and the decoder is built on a fresh view of the file, so a new
            // decoder is at the first audio packet already.
            //
            // What the seek costs is the whole point of this patch. Symphonia
            // is asked for an accurate seek, which on an Ogg stream is a
            // bisection: it reads pages at scattered offsets to find the one
            // holding the target. Over a network file that is not yet
            // downloaded, every one of those reads asks the CDN for a block and
            // waits — measured on this phone at between eight hundred
            // milliseconds and twelve seconds, on every single track, to arrive
            // at a position the decoder was already sitting on.
            let stream_position_ms = if position_ms == 0 {
                0
            } else {
                match decoder.seek(position_ms) {
                    Ok(new_position_ms) => new_position_ms,
                    Err(e) => {
                        error!(
                            "PlayerTrackLoader::load_track error seeking to starting position {position_ms}: {e}"
                        );
                        return None;
                    }
                }
            };

            // Ensure streaming mode now that we are ready to play from the requested position.
            stream_loader_controller.set_stream_mode();

            let is_explicit = audio_item.is_explicit;

            info!(
                "<{}> ({} ms) loaded in {} ms (metadata {} ms, stream {} ms, key {} ms, decode {} ms{})",
                audio_item.name,
                duration_ms,
                began.elapsed().as_millis(),
                after_metadata.as_millis(),
                (after_open - after_metadata).as_millis(),
                (after_key - after_open).as_millis(),
                (began.elapsed() - after_key).as_millis(),
                if is_cached { ", from the cache" } else { "" },
            );


            return Some(PlayerLoadedTrackData {
                decoder,
                normalisation_data,
                stream_loader_controller,
                audio_item,
                bytes_per_second,
                duration_ms,
                stream_position_ms,
                is_explicit,
            });
        }
    }

    async fn load_local_track(
        &self,
        track_uri: SpotifyUri,
        position_ms: u32,
    ) -> Option<PlayerLoadedTrackData> {
        info!("Loading local file with Spotify URI <{}>", track_uri);

        let SpotifyUri::Local { duration, .. } = track_uri else {
            error!("Unable to determine track duration for local file: not a local file URI");
            return None;
        };

        // LOCAL PATCH: the app's matches too; see local_file::set_app_files.
        let entry = self.local_file_lookup.path_for(&track_uri);

        let Some(path) = entry else {
            error!("Unable to find file path for local file <{track_uri}>");
            return None;
        };

        let src = match File::open(&path) {
            Ok(src) => src,
            Err(e) => {
                error!("Failed to open local file: {e}");
                return None;
            }
        };

        let mut hint = Hint::new();
        if let Some(file_extension) = path.extension().and_then(|e| e.to_str()) {
            hint.with_extension(file_extension);
        }

        let decoder = match SymphoniaDecoder::new(src, hint) {
            Ok(decoder) => decoder,
            Err(e) => {
                error!("Error decoding local file: {e}");
                return None;
            }
        };

        let mut decoder = Box::new(decoder);
        // LOCAL PATCH: a file with no ReplayGain tags is measured instead, so
        // it plays at the level of the streamed tracks; see local_file.rs.
        let normalisation_data = match decoder.normalisation_data() {
            Some(data) => data,
            None => {
                let measured_path = path.clone();
                tokio::task::spawn_blocking(move || crate::local_file::loudness(&measured_path))
                    .await
                    .ok()
                    .flatten()
                    .unwrap_or_else(|| {
                        warn!("Unable to get normalisation data, continuing with defaults.");
                        NormalisationData::default()
                    })
            }
        };

        let local_file_metadata = decoder.local_file_metadata().unwrap_or_default();

        let stream_position_ms = match decoder.seek(position_ms) {
            Ok(new_position_ms) => new_position_ms,
            Err(e) => {
                error!(
                    "PlayerTrackLoader::load_local_track error seeking to starting position {position_ms}: {e}"
                );
                return None;
            }
        };

        let file_size = fs::metadata(&path).ok()?.len();
        let bytes_per_second = (file_size / duration.as_secs()) as usize;

        let stream_loader_controller = StreamLoaderController::from_local_file(file_size);

        let name = local_file_metadata.name.unwrap_or_default();

        info!("Loaded <{name}> from path <{}>", path.display());

        Some(PlayerLoadedTrackData {
            decoder,
            normalisation_data,
            stream_loader_controller,
            bytes_per_second,
            duration_ms: duration.as_millis() as u32,
            stream_position_ms,
            is_explicit: false,
            audio_item: AudioItem {
                duration_ms: duration.as_millis() as u32,
                uri: track_uri.to_uri().unwrap_or_default(),
                track_id: track_uri,
                files: Default::default(),
                name,
                // We can't get a CoverImage.URL for the track image, applications will have to parse the file metadata themselves using unique_fields.path
                covers: vec![],
                language: local_file_metadata
                    .language
                    .map(|val| vec![val])
                    .unwrap_or_default(),
                is_explicit: false,
                availability: Ok(()),
                alternatives: None,
                unique_fields: UniqueFields::Local {
                    artists: local_file_metadata.artists,
                    album: local_file_metadata.album,
                    album_artists: local_file_metadata.album_artists,
                    number: local_file_metadata.number,
                    disc_number: local_file_metadata.disc_number,
                    path: path.to_path_buf(),
                },
            },
        })
    }
}

impl Future for PlayerInternal {
    type Output = ();

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        // While this is written as a future, it still contains blocking code.
        // It must be run on its own thread.
        let passthrough = self.config.passthrough;

        loop {
            let mut all_futures_completed_or_not_ready = true;

            // process commands that were sent to us
            let cmd = match self.commands.poll_recv(cx) {
                Poll::Ready(None) => return Poll::Ready(()), // client has disconnected - shut down.
                Poll::Ready(Some(cmd)) => {
                    all_futures_completed_or_not_ready = false;
                    Some(cmd)
                }
                _ => None,
            };

            if let Some(cmd) = cmd {
                if let Err(e) = self.handle_command(cmd) {
                    error!("Error handling command: {e}");
                }
            }

            // Handle loading of a new track to play
            if let PlayerState::Loading {
                ref mut loader,
                ref track_id,
                start_playback,
                play_request_id,
            } = self.state
            {
                // The loader may be terminated if we are trying to load the same track
                // as before, and that track failed to open before.
                let track_id = track_id.clone();

                if !loader.as_mut().is_terminated() {
                    match loader.as_mut().poll(cx) {
                        Poll::Ready(Ok(loaded_track)) => {
                            self.start_playback(
                                track_id,
                                play_request_id,
                                loaded_track,
                                start_playback,
                            );
                            if let PlayerState::Loading { .. } = self.state {
                                error!("The state wasn't changed by start_playback()");
                                exit(1);
                            }
                        }
                        Poll::Ready(Err(e)) => {
                            // LOCAL PATCH: try again before declaring the track
                            // gone.
                            //
                            // Upstream treats one failed load as "this track
                            // cannot be played" and Spirc answers that by
                            // skipping to the next one. On a bad connection
                            // every track fails, so the queue ran itself out in
                            // a few seconds, one skip per song, and nothing
                            // played at all — and each failure also marks the
                            // track unavailable for the rest of the session, so
                            // songs kept being skipped long after the signal
                            // came back. A slow network should mean the music
                            // takes longer to start, not that the queue empties.
                            if self.load_attempt < MAX_LOAD_ATTEMPTS {
                                let backoff = LOAD_RETRY_BACKOFF * (1 << self.load_attempt);
                                self.load_attempt += 1;
                                warn!(
                                    "retrying load of <{track_id:?}> in {backoff:?}, attempt {} of {MAX_LOAD_ATTEMPTS}: {e:?}",
                                    self.load_attempt + 1,
                                );
                                // Says it is still working on this track rather
                                // than leaving the listener at a dead screen.
                                let position_ms = self.load_position_ms;
                                self.send_event(PlayerEvent::Loading {
                                    track_id: track_id.clone(),
                                    play_request_id,
                                    position_ms,
                                });
                                let again = self.load_track(track_id.clone(), position_ms);
                                let loader = Box::pin(
                                    async move {
                                        tokio::time::sleep(backoff).await;
                                        again.await
                                    }
                                    .fuse(),
                                );
                                self.state = PlayerState::Loading {
                                    track_id,
                                    play_request_id,
                                    start_playback,
                                    loader,
                                };
                            } else {
                                error!(
                                    "Skipping to next track, unable to load track <{track_id:?}>: {e:?}"
                                );
                                self.send_event(PlayerEvent::Unavailable {
                                    track_id,
                                    play_request_id,
                                })
                            }
                        }
                        Poll::Pending => (),
                    }
                }
            }

            // handle pending preload requests.
            if let PlayerPreload::Loading {
                ref mut loader,
                ref track_id,
            } = self.preload
            {
                let track_id = track_id.clone();
                match loader.as_mut().poll(cx) {
                    Poll::Ready(Ok(loaded_track)) => {
                        self.send_event(PlayerEvent::Preloading {
                            track_id: track_id.clone(),
                        });
                        self.preload = PlayerPreload::Ready {
                            track_id,
                            loaded_track: Box::new(loaded_track),
                        };
                    }
                    Poll::Ready(Err(_)) => {
                        // LOCAL PATCH: a preload that failed is not a track
                        // that cannot be played.
                        //
                        // Upstream tells Spirc the track is unavailable, and
                        // Spirc answers by taking it out of the queue. But this
                        // is the *next* track being fetched early, while the
                        // current one is still playing and the connection is
                        // busy carrying it: on a weak link the head start is
                        // the first thing to fail, and songs were disappearing
                        // from the queue before anyone had tried to play them.
                        // Forgetting the head start is enough. The track is
                        // loaded normally when it is reached, with the retries
                        // that path has.
                        warn!("could not preload {track_id:?}, leaving it for its turn");
                        self.preload = PlayerPreload::None;
                    }
                    Poll::Pending => (),
                }
            }

            // LOCAL PATCH: the outgoing track keeps sounding while the one it
            // is dissolving into is still being loaded.
            //
            // `apply_fade` mixes the tail into the incoming track's own
            // packets, so it can only run once that track is producing audio.
            // Between the load starting and the first packet arriving there is
            // nothing to mix into, and the fade fell silent there — which is a
            // cut, not a dissolve. Online it was brief enough to pass; offline,
            // where this side loads the next track itself, it was the whole of
            // what a crossfade sounded like.
            //
            // `Loading` only, and only a load meant to play: a fade is the
            // sound of one song ending under another, and a load that will sit
            // paused is not that.
            if self.fade_out.is_some()
                && matches!(
                    self.state,
                    PlayerState::Loading {
                        start_playback: true,
                        ..
                    }
                )
                && self.pump_fade_out()
            {
                // Round again rather than to sleep: the write inside blocks for
                // as long as the audio it just handed over lasts, so this paces
                // itself the way playback does.
                all_futures_completed_or_not_ready = false;
            }

            if self.state.is_playing() {
                self.ensure_sink_running();

                // LOCAL PATCH: the DJ's opening line, before the track's
                // first packet, asked for once per play request.
                let opening = match self.state {
                    PlayerState::Playing {
                        ref track_id,
                        play_request_id,
                        stream_position_ms,
                        ..
                    } if self.narrated_before != Some(play_request_id) => {
                        Some((track_id.clone(), play_request_id, stream_position_ms))
                    }
                    _ => None,
                };
                if let Some((track_id, play_request_id, stream_position_ms)) = opening {
                    {
                        self.narrated_before = Some(play_request_id);
                        if stream_position_ms < NARRATION_START_WINDOW_MS {
                            if let Some(samples) = narration_for(&track_id, NarrationMoment::Before) {
                                self.narration = Some(Narration {
                                    samples,
                                    at: 0,
                                    then_end: false,
                                });
                            }
                        }
                    }
                }

                // LOCAL PATCH: a line being spoken is written instead of the
                // track, a piece per round, so commands are still heard.
                if self.narration.is_some() {
                    self.pump_narration();
                    continue;
                }

                if let PlayerState::Playing {
                    ref track_id,
                    play_request_id,
                    ref mut decoder,
                    normalisation_factor,
                    ref mut stream_position_ms,
                    ref mut reported_nominal_start_time,
                    ..
                } = self.state
                {
                    let track_id = track_id.clone();
                    match decoder.next_packet() {
                        Ok(result) => {
                            if let Some((ref packet_position, ref packet)) = result {
                                let new_stream_position_ms = packet_position.position_ms;
                                let expected_position_ms = std::mem::replace(
                                    &mut *stream_position_ms,
                                    new_stream_position_ms,
                                );

                                if !passthrough {
                                    match packet.samples() {
                                        Ok(_) => {
                                            let new_stream_position = Duration::from_millis(
                                                new_stream_position_ms as u64,
                                            );

                                            let now = Instant::now();

                                            // Only notify if we're skipped some packets *or* we are behind.
                                            // If we're ahead it's probably due to a buffer of the backend
                                            // and we're actually in time.
                                            let notify_about_position =
                                                match *reported_nominal_start_time {
                                                    None => true,
                                                    Some(reported_nominal_start_time) => {
                                                        let mut notify = false;

                                                        if packet_position.skipped {
                                                            if let Some(ahead) = new_stream_position
                                                                .checked_sub(Duration::from_millis(
                                                                    expected_position_ms as u64,
                                                                ))
                                                            {
                                                                notify |=
                                                                    ahead >= Duration::from_secs(1)
                                                            }
                                                        }

                                                        if let Some(lag) = now
                                                            .checked_duration_since(
                                                                reported_nominal_start_time,
                                                            )
                                                        {
                                                            if let Some(lag) =
                                                                lag.checked_sub(new_stream_position)
                                                            {
                                                                notify |=
                                                                    lag >= Duration::from_secs(1)
                                                            }
                                                        }

                                                        notify
                                                    }
                                                };

                                            if notify_about_position {
                                                *reported_nominal_start_time =
                                                    now.checked_sub(new_stream_position);
                                                self.send_event(PlayerEvent::PositionCorrection {
                                                    play_request_id,
                                                    track_id: track_id.clone(),
                                                    position_ms: new_stream_position_ms,
                                                });
                                            }

                                            if let Some(interval) =
                                                self.config.position_update_interval
                                            {
                                                let last_progress_update_since_ms =
                                                    now.duration_since(self.last_progress_update);

                                                if last_progress_update_since_ms > interval {
                                                    self.last_progress_update = now;
                                                    self.send_event(PlayerEvent::PositionChanged {
                                                        play_request_id,
                                                        track_id,
                                                        position_ms: new_stream_position_ms,
                                                    });
                                                }
                                            }
                                        }
                                        Err(e) => {
                                            // LOCAL PATCH: a failure is not the
                                            // end of the song; see reload_track.
                                            error!(
                                                "unable to decode samples for track <{track_id:?}>: {e:?}"
                                            );
                                            self.reload_track(
                                                track_id,
                                                play_request_id,
                                                new_stream_position_ms,
                                            );
                                        }
                                    }
                                }
                            }

                            self.handle_packet(result, normalisation_factor);
                        }
                        Err(e) => {
                            // LOCAL PATCH: a failure is not the end of the
                            // song; see reload_track.
                            error!("unable to get next packet for track <{track_id:?}>: {e:?}");
                            let position_ms = self.state.stream_position_ms();
                            self.reload_track(track_id, play_request_id, position_ms);
                        }
                    }
                } else {
                    error!("PlayerInternal poll: Invalid PlayerState");
                    exit(1);
                };
            }

            if let PlayerState::Playing {
                ref track_id,
                play_request_id,
                duration_ms,
                stream_position_ms,
                ref mut stream_loader_controller,
                ref mut suggested_to_preload_next_track,
                ..
            }
            | PlayerState::Paused {
                ref track_id,
                play_request_id,
                duration_ms,
                stream_position_ms,
                ref mut stream_loader_controller,
                ref mut suggested_to_preload_next_track,
                ..
            } = self.state
            {
                let track_id = track_id.clone();

                if (!*suggested_to_preload_next_track)
                    && ((duration_ms as i64 - stream_position_ms as i64)
                        < PRELOAD_NEXT_TRACK_BEFORE_END_DURATION_MS as i64)
                    && stream_loader_controller.range_to_end_available()
                {
                    *suggested_to_preload_next_track = true;
                    self.send_event(PlayerEvent::TimeToPreloadNextTrack {
                        track_id: track_id.clone(),
                        play_request_id,
                    });
                }

                // LOCAL PATCH: ask for the next track early, so it is already
                // playing while this one fades out.
                //
                // The end of a track is announced a crossfade's length before
                // it arrives. Whoever owns the queue answers with a load, the
                // usual way, and that load is what starts the fade: the decoder
                // still reading this track is handed to `fade_out` instead of
                // being dropped. Nothing here decides what plays next, which is
                // what keeps the Connect device the only thing that does.
                // LOCAL PATCH: a mixed playlist's transition, where this
                // track has one, decides both when its end is announced and
                // how long the fade into the next lasts — the point the
                // playlist's author chose rather than a fixed distance from
                // the end, and whatever the crossfade setting says.
                let plan = track_id
                    .to_uri()
                    .ok()
                    .and_then(|uri| self.mix_plan.as_ref().filter(|plan| plan.from == uri).cloned());
                let position = stream_position_ms as i64;
                let duration = duration_ms as i64;
                let (crossfade_ms, end_at) = match &plan {
                    Some(plan) => (plan.fade_ms as i64, plan.out_ms as i64),
                    None => {
                        let crossfade_ms = self.config.crossfade_duration_ms as i64;
                        (crossfade_ms, duration - crossfade_ms)
                    }
                };
                if crossfade_ms > 0 && duration > crossfade_ms && end_at > 0 && !self.config.hold_end && !narration_follows(&track_id) {
                    let silence_threshold_samples = (SAMPLE_RATE as usize * NUM_CHANNELS as usize * 350) / 1000;
                    let trailing_silence = plan.is_none()
                        && self.config.trim_silence
                        && self.consecutive_silent_samples >= silence_threshold_samples
                        && position >= duration - crossfade_ms - 2000;

                    if position < end_at && !trailing_silence {
                        // LOCAL PATCH: the track has been heard playing outside
                        // its own ending, so its ending means something.
                        //
                        // Both numbers below come from the decoder, and a track
                        // that arrives already inside the fade window is a
                        // track whose numbers cannot be trusted: a duration
                        // read before the stream was open, or a position left
                        // over from the song that just finished. Announcing an
                        // end from those is heard as a song playing for a
                        // second and then being passed over, because whoever
                        // owns the queue is being told — truthfully, as far as
                        // it knows — that the song is over. Armed here, this
                        // can only happen to a track that was playing normally
                        // a moment ago.
                        self.fade_armed = Some(play_request_id);
                    } else if self.early_end != Some(play_request_id)
                        && self.fade_armed == Some(play_request_id)
                        && self.state.is_playing()
                    {
                        if let Some(plan) = &plan {
                            info!(
                                "mix: {position} ms of {duration} ms played, into {} from {} ms over {} ms",
                                plan.to, plan.in_ms, plan.fade_ms,
                            );
                            self.mix_fade_ms = Some(plan.fade_ms);
                        } else if trailing_silence {
                            info!(
                                "silence trimming: {position} ms of {duration} ms played, trailing silence detected, triggering crossfade early for <{track_id:?}>"
                            );
                        } else {
                            info!(
                                "crossfade: {position} ms of {duration} ms played, announcing the end of <{track_id:?}>"
                            );
                        }
                        self.early_end = Some(play_request_id);
                        self.announce_end(track_id, play_request_id);
                    }
                }
            }

            if (!self.state.is_playing()) && all_futures_completed_or_not_ready {
                return Poll::Pending;
            }
        }
    }
}

impl PlayerInternal {
    fn ensure_sink_running(&mut self) {
        if self.sink_status != SinkStatus::Running {
            trace!("== Starting sink ==");
            if let Some(callback) = &mut self.sink_event_callback {
                callback(SinkStatus::Running);
            }
            match self.sink.start() {
                Ok(()) => self.sink_status = SinkStatus::Running,
                Err(e) => {
                    error!("{e}");
                    self.handle_pause();
                }
            }
        }
    }

    fn ensure_sink_stopped(&mut self, temporarily: bool) {
        match self.sink_status {
            SinkStatus::Running => {
                trace!("== Stopping sink ==");
                match self.sink.stop() {
                    Ok(()) => {
                        self.sink_status = if temporarily {
                            SinkStatus::TemporarilyClosed
                        } else {
                            SinkStatus::Closed
                        };
                        if let Some(callback) = &mut self.sink_event_callback {
                            callback(self.sink_status);
                        }
                    }
                    Err(e) => {
                        error!("{e}");
                        exit(1);
                    }
                }
            }
            SinkStatus::TemporarilyClosed => {
                if !temporarily {
                    self.sink_status = SinkStatus::Closed;
                    if let Some(callback) = &mut self.sink_event_callback {
                        callback(SinkStatus::Closed);
                    }
                }
            }
            SinkStatus::Closed => (),
        }
    }

    /// LOCAL PATCH: writes the next piece of the line being spoken, at the
    /// player's volume, dissolving out of a track still fading as music does.
    fn pump_narration(&mut self) {
        let Some(narration) = self.narration.as_mut() else {
            return;
        };
        let end = (narration.at + NARRATION_CHUNK).min(narration.samples.len());
        let mut data = narration.samples[narration.at..end].to_vec();
        narration.at = end;
        let finished = narration.at >= narration.samples.len();
        let then_end = narration.then_end;
        if finished {
            self.narration = None;
        }

        let volume = self.volume_getter.attenuation_factor();
        if volume < 1.0 {
            for sample in data.iter_mut() {
                *sample *= volume;
            }
        }
        if self.fade_out.is_some() {
            self.apply_fade(&mut data);
        }
        SPEAKING.store(true, Ordering::SeqCst);
        let written = self.sink.write(AudioPacket::Samples(data), &mut self.converter);
        SPEAKING.store(false, Ordering::SeqCst);
        if let Err(e) = written {
            error!("{e}");
            self.narration = None;
            self.handle_pause();
            return;
        }

        if finished && then_end {
            self.finish_track();
        }
    }

    /// LOCAL PATCH: how long a crossfade lasts, in interleaved samples.
    fn crossfade_samples(&self) -> usize {
        Self::fade_samples(self.config.crossfade_duration_ms)
    }

    /// LOCAL PATCH: a length in milliseconds as interleaved samples.
    fn fade_samples(ms: u32) -> usize {
        let ms = ms as usize;
        if ms == 0 {
            return 0;
        }
        let samples = ms * SAMPLE_RATE as usize / 1000 * NUM_CHANNELS as usize;
        // Whole frames only: half a frame would swap the channels over for the
        // rest of the fade.
        samples - samples % NUM_CHANNELS as usize
    }

    /// LOCAL PATCH: moves the track being replaced into the outgoing half of a
    /// crossfade, if there is one and crossfading is on.
    fn begin_fade_out(&mut self) {
        // The track that announced its own end fades out over the crossfade.
        //
        // A fade is what the end of a track sounds like, and a skip is not the
        // end of a track: it is a listener saying they have heard enough. Every
        // load arrives here the same way, whoever asked for it, so the two are
        // told apart by `early_end`, which names the one play request that was
        // reported as finishing before it had.
        //
        // Any other track that is playing goes over the shorter fade the
        // listener chose for changing songs themselves, and the incoming one
        // rises on its own clock; see PlayerConfig::skip_fade_ms and
        // FadeOut::rising. A track that is paused is not heard, and nothing
        // fades out of it.
        let expected = self.early_end.take();
        let (total, rising) = match &self.state {
            PlayerState::Playing { play_request_id, .. } if expected == Some(*play_request_id) => {
                match self.mix_fade_ms.take() {
                    Some(ms) => (Self::fade_samples(ms), None),
                    None => (self.crossfade_samples(), None),
                }
            }
            PlayerState::Playing { .. } => (Self::fade_samples(self.config.skip_fade_ms), Some(0)),
            // Nothing playing to fade out of. Whatever is already fading, if
            // anything, is the tail this load is arriving under: it was handed
            // over when the load began and the track it belongs to is gone
            // from the state already, so it is left to finish.
            _ => return,
        };
        if total == 0 {
            self.fade_out = None;
            return;
        }

        let previous = mem::replace(&mut self.state, PlayerState::Invalid);
        match previous {
            PlayerState::Playing {
                decoder,
                normalisation_factor,
                ..
            } => {
                self.fade_out = Some(FadeOut {
                    decoder,
                    normalisation_factor,
                    total,
                    done: 0,
                    spare: std::collections::VecDeque::new(),
                    drained: false,
                    rising,
                    limiter: TailLimiter {
                        integrators: self.normalisation_integrators,
                        peaks: self.normalisation_peaks,
                        channel: self.normalisation_channel,
                    },
                });
            }
            // Nothing was playing: put the state back and leave the caller to
            // replace it as it would have anyway.
            other => {
                self.state = other;
                self.fade_out = None;
            }
        }
    }

    /// LOCAL PATCH: mixes the outgoing track under `data` and fades `data` up.
    ///
    /// Equal power, not a straight line: two straight ramps summed dip in the
    /// middle, where both tracks are at half, while cos and sin square to one
    /// and hold the loudness steady across the whole overlap.
    ///
    /// The result is clamped just under full scale. Two tracks played at once
    /// can exceed it between them, and what comes out of an overflow is a click
    /// rather than a loud moment.
    /// LOCAL PATCH: see [`LimiterParams`].
    fn limiter_params(&self) -> LimiterParams {
        LimiterParams {
            dynamic: self.config.normalisation
                && self.config.normalisation_method == NormalisationMethod::Dynamic,
            threshold_db: self.config.normalisation_threshold_dbfs,
            knee_db: self.config.normalisation_knee_db,
            knee_factor: self.normalisation_knee_factor,
            attack_cf: self.config.normalisation_attack_cf,
            release_cf: self.config.normalisation_release_cf,
        }
    }

    fn apply_fade(&mut self, data: &mut [f64]) {
        let volume = self.volume_getter.attenuation_factor();
        let params = self.limiter_params();
        let channels = NUM_CHANNELS as usize;

        let Some(fade) = self.fade_out.as_mut() else {
            return;
        };

        let mut offset = 0;
        while offset + channels <= data.len() {
            let going = fade.done < fade.total;
            let arriving = fade.rising.map_or(going, |risen| risen < fade.total);
            if !arriving {
                break;
            }

            // Enough of the outgoing track for this frame, decoded on demand.
            while going && fade.spare.len() < channels && !fade.drained {
                match fade.decoder.next_packet() {
                    Ok(Some((_, packet))) => match packet.samples() {
                        Ok(samples) => fade.spare.extend(samples.iter().copied()),
                        Err(_) => fade.drained = true,
                    },
                    // Ran out before the fade did: the incoming track goes on
                    // rising, over silence rather than over music.
                    Ok(None) => fade.drained = true,
                    Err(e) => {
                        debug!("crossfade: the outgoing track stopped early: {e}");
                        fade.drained = true;
                    }
                }
            }

            let x = fade.done.min(fade.total) as f64 / fade.total as f64;
            let gain_in = match fade.rising {
                // A fade the listener started rises from nothing whatever the
                // outgoing half has done in the meantime.
                Some(risen) => (risen as f64 / fade.total as f64 * std::f64::consts::FRAC_PI_2).sin(),
                // If the outgoing track has finished draining early, bring the
                // incoming track to full scale.
                None if fade.drained && fade.spare.is_empty() => 1.0,
                None => (x * std::f64::consts::FRAC_PI_2).sin(),
            };
            let gain_out = if going {
                (x * std::f64::consts::FRAC_PI_2).cos()
            } else {
                0.0
            };

            for sample in data.iter_mut().skip(offset).take(channels) {
                let tail = if going {
                    fade.spare.pop_front().unwrap_or(0.0)
                } else {
                    0.0
                };
                // Levelled as it was while it played alone, then faded.
                let tail = fade.limiter.limit(tail * fade.normalisation_factor, &params);
                let mixed = *sample * gain_in + tail * gain_out * volume;
                *sample = soft_limit(mixed);
            }

            if going {
                fade.done += channels;
            }
            if let Some(risen) = fade.rising.as_mut() {
                *risen += channels;
            }
            offset += channels;
        }

        let finished = match fade.rising {
            Some(risen) => risen >= fade.total,
            None => fade.done >= fade.total || (fade.drained && fade.spare.is_empty()),
        };
        if finished {
            // Dropping it closes the outgoing stream.
            self.fade_out = None;
        }
    }

    /// LOCAL PATCH: writes the outgoing track on its own, with no incoming one.
    ///
    /// The same curve [`apply_fade`] uses, applied to the tail alone: there is
    /// nothing to mix it with yet. Returns whether anything was written, so the
    /// caller knows to come round again rather than wait to be woken.
    fn pump_fade_out(&mut self) -> bool {
        let volume = self.volume_getter.attenuation_factor();
        let params = self.limiter_params();

        let (samples, drained, rising) = {
            let Some(fade) = self.fade_out.as_mut() else {
                return false;
            };
            // A listener's fade whose outgoing half is already over: nothing
            // is left to play through the load, and the incoming half still
            // has its rise to come.
            if fade.rising.is_some() && fade.done >= fade.total {
                return false;
            }

            let mut samples: Vec<f64> = fade.spare.drain(..).collect();
            if !fade.drained {
                match fade.decoder.next_packet() {
                    Ok(Some((_, packet))) => match packet.samples() {
                        Ok(decoded) => samples.extend_from_slice(decoded),
                        Err(_) => fade.drained = true,
                    },
                    Ok(None) => fade.drained = true,
                    Err(e) => {
                        debug!("crossfade: the outgoing track stopped early: {e}");
                        fade.drained = true;
                    }
                }
            }

            let x = fade.done as f64 / fade.total as f64;
            let gain = (x * std::f64::consts::FRAC_PI_2).cos() * volume;
            for sample in samples.iter_mut() {
                let levelled = fade.limiter.limit(*sample * fade.normalisation_factor, &params);
                *sample = soft_limit(levelled * gain);
            }

            // Counted here as well, or the curve would stand still through the
            // load and the fade would restart at full level once the incoming
            // track arrived.
            fade.done = (fade.done + samples.len()).min(fade.total);

            (samples, fade.drained, fade.rising.is_some())
        };

        if samples.is_empty() {
            // Dropping it closes the outgoing stream; a listener's fade is kept
            // for the incoming song's rise, and closes when that is over.
            if drained && !rising {
                self.fade_out = None;
            }
            return false;
        }

        if let Err(e) = self
            .sink
            .write(AudioPacket::Samples(samples), &mut self.converter)
        {
            // The fade goes rather than the playback: what failed is the tail of
            // a song that is already over, and the track being loaded has its
            // own sink errors to report if it hits any.
            error!("{e}");
            self.fade_out = None;
            return false;
        }
        true
    }

    fn handle_player_stop(&mut self) {
        // LOCAL PATCH: nothing is being faded into any more.
        self.fade_out = None;
        // LOCAL PATCH: nor said.
        self.narration = None;
        match self.state {
            PlayerState::Playing {
                ref track_id,
                play_request_id,
                ..
            }
            | PlayerState::Paused {
                ref track_id,
                play_request_id,
                ..
            }
            | PlayerState::EndOfTrack {
                ref track_id,
                play_request_id,
                ..
            }
            | PlayerState::Loading {
                ref track_id,
                play_request_id,
                ..
            } => {
                let track_id = track_id.clone();

                self.ensure_sink_stopped(false);
                self.send_event(PlayerEvent::Stopped {
                    track_id,
                    play_request_id,
                });
                self.state = PlayerState::Stopped;
            }
            PlayerState::Stopped => (),
            PlayerState::Invalid => {
                error!("PlayerInternal::handle_player_stop in invalid state");
                exit(1);
            }
        }
    }

    fn handle_play(&mut self) {
        match self.state {
            PlayerState::Paused {
                ref track_id,
                play_request_id,
                stream_position_ms,
                ..
            } => {
                let track_id = track_id.clone();

                self.state.paused_to_playing();
                self.send_event(PlayerEvent::Playing {
                    track_id,
                    play_request_id,
                    position_ms: stream_position_ms,
                });
                self.ensure_sink_running();
            }
            // LOCAL PATCH: already playing, because the engine told this player
            // directly before it told the Connect task; see `play` in the
            // engine. The Connect task's own play comes later, sometimes
            // seconds later, and restarts its clock from the position it
            // paused at. Saying where the track really is lets it correct that
            // rather than report a position that lags by the whole delay.
            PlayerState::Playing {
                ref track_id,
                play_request_id,
                stream_position_ms,
                ..
            } => {
                let track_id = track_id.clone();
                self.send_event(PlayerEvent::PositionCorrection {
                    play_request_id,
                    track_id,
                    position_ms: stream_position_ms,
                });
            }
            PlayerState::Loading {
                ref mut start_playback,
                ..
            } => {
                *start_playback = true;
            }
            _ => error!("Player::play called from invalid state: {:?}", self.state),
        }
    }

    fn handle_pause(&mut self) {
        match self.state {
            PlayerState::Paused { .. } => self.ensure_sink_stopped(false),
            PlayerState::Playing {
                ref track_id,
                play_request_id,
                stream_position_ms,
                ..
            } => {
                let track_id = track_id.clone();

                self.state.playing_to_paused();

                self.ensure_sink_stopped(false);
                self.send_event(PlayerEvent::Paused {
                    track_id,
                    play_request_id,
                    position_ms: stream_position_ms,
                });
            }
            PlayerState::Loading {
                ref mut start_playback,
                ..
            } => {
                *start_playback = false;
            }
            _ => error!("Player::pause called from invalid state: {:?}", self.state),
        }
    }

    fn handle_packet(
        &mut self,
        packet: Option<(AudioPacketPosition, AudioPacket)>,
        normalisation_factor: f64,
    ) {
        match packet {
            Some((_, mut packet)) => {
                if !packet.is_empty() {
                    if let AudioPacket::Samples(ref mut data) = packet {
                        // LOCAL PATCH: a mix's incoming song, at the tempo
                        // the transition asked for; see TempoRamp.
                        if let Some(tempo) = self.tempo.as_mut() {
                            *data = tempo.process(data);
                            if tempo.finished() {
                                self.tempo = None;
                            }
                        }

                        // Get the volume for the packet. In the case of hardware volume control
                        // this will always be 1.0 (no change).
                        let volume = self.volume_getter.attenuation_factor();

                        // For the basic normalisation method, a normalisation factor of 1.0
                        // indicates that there is nothing to normalise (all samples should pass
                        // unaltered). For the dynamic method, there may still be peaks that we
                        // want to shave off.
                        //
                        // No matter the case we apply volume attenuation last if there is any.
                        match (self.config.normalisation, self.config.normalisation_method) {
                            (false, _) => {
                                if volume < 1.0 {
                                    for sample in data.iter_mut() {
                                        *sample *= volume;
                                    }
                                }
                            }
                            (true, NormalisationMethod::Dynamic) => {
                                // zero-cost shorthands
                                let threshold_db = self.config.normalisation_threshold_dbfs;
                                let knee_db = self.config.normalisation_knee_db;
                                let attack_cf = self.config.normalisation_attack_cf;
                                let release_cf = self.config.normalisation_release_cf;

                                for sample in data.iter_mut() {
                                    // Feedforward limiter in the log domain
                                    // After: Giannoulis, D., Massberg, M., & Reiss, J.D. (2012).
                                    // Digital Dynamic Range Compressor Design—A Tutorial and
                                    // Analysis. Journal of The Audio Engineering Society, 60,
                                    // 399-408.

                                    // This implementation assumes audio is stereo.

                                    // step 0: apply gain stage
                                    *sample *= normalisation_factor;

                                    // step 1-4: half-wave rectification and conversion into dB, and
                                    // gain computer with soft knee and subtractor
                                    let limiter_db = {
                                        // Add slight DC offset. Some samples are silence, which is
                                        // -inf dB and gets the limiter stuck. Adding a small
                                        // positive offset prevents this.
                                        *sample += f64::MIN_POSITIVE;

                                        let bias_db = ratio_to_db(sample.abs()) - threshold_db;
                                        let knee_boundary_db = bias_db * 2.0;
                                        if knee_boundary_db < -knee_db {
                                            0.0
                                        } else if knee_boundary_db.abs() <= knee_db {
                                            let term = knee_boundary_db + knee_db;
                                            term * term * self.normalisation_knee_factor
                                        } else {
                                            bias_db
                                        }
                                    };

                                    // track left/right channel
                                    let channel = self.normalisation_channel;
                                    self.normalisation_channel ^= 1;

                                    // step 5: smooth, decoupled peak detector for each channel
                                    // Use direct references to reduce repeated array indexing
                                    let integrator = &mut self.normalisation_integrators[channel];
                                    let peak = &mut self.normalisation_peaks[channel];

                                    *integrator = f64::max(
                                        limiter_db,
                                        release_cf * *integrator + (1.0 - release_cf) * limiter_db,
                                    );
                                    *peak = attack_cf * *peak + (1.0 - attack_cf) * *integrator;

                                    // steps 6-8: conversion into level and multiplication into gain
                                    // stage. Find maximum peak across both channels to couple the
                                    // gain and maintain stereo imaging.
                                    let max_peak = f64::max(
                                        self.normalisation_peaks[0],
                                        self.normalisation_peaks[1],
                                    );
                                    *sample *= db_to_ratio(-max_peak) * volume;
                                }
                            }
                            (true, NormalisationMethod::Basic) => {
                                if normalisation_factor < 1.0 || volume < 1.0 {
                                    for sample in data.iter_mut() {
                                        *sample *= normalisation_factor * volume;
                                    }
                                }
                            }
                        }
                    }

                // LOCAL PATCH: the outgoing track, mixed under this one.
                //
                // Here rather than earlier because both sides have to be at the
                // level they would have played at on their own: normalisation
                // and volume are applied above, and a fade that ran before them
                // would be a fade between two tracks nobody is hearing yet.
                if self.fade_out.is_some() {
                    if let AudioPacket::Samples(ref mut data) = packet {
                        self.apply_fade(data);
                    }
                } else if let AudioPacket::Samples(ref data) = packet {
                    // LOCAL PATCH: track trailing silence near the end of a track for silence trimming
                    let crossfade_ms = self.config.crossfade_duration_ms as i64;
                    if self.config.trim_silence && crossfade_ms > 0 && self.fade_armed.is_some() && self.early_end.is_none() {
                        const SILENCE_THRESHOLD: f64 = 0.00316; // -50 dBFS
                        if data.iter().all(|s| s.abs() < SILENCE_THRESHOLD) {
                            self.consecutive_silent_samples += data.len();
                        } else {
                            self.consecutive_silent_samples = 0;
                        }
                    } else {
                        self.consecutive_silent_samples = 0;
                    }
                }

                    if let Err(e) = self.sink.write(packet, &mut self.converter) {
                        error!("{e}");
                        self.handle_pause();
                    }
                }
            }

            None => {
                // LOCAL PATCH: a stream that runs out early is not a track that
                // ended.
                //
                // The decoder having nothing left is how a song finishes, and it
                // is also what a truncated file or a connection dropped mid-track
                // looks like from here. Upstream cannot tell the two apart, so it
                // reports the end of the track either way and whoever owns the
                // queue plays the next song — which is heard as a song starting
                // and being passed over a moment later, on a song that plays
                // perfectly well when it is chosen again.
                //
                // Far enough from where the track really ends, this is a failure,
                // and the answer to a failure is the one below: put it back on
                // from where it stopped. Bounded, because a stream that truly
                // cannot be read to the end would otherwise never let go.
                if let Some((track_id, play_request_id, position, duration)) =
                    self.state.playing_progress()
                {
                    let short = duration > 0
                        && (position as i64) + SHORT_END_TOLERANCE_MS < duration as i64;
                    let attempts = match self.short_end {
                        Some((request, count)) if request == play_request_id => count,
                        _ => 0,
                    };
                    if short && attempts < MAX_SHORT_END_RELOADS {
                        warn!("the stream for <{track_id:?}> ended at {position} ms of {duration} ms, putting it back on");
                        self.short_end = Some((play_request_id, attempts + 1));
                        self.reload_track(track_id, play_request_id, position);
                        return;
                    }
                }
                // LOCAL PATCH: the DJ's closing line, before the end is
                // announced; the end follows once it has been said.
                let closing = match self.state {
                    PlayerState::Playing {
                        ref track_id,
                        play_request_id,
                        ..
                    } if self.narrated_after != Some(play_request_id) => {
                        Some((track_id.clone(), play_request_id))
                    }
                    _ => None,
                };
                if let Some((track_id, play_request_id)) = closing {
                    {
                        self.narrated_after = Some(play_request_id);
                        if let Some(samples) = narration_for(&track_id, NarrationMoment::After) {
                            self.narration = Some(Narration {
                                samples,
                                at: 0,
                                then_end: true,
                            });
                            return;
                        }
                    }
                }
                self.finish_track();
            }
        }
    }

    /// LOCAL PATCH: the end of the track, said; split out of `handle_packet`
    /// so a closing line can say it once it is over.
    fn finish_track(&mut self) {
        self.state.playing_to_end_of_track();
        if let PlayerState::EndOfTrack {
            ref track_id,
            play_request_id,
            ..
        } = self.state
        {
            let track_id = track_id.clone();
            self.announce_end(track_id, play_request_id)
        } else {
            error!("PlayerInternal finish_track: Invalid PlayerState");
            exit(1);
        }
    }

    fn start_playback(
        &mut self,
        track_id: SpotifyUri,
        play_request_id: u64,
        loaded_track: PlayerLoadedTrackData,
        start_playback: bool,
    ) {
        let audio_item = Box::new(loaded_track.audio_item.clone());

        self.send_event(PlayerEvent::TrackChanged { audio_item });

        let position_ms = loaded_track.stream_position_ms;

        let mut config = self.config.clone();
        if config.normalisation_type == NormalisationType::Auto {
            if self.auto_normalise_as_album {
                config.normalisation_type = NormalisationType::Album;
            } else {
                config.normalisation_type = NormalisationType::Track;
            }
        };
        let normalisation_factor =
            NormalisationData::get_factor(&config, loaded_track.normalisation_data);

        // LOCAL PATCH: keep the track being replaced audible for the length of
        // the crossfade. Only when one really is playing: a load from stopped,
        // or a seek within the same track, has nothing to fade out of.
        if start_playback {
            self.begin_fade_out();
        } else {
            self.fade_out = None;
        }

        if start_playback {
            self.ensure_sink_running();
            self.send_event(PlayerEvent::Playing {
                track_id: track_id.clone(),
                play_request_id,
                position_ms,
            });

            self.state = PlayerState::Playing {
                track_id,
                play_request_id,
                decoder: loaded_track.decoder,
                audio_item: loaded_track.audio_item,
                normalisation_data: loaded_track.normalisation_data,
                normalisation_factor,
                stream_loader_controller: loaded_track.stream_loader_controller,
                duration_ms: loaded_track.duration_ms,
                bytes_per_second: loaded_track.bytes_per_second,
                stream_position_ms: loaded_track.stream_position_ms,
                reported_nominal_start_time: Instant::now()
                    .checked_sub(Duration::from_millis(position_ms as u64)),
                suggested_to_preload_next_track: false,
                is_explicit: loaded_track.is_explicit,
            };
        } else {
            self.ensure_sink_stopped(false);

            self.state = PlayerState::Paused {
                track_id: track_id.clone(),
                play_request_id,
                decoder: loaded_track.decoder,
                audio_item: loaded_track.audio_item,
                normalisation_data: loaded_track.normalisation_data,
                normalisation_factor,
                stream_loader_controller: loaded_track.stream_loader_controller,
                duration_ms: loaded_track.duration_ms,
                bytes_per_second: loaded_track.bytes_per_second,
                stream_position_ms: loaded_track.stream_position_ms,
                suggested_to_preload_next_track: false,
                is_explicit: loaded_track.is_explicit,
            };

            self.send_event(PlayerEvent::Paused {
                track_id,
                play_request_id,
                position_ms,
            });
        }
    }

    fn handle_command_load(
        &mut self,
        track_id: SpotifyUri,
        play_request_id_option: Option<u64>,
        play: bool,
        position_ms: u32,
    ) -> PlayerResult {
        let play_request_id =
            play_request_id_option.unwrap_or(self.play_request_id_generator.get());

        // LOCAL PATCH: the song a mix transition goes into comes in where the
        // transition says, not from its first second; see [MixPlan]. Only a
        // load from the start, which is what moving on to the next song is:
        // a load at a position is a seek or a resume, and keeps it.
        let mut position_ms = position_ms;
        // Whatever song was being brought back to its tempo is gone.
        self.tempo = None;
        if let Some(plan) = self.mix_plan.as_ref() {
            if position_ms == 0 && track_id.to_uri().ok().as_deref() == Some(plan.to.as_str()) {
                info!("mix: {} comes in at {} ms, at {}x", plan.to, plan.in_ms, plan.speed_in);
                position_ms = plan.in_ms;
                if (plan.speed_in - 1.0).abs() > 0.002 {
                    self.tempo = Some(TempoRamp::new(plan.speed_in, plan.fade_ms));
                }
            }
        }

        // LOCAL PATCH: a line about the track being left goes with it.
        self.narration = None;

        // LOCAL PATCH: whatever was playing is being replaced, so nothing more
        // is going to be said about it.
        //
        // A fade announces the end of a song a few seconds before it arrives,
        // and a listener who skips inside those seconds leaves that
        // announcement in flight: it lands after the queue has already moved,
        // and is heard as the song after this one being passed over, or as two
        // songs playing at once while the one that was replaced insists it is
        // still finishing. The song being left has no end worth reporting — it
        // is not ending, it is being replaced.
        //
        // Only the announcing is stopped. `early_end` stays exactly as it is,
        // because it is also what tells `begin_fade_out` that this song is
        // owed a fade: clearing it here left every crossfade to end as a cut,
        // which is worse than the thing this was fixing.
        if let Some(previous) = self.state.play_request_id() {
            if previous != play_request_id {
                self.ended = Some(previous);
                self.consecutive_silent_samples = 0;
            }
        }

        self.send_event(PlayerEvent::PlayRequestIdChanged { play_request_id });

        if !self.config.gapless {
            self.ensure_sink_stopped(play);
        }

        if matches!(self.state, PlayerState::Invalid) {
            return Err(Error::internal(format!(
                "Player::handle_command_load called from invalid state: {:?}",
                self.state
            )));
        }

        // Now we check at different positions whether we already have a pre-loaded version
        // of this track somewhere. If so, use it and return.

        // Check if there's a matching loaded track in the EndOfTrack player state.
        // This is the case if we're repeating the same track again.
        if let PlayerState::EndOfTrack {
            track_id: previous_track_id,
            ..
        } = &self.state
        {
            if *previous_track_id == track_id {
                let mut loaded_track = match mem::replace(&mut self.state, PlayerState::Invalid) {
                    PlayerState::EndOfTrack { loaded_track, .. } => loaded_track,
                    _ => {
                        return Err(Error::internal(format!(
                            "PlayerInternal::handle_command_load repeating the same track: invalid state: {:?}",
                            self.state
                        )));
                    }
                };

                if position_ms != loaded_track.stream_position_ms {
                    // This may be blocking.
                    loaded_track.stream_position_ms = loaded_track.decoder.seek(position_ms)?;
                }
                self.preload = PlayerPreload::None;
                self.start_playback(track_id, play_request_id, loaded_track, play);
                if let PlayerState::Invalid = self.state {
                    return Err(Error::internal(format!(
                        "PlayerInternal::handle_command_load repeating the same track: start_playback() did not transition to valid player state: {:?}",
                        self.state
                    )));
                }
                return Ok(());
            }
        }

        // Check if we are already playing the track. If so, just do a seek and update our info.
        if let PlayerState::Playing {
            track_id: ref current_track_id,
            ref mut stream_position_ms,
            ref mut decoder,
            ..
        }
        | PlayerState::Paused {
            track_id: ref current_track_id,
            ref mut stream_position_ms,
            ref mut decoder,
            ..
        } = self.state
        {
            if *current_track_id == track_id {
                // we can use the current decoder. Ensure it's at the correct position.
                if position_ms != *stream_position_ms {
                    // This may be blocking.
                    *stream_position_ms = decoder.seek(position_ms)?;
                }

                // Move the info from the current state into a PlayerLoadedTrackData so we can use
                // the usual code path to start playback.
                let old_state = mem::replace(&mut self.state, PlayerState::Invalid);

                if let PlayerState::Playing {
                    stream_position_ms,
                    decoder,
                    audio_item,
                    stream_loader_controller,
                    bytes_per_second,
                    duration_ms,
                    normalisation_data,
                    is_explicit,
                    ..
                }
                | PlayerState::Paused {
                    stream_position_ms,
                    decoder,
                    audio_item,
                    stream_loader_controller,
                    bytes_per_second,
                    duration_ms,
                    normalisation_data,
                    is_explicit,
                    ..
                } = old_state
                {
                    let loaded_track = PlayerLoadedTrackData {
                        decoder,
                        normalisation_data,
                        stream_loader_controller,
                        audio_item,
                        bytes_per_second,
                        duration_ms,
                        stream_position_ms,
                        is_explicit,
                    };

                    self.preload = PlayerPreload::None;
                    self.start_playback(track_id, play_request_id, loaded_track, play);

                    if let PlayerState::Invalid = self.state {
                        return Err(Error::internal(format!(
                            "PlayerInternal::handle_command_load already playing this track: start_playback() did not transition to valid player state: {:?}",
                            self.state
                        )));
                    }

                    return Ok(());
                } else {
                    return Err(Error::internal(format!(
                        "PlayerInternal::handle_command_load already playing this track: invalid state: {:?}",
                        self.state
                    )));
                }
            }
        }

        // Check if the requested track has been preloaded already. If so use the preloaded data.
        if let PlayerPreload::Ready {
            track_id: loaded_track_id,
            ..
        } = &self.preload
        {
            if track_id == *loaded_track_id {
                let preload = std::mem::replace(&mut self.preload, PlayerPreload::None);
                if let PlayerPreload::Ready {
                    track_id,
                    mut loaded_track,
                } = preload
                {
                    if position_ms != loaded_track.stream_position_ms {
                        // This may be blocking
                        loaded_track.stream_position_ms = loaded_track.decoder.seek(position_ms)?;
                    }
                    self.start_playback(track_id, play_request_id, *loaded_track, play);
                    return Ok(());
                } else {
                    return Err(Error::internal(format!(
                        "PlayerInternal::handle_command_loading preloaded track: invalid state: {:?}",
                        self.state
                    )));
                }
            }
        }

        self.send_event(PlayerEvent::Loading {
            track_id: track_id.clone(),
            play_request_id,
            position_ms,
        });

        // Try to extract a pending loader from the preloading mechanism
        let loader = if let PlayerPreload::Loading {
            track_id: loaded_track_id,
            ..
        } = &self.preload
        {
            if (track_id == *loaded_track_id) && (position_ms == 0) {
                let mut preload = PlayerPreload::None;
                std::mem::swap(&mut preload, &mut self.preload);
                if let PlayerPreload::Loading { loader, .. } = preload {
                    Some(loader)
                } else {
                    None
                }
            } else {
                None
            }
        } else {
            None
        };

        self.preload = PlayerPreload::None;

        // LOCAL PATCH: a fresh load is a fresh set of attempts, and a retry has
        // to know where this one was starting from.
        self.load_attempt = 0;
        self.load_position_ms = position_ms;

        // If we don't have a loader yet, create one from scratch.
        let loader =
            loader.unwrap_or_else(|| Box::pin(self.load_track(track_id.clone(), position_ms)));

        // LOCAL PATCH: the track being left goes into the fade here, not when
        // the new one starts.
        //
        // A track that was already preloaded reaches `start_playback` in the
        // same breath and fades out there. One that has to be fetched does not:
        // the state below replaces the track that is playing, and with it went
        // its decoder and any chance of fading it, so a skip onto a track the
        // engine had not seen coming was a cut. The tail is played under the
        // wait by `pump_fade_out`, and the track arriving rises from nothing on
        // its own clock; see FadeOut::rising.
        if play {
            self.begin_fade_out();
        }

        // Set ourselves to a loading state.
        self.state = PlayerState::Loading {
            track_id,
            play_request_id,
            start_playback: play,
            loader,
        };

        Ok(())
    }

    fn handle_command_preload(&mut self, track_id: SpotifyUri) {
        debug!("Preloading track");
        let mut preload_track = true;
        // check whether the track is already loaded somewhere or being loaded.
        if let PlayerPreload::Loading {
            track_id: currently_loading,
            ..
        }
        | PlayerPreload::Ready {
            track_id: currently_loading,
            ..
        } = &self.preload
        {
            if *currently_loading == track_id {
                // we're already preloading the requested track.
                preload_track = false;
            } else {
                // we're preloading something else - cancel it.
                self.preload = PlayerPreload::None;
            }
        }

        if let PlayerState::Playing {
            track_id: current_track_id,
            ..
        }
        | PlayerState::Paused {
            track_id: current_track_id,
            ..
        }
        | PlayerState::EndOfTrack {
            track_id: current_track_id,
            ..
        } = &self.state
        {
            if *current_track_id == track_id {
                // we already have the requested track loaded.
                preload_track = false;
            }
        }

        // schedule the preload of the current track if desired.
        if preload_track {
            let loader = self.load_track(track_id.clone(), 0);
            self.preload = PlayerPreload::Loading {
                track_id,
                loader: Box::pin(loader),
            }
        }
    }

    fn handle_command_seek(&mut self, position_ms: u32) -> PlayerResult {
        // LOCAL PATCH: a listener who moves through the track wants the
        // music, not the rest of its introduction. A closing line still ends
        // the track: there is no music left to want.
        // Paused, it is simply dropped: the decoder is at the end, and the
        // end is reached again as soon as the track plays.
        if let Some(narration) = self.narration.take() {
            if narration.then_end && self.state.is_playing() {
                self.finish_track();
                return Ok(());
            }
        }

        // When we are still loading, the user may immediately ask to
        // seek to another position yet the decoder won't be ready for
        // that. In this case just restart the loading process but
        // with the requested position.
        if let PlayerState::Loading {
            ref track_id,
            play_request_id,
            start_playback,
            ..
        } = self.state
        {
            return self.handle_command_load(
                track_id.clone(),
                Some(play_request_id),
                start_playback,
                position_ms,
            );
        }

        if let Some(decoder) = self.state.decoder() {
            match decoder.seek(position_ms) {
                Ok(new_position_ms) => {
                    if let PlayerState::Playing {
                        ref mut stream_position_ms,
                        ref track_id,
                        play_request_id,
                        ..
                    }
                    | PlayerState::Paused {
                        ref mut stream_position_ms,
                        ref track_id,
                        play_request_id,
                        ..
                    } = self.state
                    {
                        *stream_position_ms = new_position_ms;

                        self.send_event(PlayerEvent::Seeked {
                            play_request_id,
                            track_id: track_id.clone(),
                            position_ms: new_position_ms,
                        });
                    }
                }
                Err(e) => error!("PlayerInternal::handle_command_seek error: {e}"),
            }
        } else {
            error!("Player::seek called from invalid state: {:?}", self.state);
        }

        // ensure we have a bit of a buffer of downloaded data
        self.preload_data_before_playback()?;

        if let PlayerState::Playing {
            ref mut reported_nominal_start_time,
            ..
        } = self.state
        {
            *reported_nominal_start_time =
                Instant::now().checked_sub(Duration::from_millis(position_ms as u64));
        }

        Ok(())
    }

    fn handle_command(&mut self, cmd: PlayerCommand) -> PlayerResult {
        debug!("command={cmd:?}");
        match cmd {
            PlayerCommand::Load {
                track_id,
                play,
                position_ms,
            } => self.handle_command_load(track_id, None, play, position_ms)?,

            PlayerCommand::Preload { track_id } => self.handle_command_preload(track_id),

            PlayerCommand::Seek(position_ms) => self.handle_command_seek(position_ms)?,

            PlayerCommand::Play => self.handle_play(),

            PlayerCommand::Pause => self.handle_pause(),

            PlayerCommand::Stop => self.handle_player_stop(),

            PlayerCommand::SetSession(session) => self.session = session,

            PlayerCommand::AddEventSender(sender) => self.event_senders.push(sender),

            PlayerCommand::SetSinkEventCallback(callback) => self.sink_event_callback = callback,

            PlayerCommand::EmitVolumeChangedEvent(volume) => {
                self.send_event(PlayerEvent::VolumeChanged { volume })
            }

            PlayerCommand::EmitRepeatChangedEvent { context, track } => {
                self.send_event(PlayerEvent::RepeatChanged { context, track })
            }

            PlayerCommand::EmitShuffleChangedEvent(shuffle) => {
                self.send_event(PlayerEvent::ShuffleChanged { shuffle })
            }

            PlayerCommand::EmitAutoPlayChangedEvent(auto_play) => {
                self.send_event(PlayerEvent::AutoPlayChanged { auto_play })
            }

            PlayerCommand::EmitSessionClientChangedEvent {
                client_id,
                client_name,
                client_brand_name,
                client_model_name,
            } => self.send_event(PlayerEvent::SessionClientChanged {
                client_id,
                client_name,
                client_brand_name,
                client_model_name,
            }),

            PlayerCommand::EmitSessionConnectedEvent {
                connection_id,
                user_name,
            } => self.send_event(PlayerEvent::SessionConnected {
                connection_id,
                user_name,
            }),

            PlayerCommand::EmitSessionDisconnectedEvent {
                connection_id,
                user_name,
            } => self.send_event(PlayerEvent::SessionDisconnected {
                connection_id,
                user_name,
            }),

            PlayerCommand::SetAutoNormaliseAsAlbum(setting) => {
                self.auto_normalise_as_album = setting
            }

            // LOCAL PATCH: see Player::set_bitrate.
            PlayerCommand::SetBitrate(bitrate) => {
                if self.config.bitrate != bitrate {
                    info!("bitrate is now {bitrate:?}, from the next track");
                    self.config.bitrate = bitrate;
                    // What was preloaded was fetched at the old quality, and
                    // keeping it would silently undo the change for exactly one
                    // track — the next one, which is the one this was asked for.
                    self.preload = PlayerPreload::None;
                }
            }

            // LOCAL PATCH: see Player::set_trim_silence.
            PlayerCommand::SetTrimSilence(enabled) => {
                info!("trim_silence is now {enabled}");
                self.config.trim_silence = enabled;
            }

            // LOCAL PATCH: see PlayerConfig::hold_end.
            // LOCAL PATCH: see PlayerConfig::skip_fade_ms.
            PlayerCommand::SetSkipFade(ms) => {
                info!("skip_fade_ms is now {ms}");
                self.config.skip_fade_ms = ms;
            }

            PlayerCommand::SetMixPlan(plan) => {
                info!("mix plan is now {plan:?}");
                self.mix_plan = plan;
            }

            PlayerCommand::SetHoldEnd(enabled) => {
                info!("hold_end is now {enabled}");
                self.config.hold_end = enabled;
            }

            PlayerCommand::EmitFilterExplicitContentChangedEvent(filter) => {
                self.send_event(PlayerEvent::FilterExplicitContentChanged { filter });

                if filter {
                    if let PlayerState::Playing {
                        ref track_id,
                        play_request_id,
                        is_explicit,
                        ..
                    }
                    | PlayerState::Paused {
                        ref track_id,
                        play_request_id,
                        is_explicit,
                        ..
                    } = self.state
                    {
                        let track_id = track_id.clone();

                        if is_explicit {
                            warn!(
                                "Currently loaded track is explicit, which client setting forbids -- skipping to next track."
                            );
                            self.announce_end(track_id, play_request_id)
                        }
                    }
                }
            }
        };

        Ok(())
    }

    /// LOCAL PATCH: says a track has finished, once and only once.
    ///
    /// A track can reach its end by more than one road — the crossfade
    /// announcing it early, the stream running out, a filter refusing to play
    /// it — and on a track whose file is shorter than its metadata says, two of
    /// them arrive within a fraction of a second. Whoever owns the queue obeys
    /// each one, so two announcements are two songs skipped: one heard for an
    /// instant and one not heard at all.
    fn announce_end(&mut self, track_id: SpotifyUri, play_request_id: u64) {
        if self.ended == Some(play_request_id) {
            debug!("<{track_id:?}> has already been announced as finished");
            return;
        }
        self.ended = Some(play_request_id);
        self.send_event(PlayerEvent::EndOfTrack {
            track_id,
            play_request_id,
        });
    }

    fn send_event(&mut self, event: PlayerEvent) {
        self.event_senders
            .retain(|sender| sender.send(event.clone()).is_ok());
    }

    /// LOCAL PATCH: puts a failed track back on, from where it stopped.
    ///
    /// Upstream answers a read or decode failure with `EndOfTrack`, and Spirc
    /// answers *that* by playing the next song — so a stumble on the network
    /// looks exactly like a song reaching its end, and the queue walks forward
    /// on its own. Two failures in a row and the listener is two songs along
    /// from what they chose, which is what this is here to stop.
    ///
    /// The difference that matters is between a track that cannot be played and
    /// one that did not load: the first is answered with `Unavailable` further
    /// up, and skipping it is right. This is the second, and the only correct
    /// answer to it is to try again — the song is there, and the listener asked
    /// for it.
    fn reload_track(&mut self, track_id: SpotifyUri, play_request_id: u64, position_ms: u32) {
        let start_playback = self.state.is_playing();
        self.send_event(PlayerEvent::Loading {
            track_id: track_id.clone(),
            play_request_id,
            position_ms,
        });

        let loader = self.load_track(track_id.clone(), position_ms);
        let loader = Box::pin(
            async move {
                loader.await
            }
            .fuse(),
        );
        self.state = PlayerState::Loading {
            track_id,
            play_request_id,
            start_playback,
            loader,
        };
    }

    fn load_track(
        &mut self,
        spotify_uri: SpotifyUri,
        position_ms: u32,
    ) -> impl FusedFuture<Output = Result<PlayerLoadedTrackData, ()>> + Send + 'static {
        // This method creates a future that returns the loaded stream and associated info.
        // Ideally all work should be done using asynchronous code. However, seek() on the
        // audio stream is implemented in a blocking fashion. Thus, we can't turn it into future
        // easily. Instead we spawn a thread to do the work and return a one-shot channel as the
        // future to work with.

        let loader = PlayerTrackLoader {
            session: self.session.clone(),
            config: self.config.clone(),
            local_file_lookup: self.local_file_lookup.clone(),
        };

        let (result_tx, result_rx) = oneshot::channel();

        let load_handles_clone = self.load_handles.clone();
        let handle = tokio::runtime::Handle::current();

        let load_handle = thread::spawn(move || {
            let data = handle.block_on(loader.load_track(spotify_uri, position_ms));
            if let Some(data) = data {
                let _ = result_tx.send(data);
            }

            let mut load_handles = load_handles_clone.lock().expect(LOAD_HANDLES_POISON_MSG);
            load_handles.remove(&thread::current().id());
        });

        let mut load_handles = self.load_handles.lock().expect(LOAD_HANDLES_POISON_MSG);
        load_handles.insert(load_handle.thread().id(), load_handle);

        result_rx.map_err(|_| ())
    }

    fn preload_data_before_playback(&mut self) -> PlayerResult {
        if let PlayerState::Playing {
            bytes_per_second,
            ref mut stream_loader_controller,
            ..
        } = self.state
        {
            let read_ahead_during_playback = AudioFetchParams::get().read_ahead_during_playback;
            // Request our read ahead range
            let request_data_length =
                (read_ahead_during_playback.as_secs_f32() * bytes_per_second as f32) as usize;

            // Request the part we want to wait for blocking. This effectively means we wait for the previous request to partially complete.
            let wait_for_data_length =
                (read_ahead_during_playback.as_secs_f32() * bytes_per_second as f32) as usize;

            stream_loader_controller.fetch_next_and_wait(request_data_length, wait_for_data_length)
        } else {
            Ok(())
        }
    }
}

impl Drop for PlayerInternal {
    fn drop(&mut self) {
        debug!("drop PlayerInternal[{}]", self.player_id);

        let handles: Vec<thread::JoinHandle<()>> = {
            // waiting for the thread while holding the mutex would result in a deadlock
            let mut load_handles = self.load_handles.lock().expect(LOAD_HANDLES_POISON_MSG);

            load_handles
                .drain()
                .map(|(_thread_id, handle)| handle)
                .collect()
        };

        for handle in handles {
            let _ = handle.join();
        }
    }
}

impl fmt::Debug for PlayerCommand {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PlayerCommand::Load {
                track_id,
                play,
                position_ms,
                ..
            } => f
                .debug_tuple("Load")
                .field(&track_id)
                .field(&play)
                .field(&position_ms)
                .finish(),
            PlayerCommand::Preload { track_id } => {
                f.debug_tuple("Preload").field(&track_id).finish()
            }
            PlayerCommand::Play => f.debug_tuple("Play").finish(),
            PlayerCommand::Pause => f.debug_tuple("Pause").finish(),
            PlayerCommand::Stop => f.debug_tuple("Stop").finish(),
            PlayerCommand::Seek(position) => f.debug_tuple("Seek").field(&position).finish(),
            PlayerCommand::SetSession(_) => f.debug_tuple("SetSession").finish(),
            PlayerCommand::AddEventSender(_) => f.debug_tuple("AddEventSender").finish(),
            PlayerCommand::SetSinkEventCallback(_) => {
                f.debug_tuple("SetSinkEventCallback").finish()
            }
            PlayerCommand::EmitVolumeChangedEvent(volume) => f
                .debug_tuple("EmitVolumeChangedEvent")
                .field(&volume)
                .finish(),
            PlayerCommand::SetBitrate(bitrate) => {
                f.debug_tuple("SetBitrate").field(bitrate).finish()
            }
            PlayerCommand::SetTrimSilence(enabled) => {
                f.debug_tuple("SetTrimSilence").field(enabled).finish()
            }
            PlayerCommand::SetSkipFade(ms) => f.debug_tuple("SetSkipFade").field(ms).finish(),
            PlayerCommand::SetMixPlan(plan) => f.debug_tuple("SetMixPlan").field(plan).finish(),
            PlayerCommand::SetHoldEnd(enabled) => {
                f.debug_tuple("SetHoldEnd").field(enabled).finish()
            }
            PlayerCommand::SetAutoNormaliseAsAlbum(setting) => f
                .debug_tuple("SetAutoNormaliseAsAlbum")
                .field(&setting)
                .finish(),
            PlayerCommand::EmitFilterExplicitContentChangedEvent(filter) => f
                .debug_tuple("EmitFilterExplicitContentChangedEvent")
                .field(&filter)
                .finish(),
            PlayerCommand::EmitSessionConnectedEvent {
                connection_id,
                user_name,
            } => f
                .debug_tuple("EmitSessionConnectedEvent")
                .field(&connection_id)
                .field(&user_name)
                .finish(),
            PlayerCommand::EmitSessionDisconnectedEvent {
                connection_id,
                user_name,
            } => f
                .debug_tuple("EmitSessionDisconnectedEvent")
                .field(&connection_id)
                .field(&user_name)
                .finish(),
            PlayerCommand::EmitSessionClientChangedEvent {
                client_id,
                client_name,
                client_brand_name,
                client_model_name,
            } => f
                .debug_tuple("EmitSessionClientChangedEvent")
                .field(&client_id)
                .field(&client_name)
                .field(&client_brand_name)
                .field(&client_model_name)
                .finish(),
            PlayerCommand::EmitShuffleChangedEvent(shuffle) => f
                .debug_tuple("EmitShuffleChangedEvent")
                .field(&shuffle)
                .finish(),
            PlayerCommand::EmitRepeatChangedEvent { context, track } => f
                .debug_tuple("EmitRepeatChangedEvent")
                .field(&context)
                .field(&track)
                .finish(),
            PlayerCommand::EmitAutoPlayChangedEvent(auto_play) => f
                .debug_tuple("EmitAutoPlayChangedEvent")
                .field(&auto_play)
                .finish(),
        }
    }
}

impl fmt::Debug for PlayerState {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        use PlayerState::*;
        match self {
            Stopped => f.debug_struct("Stopped").finish(),
            Loading {
                track_id,
                play_request_id,
                ..
            } => f
                .debug_struct("Loading")
                .field("track_id", &track_id)
                .field("play_request_id", &play_request_id)
                .finish(),
            Paused {
                track_id,
                play_request_id,
                ..
            } => f
                .debug_struct("Paused")
                .field("track_id", &track_id)
                .field("play_request_id", &play_request_id)
                .finish(),
            Playing {
                track_id,
                play_request_id,
                ..
            } => f
                .debug_struct("Playing")
                .field("track_id", &track_id)
                .field("play_request_id", &play_request_id)
                .finish(),
            EndOfTrack {
                track_id,
                play_request_id,
                ..
            } => f
                .debug_struct("EndOfTrack")
                .field("track_id", &track_id)
                .field("play_request_id", &play_request_id)
                .finish(),
            Invalid => f.debug_struct("Invalid").finish(),
        }
    }
}

struct Subfile<T: Read + Seek> {
    stream: T,
    offset: u64,
    length: u64,
}

impl<T: Read + Seek> Subfile<T> {
    pub fn new(mut stream: T, offset: u64, length: u64) -> Result<Subfile<T>, io::Error> {
        let target = SeekFrom::Start(offset);
        stream.seek(target)?;

        Ok(Subfile {
            stream,
            offset,
            length,
        })
    }
}

impl<T: Read + Seek> Read for Subfile<T> {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        self.stream.read(buf)
    }
}

impl<T: Read + Seek> Seek for Subfile<T> {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        let pos = match pos {
            SeekFrom::Start(offset) => SeekFrom::Start(offset + self.offset),
            SeekFrom::End(offset) => {
                if (self.length as i64 - offset) < self.offset as i64 {
                    return Err(io::Error::new(
                        io::ErrorKind::InvalidInput,
                        "newpos would be < self.offset",
                    ));
                }
                pos
            }
            _ => pos,
        };

        let newpos = self.stream.seek(pos)?;
        Ok(newpos - self.offset)
    }
}

impl<R> MediaSource for Subfile<R>
where
    R: Read + Seek + Send + Sync,
{
    fn is_seekable(&self) -> bool {
        true
    }

    fn byte_len(&self) -> Option<u64> {
        Some(self.length)
    }
}