Skip to content

A cross platform Audiobookshelf client for Android and iOS

Dart
336 KB
Raw Blame
import 'dart:async';
import 'dart:convert';
import 'dart:math' as math;
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import '_audio_player.dart';
import 'package:audio_service/audio_service.dart';
import 'package:audio_session/audio_session.dart';
import 'package:just_audio_media_kit/just_audio_media_kit.dart';
import 'package:connectivity_plus/connectivity_plus.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'api_service.dart';
import 'download_service.dart';
import 'narrated_books.dart';
import 'narration_stream.dart';
import 'offline_source.dart';
import 'playback_history_service.dart' hide PlaybackEvent;
import 'progress_sync_service.dart';
import 'local_session_service.dart';
import 'sync_logic.dart';
import 'transcription_service.dart';
import 'sleep_timer_service.dart';
import 'equalizer_service.dart';
import 'external_audio_output_types.dart';
import 'android_auto_service.dart';
import 'chromecast_service.dart';
import 'chapter_lookup.dart';
import 'now_playing_layout.dart';
import 'cold_start_play_policy.dart';
import 'playback_error_policy.dart';
import 'player_settings.dart';
import 'session_cache.dart';
import 'home_widget_service.dart';
import 'bookmark_service.dart';
import 'review_service.dart';
import 'dart:io' show ProcessInfo;
import 'package:flutter/foundation.dart' show kIsWeb;
import '../utils/app_platform.dart';
import '../utils/episode_key.dart';
import '../utils/duration_format.dart';
import '../l10n/app_localizations.dart';
import '../main.dart' show rootNavigatorKey;
import '../widgets/overlay_toast.dart' show showNavigatorOverlayToast;
export 'player_settings.dart';

String playbackDownloadKey(String itemId, String? episodeId) =>
    episodeKeyFor(itemId, episodeId);

// ─── AudioHandler (runs in background, controls notification) ───

class AudioPlayerHandler extends BaseAudioHandler with SeekHandler {
  final AudioPlayer _player = AudioPlayer(
    handleInterruptions: false,
    // Bypass the local HTTP proxy — headers are sent natively on both
    // platforms (ExoPlayer via setDefaultRequestProperties, AVPlayer via
    // AVURLAssetHTTPHeaderFieldsKey). The proxy doubles the packet count.
    useProxyForRequestHeaders: false,
    audioLoadConfiguration: AudioLoadConfiguration(
      androidLoadControl: const AndroidLoadControl(
        bufferForPlaybackDuration: Duration(seconds: 2),
        bufferForPlaybackAfterRebufferDuration: Duration(seconds: 5),
        targetBufferBytes: 5 * 1024 * 1024, // 5 MB buffer
      ),
      // iOS: disable AVPlayer's "wait for sustained playback guarantee" mode.
      // Default true makes AVPlayer set _player.rate = speed and only actually
      // start playing once iOS thinks stalls are unlikely. In foreground this
      // resolves instantly; in background after a fresh asset load, iOS never
      // grants that guarantee, so the new track stays state=buffering at
      // pos=0.0 forever even with hundreds of seconds buffered (GH #244).
      // Apple only: elsewhere leaving the default skips the call, which the
      // Windows engine doesn't implement and failed every load on.
      darwinLoadControl: DarwinLoadControl(
        automaticallyWaitsToMinimizeStalling:
            !(AppPlatform.isIOS || AppPlatform.isMacOS),
      ),
    ),
  );
  AudioPlayerService? _service; // back-reference for auto-rewind

  // Cached skip amounts for notification icon selection (updated when settings change)
  int _cachedForwardSkip = 30;
  int _cachedBackSkip = 10;
  // Android: which pair fills the phone media player's two extra slots - speed +
  // bookmark (true) or chapter skip (false). Android Auto shows all of them
  // regardless. See PlayerSettings.getMediaControlsSpeedBookmark.
  bool _cachedNotifSpeedBookmark = false;
  // When true, the system scrubber is non-draggable (seek action dropped from
  // the playback state). See PlayerSettings.getLockSeekBar.
  bool _cachedLockSeekBar = false;

  AudioPlayer get player => _player;

  void bindService(AudioPlayerService service) => _service = service;

  // [AbsorbDiag] Channel for phantom-resume diagnostics (GH #243). Reads
  // statics from the vendored audio_service Java side via MainActivity.kt.
  // Strip the call sites + the channel once #243 is closed.
  static const _absorbDiagChannel = MethodChannel('com.absorb.audio_diag');
  static bool _diagMissingLogged = false;

  /// Fetch the raw diag snapshot from the Java side. Returns null on iOS or
  /// when the channel is unavailable. Used by click() to also read the
  /// keycode for intent disambiguation, not just to log it.
  static Future<Map<String, dynamic>?> _absorbDiagSnapshot() async {
    if (!AppPlatform.isAndroid) return null;
    try {
      return await _absorbDiagChannel.invokeMapMethod<String, dynamic>(
        'snapshot',
      );
    } on MissingPluginException {
      if (!_diagMissingLogged) {
        _diagMissingLogged = true;
        debugPrint('[AbsorbDiag] snapshot channel missing on this engine');
      }
      return null;
    } catch (e) {
      debugPrint('[AbsorbDiag] snapshot failed: $e');
      return null;
    }
  }

  static void _logAbsorbDiagFromSnapshot(
    String tag,
    Map<String, dynamic>? snap,
  ) {
    if (snap == null) return;
    debugPrint(
      '[AbsorbDiag] $tag: '
      'keyCode=${snap['lastKeyCode']} keyAgeMs=${snap['lastKeyAgeMs']} '
      'lastPlayCaller=${snap['lastPlayCaller']} playAgeMs=${snap['lastPlayCallerAgeMs']} '
      'lastPauseCaller=${snap['lastPauseCaller']} pauseAgeMs=${snap['lastPauseCallerAgeMs']} '
      'carClientAgeMs=${snap['carClientAgeMs']} keyPkg=${snap['lastKeyPkg']} '
      'route=[${snap['route']}] outputs=[${snap['outputs']}]',
    );
  }

  static bool _isCarPackage(String? pkg) =>
      pkg != null &&
      (pkg == 'com.google.android.projection.gearhead' ||
          pkg.startsWith('com.android.car'));

  /// Our own widget sends its play button through the media session like a
  /// headset would; the package tells them apart.
  static bool _isOwnPackage(String? pkg) =>
      pkg != null && pkg.startsWith('com.barnabas.absorb');

  static Future<void> _logAbsorbDiag(String tag) async {
    _logAbsorbDiagFromSnapshot(tag, await _absorbDiagSnapshot());
  }

  /// How long after a car client (Android Auto / Automotive) last touched the
  /// browse tree we still assume a car is attached. Long enough to span a
  /// drive where the head unit connected once and never browsed again, short
  /// enough that a headset press hours after the drive is taken at face value.
  static const _carClientWindow = Duration(hours: 2);

  /// Whether another app is playing on the music stream right now. A media
  /// key that reaches us while we are paused and something else is audible
  /// was meant for that something else - an earbud's wear detection pausing
  /// a video, say. Android routes keys to the last media session, and video
  /// apps often have none, so it lands here; playing on top of the video is
  /// the last thing the user wants. Unknown reads as nothing playing.
  static Future<bool> _otherAudioActive() async {
    if (!AppPlatform.isAndroid) return false;
    try {
      final active = await AndroidAudioManager().isMusicActive();
      debugPrint('[Handler] other audio active=$active');
      return active;
    } catch (e) {
      debugPrint('[Handler] isMusicActive failed: $e');
      return false;
    }
  }

  /// Whether a car client has touched the media browse tree recently, per the
  /// Java-side stamp. The MEDIA_PAUSE-while-paused phantom (GH #243) only
  /// exists on Android Auto, so this is what decides whether the click
  /// resolver suppresses that keycode or honors it as a headset toggle.
  /// Snapshot missing (iOS, channel unavailable) reads as no car.
  static Future<bool> _carClientRecentlySeen() async {
    final snap = await _absorbDiagSnapshot();
    final age = snap?['carClientAgeMs'];
    final seen =
        age is int && age >= 0 && age < _carClientWindow.inMilliseconds;
    debugPrint(
      '[Handler] car client ${seen ? 'seen' : 'not seen'} (carClientAgeMs=$age)',
    );
    return seen;
  }

  /// Force-push current PlaybackState so the notification picks up
  /// new chapter-relative position immediately (e.g. on chapter change).
  void refreshPlaybackState() {
    try {
      playbackState.add(_transformEvent(_player.playbackEvent));
      _lastPlaybackStateUpdate = DateTime.now();
      _lastPlaying = _player.playing;
      _lastProcessingState = _player.processingState;
    } catch (_) {}
  }

  AudioPlayerHandler() {
    _subscribePlaybackEvents();
    // One line per ExoPlayer state transition (playerStateStream is already
    // distinct). Tells "the app paused it" apart from "the audio pipeline
    // stalled": a play/pause blip the app caused shows up as playing flips
    // next to a Handler/Service/AudioSession line, a rebuffer shows as
    // ready -> buffering -> ready, and a BT-link hiccup shows nothing here.
    _player.playerStateStream.listen((s) {
      debugPrint(
        '[PlayerState] playing=${s.playing} state=${s.processingState.name} '
        'pos=${(_player.position.inMilliseconds / 1000).toStringAsFixed(2)}s',
      );
    });
  }

  /// Subscribe to the player's playback event stream and forward state to
  /// the system MediaSession. If the stream errors or completes unexpectedly,
  /// re-subscribe so system media controls stay alive.
  /// Rate-limited to prevent infinite error loops (e.g. multi-channel audio).
  int _resubscribeCount = 0;
  DateTime _lastResubscribe = DateTime.now();

  // Throttle playback state updates to avoid excessive notification refreshes
  DateTime _lastPlaybackStateUpdate = DateTime.now();
  bool? _lastPlaying;
  ProcessingState? _lastProcessingState;

  // Brief "Saved" flash on the Android Auto bookmark button after a save.
  bool _bookmarkSavedFlash = false;
  Timer? _bookmarkFlashTimer;

  // Keep the media session in buffering while a queued item is taking over.
  // Android maps AudioProcessingState.loading to STATE_CONNECTING, which does
  // not show the buffering animation used for an in-progress media load.
  bool _advanceBuffering = false;
  DateTime? _advanceBufferingUntil;
  Timer? _advanceBufferingMinimumTimer;

  void setAdvanceBuffering(
    bool value, {
    Duration minimumDuration = Duration.zero,
  }) {
    _advanceBufferingMinimumTimer?.cancel();
    _advanceBufferingMinimumTimer = null;
    final changed = _advanceBuffering != value;
    _advanceBuffering = value;
    _advanceBufferingUntil = value ? DateTime.now().add(minimumDuration) : null;
    if (value) _clearAdvanceBufferingIfReady();
    if (!changed && !value) return;
    refreshPlaybackState();
  }

  void _clearAdvanceBufferingIfReady({bool refresh = true}) {
    if (!_advanceBuffering ||
        _player.processingState != ProcessingState.ready) {
      return;
    }
    final remaining =
        _advanceBufferingUntil?.difference(DateTime.now()) ?? Duration.zero;
    if (remaining > Duration.zero) {
      _advanceBufferingMinimumTimer?.cancel();
      _advanceBufferingMinimumTimer = Timer(remaining, () {
        _advanceBufferingMinimumTimer = null;
        _clearAdvanceBufferingIfReady();
      });
      return;
    }
    _advanceBuffering = false;
    _advanceBufferingUntil = null;
    if (refresh) refreshPlaybackState();
  }

  void _subscribePlaybackEvents() {
    _player.playbackEventStream.listen(
      (event) {
        _clearAdvanceBufferingIfReady(refresh: false);
        final state = _transformEvent(event);
        // Only push state on meaningful changes (play/pause, processing state)
        // or at most every 5 seconds for position updates
        final now = DateTime.now();
        final playingChanged = _player.playing != _lastPlaying;
        final processingChanged =
            _player.processingState != _lastProcessingState;
        final elapsed = now.difference(_lastPlaybackStateUpdate);

        if (playingChanged || processingChanged || elapsed.inSeconds >= 5) {
          playbackState.add(state);
          _lastPlaybackStateUpdate = now;
          _lastPlaying = _player.playing;
          _lastProcessingState = _player.processingState;
        }
        // Reset error counter on successful events
        _resubscribeCount = 0;
      },
      onError: (Object e, StackTrace st) {
        if (PlaybackErrorPolicy.isSourceError(e)) {
          debugPrint(
            '[Player] playbackEvent source error - restarting stream: $e',
          );
          AudioPlayerService()._attemptStreamRetry(e);
          return;
        }

        final now = DateTime.now();
        // Reset counter if it's been more than 5 seconds since last error
        if (now.difference(_lastResubscribe).inSeconds > 5) {
          _resubscribeCount = 0;
        }
        _lastResubscribe = now;
        _resubscribeCount++;

        if (_resubscribeCount <= 3) {
          debugPrint(
            '[Player] playbackEvent error ($_resubscribeCount/3) - re-subscribing: $e',
          );
          refreshPlaybackState();
          Future.delayed(const Duration(seconds: 1), _subscribePlaybackEvents);
        } else {
          debugPrint(
            '[Player] playbackEvent error - too many rapid failures, stopping re-subscribe: $e',
          );
          if (PlaybackErrorPolicy.shouldRetryWithTranscode(e)) {
            final service = AudioPlayerService();
            if (service._localSessionMode) {
              service._recoverLocalPlayback(e);
            } else {
              service._retryWithTranscode();
            }
          }
        }
      },
      onDone: () {
        _resubscribeCount++;
        if (_resubscribeCount <= 3) {
          debugPrint(
            '[Player] playbackEvent stream completed ($_resubscribeCount/3) - re-subscribing',
          );
          refreshPlaybackState();
          Future.delayed(const Duration(seconds: 1), _subscribePlaybackEvents);
        } else {
          debugPrint(
            '[Player] playbackEvent stream completed - too many rapid re-subscribes, stopping',
          );
        }
      },
    );
  }

  // The Android Auto speed button shows a pre-baked badge for the current rate.
  // We snap to the nearest 0.05 within the baked range (0.5x..5.0x); every step
  // has a generated ic_speed_*x drawable (rendered from Roboto Bold).
  String _speedBadgeIcon() {
    final speed = _service?.speed ?? _player.speed;
    var rate = (speed * 20).round() / 20; // nearest 0.05
    if (rate < 0.5) rate = 0.5;
    if (rate > 5.0) rate = 5.0;
    // 1.0 -> "1x", 1.2 -> "1_2x", 1.25 -> "1_25x" (matches the generated files).
    final s = rate
        .toStringAsFixed(2)
        .replaceAll(RegExp(r'0+$'), '')
        .replaceAll(RegExp(r'\.$'), '');
    return 'drawable/ic_speed_${s.replaceAll('.', '_')}x';
  }

  PlaybackState _transformEvent(PlaybackEvent event) {
    final playPause = _player.playing ? MediaControl.pause : MediaControl.play;

    final rewindControl = MediaControl(
      androidIcon: 'drawable/ic_skip_back',
      label: 'Back ${_cachedBackSkip}s',
      action: MediaAction.rewind,
    );
    final fastForwardControl = MediaControl(
      androidIcon: 'drawable/ic_skip_forward',
      label: 'Forward ${_cachedForwardSkip}s',
      action: MediaAction.fastForward,
    );

    // Base 3 controls (rewind | play | forward) feed both the phone
    // notification and Android Auto. compactIndices keeps the glanceable
    // notification to just these three.
    final controls = <MediaControl>[
      rewindControl,
      playPause,
      fastForwardControl,
    ];
    final compactIndices = const [0, 1, 2];

    // Extra Android Auto controls (custom actions). On Android 12 and below they
    // show only in AA; on 13+ they also feed the phone's media player. We always
    // add the chapter buttons - they no-op when the item has no chapters - which
    // (a) keeps the layout identical for books and podcasts and (b) since the
    // phone player caps at 5 buttons, makes the two chapter buttons push speed +
    // bookmark to AA-only for every item type. iOS uses the CarPlay Now Playing
    // buttons instead, so these are never added on iOS (lock screen stays as-is).
    if (AppPlatform.isAndroid) {
      final prevChapter = MediaControl.custom(
        androidIcon: 'drawable/ic_widget_prev_chapter',
        label: 'Previous chapter',
        name: 'previousChapter',
      );
      final nextChapter = MediaControl.custom(
        androidIcon: 'drawable/ic_widget_next_chapter',
        label: 'Next chapter',
        name: 'nextChapter',
      );
      final speed = MediaControl.custom(
        androidIcon: _speedBadgeIcon(),
        label: 'Speed',
        name: 'cycleSpeed',
      );
      // Bookmark icon/label briefly flip to a checkmark + "Saved" after a save,
      // as on-screen confirmation for Android Auto (the CarPlay banner equivalent).
      final bookmark = MediaControl.custom(
        androidIcon: _bookmarkSavedFlash
            ? 'drawable/ic_check'
            : 'drawable/ic_bookmark',
        label: _bookmarkSavedFlash ? 'Saved' : 'Bookmark',
        name: 'bookmark',
      );
      // The phone media player (Android 13+) only shows the first 2 of these
      // extras (after rewind/forward); the rest stay Android-Auto-only. Order so
      // the user's chosen pair lands on the phone. Default: chapter skip.
      if (_cachedNotifSpeedBookmark) {
        controls.addAll([speed, bookmark, prevChapter, nextChapter]);
      } else {
        controls.addAll([prevChapter, nextChapter, speed, bookmark]);
      }
    }

    return PlaybackState(
      controls: controls,
      // iOS-only: declaring on Android adds prev/next buttons to the notification.
      systemActions: {
        // Dropping seek locks the scrubber: Android omits ACTION_SEEK_TO and iOS
        // omits changePlaybackPositionCommand, so it shows progress but can't be
        // dragged. The skip (rewind/forward) buttons stay functional.
        if (!_cachedLockSeekBar) MediaAction.seek,
        MediaAction.seekForward,
        MediaAction.seekBackward,
        MediaAction.skipToQueueItem,
        if (AppPlatform.isIOS) MediaAction.skipToNext,
        if (AppPlatform.isIOS) MediaAction.skipToPrevious,
      },
      androidCompactActionIndices: compactIndices,
      processingState: () {
        final mapped = const {
          ProcessingState.idle: AudioProcessingState.idle,
          ProcessingState.loading: AudioProcessingState.loading,
          ProcessingState.buffering: AudioProcessingState.buffering,
          ProcessingState.ready: AudioProcessingState.ready,
          ProcessingState.completed: AudioProcessingState.completed,
        }[_player.processingState]!;
        if (_advanceBuffering) return AudioProcessingState.buffering;
        return mapped;
      }(),
      playing: _player.playing,
      updatePosition: _speedAdjustedPosition(),
      bufferedPosition: _player.bufferedPosition,
      // Report speed as 1.0 because duration and position are already
      // divided by the playback speed. This makes Android Auto, WearOS,
      // and the notification show "real time remaining" instead of raw
      // content duration.
      speed: 1.0,
      queueIndex: _safeCurrentChapterIndex(),
    );
  }

  /// Return the index of the chapter containing the current playback position,
  /// or null if there are no chapters.  Used as queueIndex so Android Auto
  /// highlights the active chapter in the queue view.
  int? _safeCurrentChapterIndex() {
    try {
      if (_service == null) return null;
      final posSec = _player.position.inMilliseconds / 1000.0;
      return ChapterLookup.indexAt(
        _service!.chapters,
        posSec,
        _service!.totalDuration,
      );
    } catch (e) {
      debugPrint('[Handler] _safeCurrentChapterIndex error: $e');
      return null;
    }
  }

  /// Compute the position to report to the MediaSession, divided by playback
  /// speed so that Android Auto / WearOS / notification show "real time
  /// remaining" rather than raw content duration.
  Duration _speedAdjustedPosition() {
    Duration pos;
    if (_service != null && _service!.notifChapterMode) {
      final absPos = _service!.position;
      final chStart = Duration(seconds: _service!.currentChapterStart.round());
      final relative = absPos - chStart;
      pos = relative.isNegative ? Duration.zero : relative;
    } else {
      pos = _service?.position ?? _player.position;
    }
    final speed = _player.speed;
    if (speed <= 0 || speed == 1.0) return pos;
    return Duration(milliseconds: (pos.inMilliseconds / speed).round());
  }

  @override
  Future<void> play() async {
    debugPrint(
      '[Handler] play() called - routing to service (state=${_player.processingState.name})',
    );
    await _logAbsorbDiag('play');
    final entryBt = await AudioPlayerService._isBluetoothAudioConnected();
    if (entryBt) AudioPlayerService._lastPlayedOnBtAt = DateTime.now();
    debugPrint(
      '[ClickDebug] play() entry: ${_clickDebugSnapshot(btNow: entryBt)}',
    );
    // Mirror the click() guard: a raw play() arriving within 5s of a
    // headphone/AA/BT disconnect is almost always the platform echoing a
    // resume command, not the user. Drop it so playback doesn't jump to
    // the phone speaker after the user unplugs or AA tears down.
    if (_noisyPauseAt != null) {
      final elapsed = DateTime.now().difference(_noisyPauseAt!).inMilliseconds;
      if (elapsed < _noisyGuardMs) {
        debugPrint(
          '[Handler] Ignoring phantom play (${elapsed}ms after platform pause)',
        );
        return;
      }
      _noisyPauseAt = null;
    }
    _lastHandlerPlayAt = DateTime.now();
    if (_service != null) {
      await _service!.play();
    } else {
      debugPrint('[Handler] play() - no service ref, using player directly');
      await _player.play();
    }
  }

  @override
  Future<void> pause() async {
    _service?._markPauseRequested();
    debugPrint('[Handler] pause() called - routing to service');
    await _logAbsorbDiag('pause');
    final pauseEntryBt = await AudioPlayerService._isBluetoothAudioConnected();
    debugPrint(
      '[ClickDebug] pause() entry: ${_clickDebugSnapshot(btNow: pauseEntryBt)}',
    );
    _lastHandlerPauseAt = DateTime.now();
    // Android Auto disconnect can dispatch both a MediaButton click and a
    // pause() action simultaneously. The click's 400ms debounce timer would
    // then see playing=false and misinterpret it as "user wants to play",
    // triggering a cold-start restore. Cancel any pending click so the
    // platform-initiated pause wins.
    final clickPending = _clickTimer?.isActive ?? false;
    if (clickPending) {
      debugPrint('[Handler] Cancelling pending click (platform pause)');
      _clickTimer!.cancel();
      _clickCount = 0;
    }
    // Detect BT/AA disconnect by route change: we were playing on BT recently
    // and BT is no longer connected at this pause. Arm the 5s phantom guard
    // so any echoed resume command from the dead route gets dropped. We do
    // NOT stamp for plain user pauses (notification, lock screen, in-app)
    // because that would block their immediate follow-up play. becomingNoisy
    // covers the headphone-unplug path independently.
    if (!_inClickResolver) {
      final lastBt = AudioPlayerService._lastPlayedOnBtAt;
      final btJustWent = lastBt != null && !pauseEntryBt;
      if (btJustWent) {
        _noisyPauseAt = DateTime.now();
        _noisyGuardMs = 5000;
      }
    }
    if (_service != null) {
      await _service!.pause();
    } else {
      await _player.pause();
    }
  }

  @override
  Future<void> seek(Duration position) async {
    debugPrint('[Handler] seek(${position.inSeconds}s)');
    if (_service != null) {
      final speed = _player.speed;
      final realPos = speed > 0 && speed != 1.0
          ? Duration(milliseconds: (position.inMilliseconds * speed).round())
          : position;
      final absPos = _service!.notifChapterMode
          ? realPos + Duration(seconds: _service!.currentChapterStart.round())
          : realPos;
      await _service!.seekTo(absPos);
    } else {
      await _player.seek(position);
    }
  }

  @override
  Future<void> stop() async {
    // Don't call super.stop() - it deactivates the MediaSession, and on some
    // devices (Android 16+) the system never re-routes BT media buttons /
    // notification controls to a reactivated session. Same reasoning as
    // onTaskRemoved below: keep the session alive so external controls
    // recover when the user comes back. Just stop the player.
    //
    // Alpha: stack trace tells us who is calling stop() so we can decide if
    // any caller deserves a true teardown. Strip [Handler] stop trace before
    // beta.
    debugPrint(
      '[Handler] stop() - keeping MediaSession alive '
      '(playing=${_player.playing}, processingState=${_player.processingState.name}, '
      'hasService=${_service != null})',
    );
    debugPrint('[Handler] stop() trace:\n${StackTrace.current}');
    try {
      await _player.stop();
    } catch (e) {
      debugPrint('[Handler] stop() player.stop error: $e');
    }
  }

  /// Called when the user swipes the app away from recents.
  ///
  /// Only pause instead of stopping - the 10-minute pause timeout already
  /// handles cleanup (server session + audio focus). Calling stop() here
  /// deactivates the MediaSession, and on some devices (Android 16+) the
  /// system never re-routes BT media buttons to a reactivated session,
  /// leaving earbud controls permanently broken until reboot.
  @override
  Future<void> onTaskRemoved() async {
    debugPrint('[Handler] onTaskRemoved - app swiped away');
    // Don't stop cast playback when app is swiped away
    if (ChromecastService().isCasting) return;
    if (_service != null) {
      await _service!.pause();
    } else {
      await _player.pause();
    }
    // Don't call super.onTaskRemoved() - it calls stop() which deactivates
    // the MediaSession and breaks BT media button routing on restart.
  }

  @override
  Future<void> fastForward() async {
    debugPrint('[Handler] fastForward() - seeking forward');
    final skipAmount = await PlayerSettings.getEffectiveForwardSkip(
      libraryId: _service?.currentLibraryId,
    );
    debugPrint(
      '[SkipDebug] fastForward: lib=${_service?.currentLibraryId} amount=${skipAmount}s',
    );
    if (_service != null) {
      await _service!.skipForward(skipAmount);
    } else {
      final adjusted = (skipAmount * _player.speed).round();
      await _player.seek(_player.position + Duration(seconds: adjusted));
    }
  }

  @override
  Future<void> rewind() async {
    debugPrint('[Handler] rewind() - seeking back');
    final skipAmount = await PlayerSettings.getEffectiveBackSkip(
      libraryId: _service?.currentLibraryId,
    );
    debugPrint(
      '[SkipDebug] rewind: lib=${_service?.currentLibraryId} amount=${skipAmount}s',
    );
    if (_service != null) {
      await _service!.skipBackward(skipAmount);
    } else {
      final adjusted = (skipAmount * _player.speed).round();
      var pos = _player.position - Duration(seconds: adjusted);
      if (pos < Duration.zero) pos = Duration.zero;
      await _player.seek(pos);
    }
  }

  // iOS BT (AirPods, steering wheel) routes track-skip through these.
  @override
  Future<void> skipToNext() => fastForward();

  @override
  Future<void> skipToPrevious() => rewind();

  // Custom click handler with proper multi-press detection
  Timer? _clickTimer;
  int _clickCount = 0;
  DateTime? _hardwareButtonTime; // cooldown after hardware next/prev
  DateTime? _noisyPauseAt; // suppress clicks for a window after BT disconnect
  int _noisyGuardMs = 5000;
  // Keycode of the media button event that arrived at the most recent click().
  // Read from the [AbsorbDiag] snapshot at click arrival and consumed by the
  // 400ms resolver to honor PAUSE/PLAY intent instead of blindly toggling -
  // Android Auto sends KEYCODE_MEDIA_PAUSE when the user switches to Radio,
  // and the old toggle path bounced it back as a phantom resume (GH #243).
  int? _lastClickKeyCode;
  String? _lastClickKeyPkg;
  // When the debounce-free resume last fired, so a second press arriving just
  // after it is still read as a double-press skip rather than a fresh click.
  DateTime? _fastPathPlayAt;
  // True while the click resolver is synchronously calling pause()/play().
  // pause() uses this to skip stamping _noisyPauseAt for click-driven pauses,
  // so legit user pause-then-play flows are not blocked by the disconnect guard.
  bool _inClickResolver = false;
  // [ClickDebug] — timestamp of the last Handler-level pause() call.
  // Used to correlate phantom play/click commands with a preceding pause.
  DateTime? _lastHandlerPauseAt;
  // [ClickDebug] — timestamp of the last Handler-level play() call.
  // Used to spot the variant-3 phantom-resume fingerprint: click-initiated
  // play followed by a raw pause a few seconds later (AA disconnect tearing
  // down after a spurious transport event).
  DateTime? _lastHandlerPlayAt;

  /// [ClickDebug] — one-line snapshot of state around a media-button event.
  /// Helps diagnose phantom clicks after Android Auto disconnect.
  ///
  /// `btNow` should be pre-fetched async by the caller when available so
  /// the AA-disconnect heuristic can be evaluated. When null, that flag
  /// is reported as `unknown`.
  String _clickDebugSnapshot({bool? btNow}) {
    final now = DateTime.now();
    int sincePrevPauseMs = -1;
    if (_lastHandlerPauseAt != null) {
      sincePrevPauseMs = now.difference(_lastHandlerPauseAt!).inMilliseconds;
    }
    int sincePrevPlayMs = -1;
    if (_lastHandlerPlayAt != null) {
      sincePrevPlayMs = now.difference(_lastHandlerPlayAt!).inMilliseconds;
    }
    int sinceForegroundMs = -1;
    if (AudioPlayerService._lastForegroundAt != null) {
      sinceForegroundMs = now
          .difference(AudioPlayerService._lastForegroundAt!)
          .inMilliseconds;
    }
    int sinceNoisyPauseMs = -1;
    if (_noisyPauseAt != null) {
      sinceNoisyPauseMs = now.difference(_noisyPauseAt!).inMilliseconds;
    }
    final backgrounded = _service?.isBackgrounded;
    // Variant-3 fingerprint: raw pause fires within 5s of a click-initiated
    // play while still playing in background. Flag it so the pause log line
    // is self-describing without having to cross-reference timestamps.
    final phantomSuspect =
        sincePrevPlayMs >= 0 &&
        sincePrevPlayMs < 5000 &&
        _player.playing &&
        (backgrounded ?? false);
    // AA-disconnect fingerprint: BT/AA was the audio route within the last
    // 10 min, isn't anymore, and the click came in while bg + not playing.
    int sinceBtMs = -1;
    final lastBt = AudioPlayerService._lastPlayedOnBtAt;
    if (lastBt != null) sinceBtMs = now.difference(lastBt).inMilliseconds;
    final String aaDisconnect;
    if (btNow == null) {
      aaDisconnect = 'unknown';
    } else {
      final fired =
          lastBt != null && !btNow && sinceBtMs >= 0 && sinceBtMs < 600000;
      aaDisconnect = fired ? 'true' : 'false';
    }
    return 'bg=$backgrounded, sincePrevPauseMs=$sincePrevPauseMs, '
        'sincePrevPlayMs=$sincePrevPlayMs, '
        'sinceForegroundMs=$sinceForegroundMs, '
        'sinceNoisyPauseMs=$sinceNoisyPauseMs, '
        'playing=${_player.playing}, '
        'processingState=${_player.processingState.name}, '
        'noisyPause=${AudioPlayerService._noisyPause}, '
        'phantomSuspect=$phantomSuspect, '
        'sinceBtMs=$sinceBtMs, btNow=${btNow ?? 'unknown'}, '
        'aaDisconnectSuspect=$aaDisconnect';
  }

  @override
  Future<void> click([MediaButton button = MediaButton.media]) async {
    debugPrint(
      '[Handler] click(button=$button) count=${_clickCount + 1} playing=${_player.playing}',
    );
    final diagSnap = await _absorbDiagSnapshot();
    _logAbsorbDiagFromSnapshot('click', diagSnap);
    // Pre-fetch BT-route state so the snapshot can fill in the AA-disconnect
    // heuristic and the suppression branch below has a value to test against.
    final btNow = await AudioPlayerService._isBluetoothAudioConnected();
    final snapshot = _clickDebugSnapshot(btNow: btNow);
    debugPrint('[ClickDebug] click arrival (button=$button): $snapshot');
    _service?._logEvent(
      PlaybackEventType.clickDebounce,
      detail: 'button=$button | $snapshot',
    );

    if (button != MediaButton.media) {
      // Hardware next/prev button — set cooldown to ignore phantom media click
      _hardwareButtonTime = DateTime.now();
      if (button == MediaButton.next) {
        debugPrint('[Handler] Hardware NEXT button');
        await fastForward();
      } else if (button == MediaButton.previous) {
        debugPrint('[Handler] Hardware PREV button');
        await rewind();
      }
      return;
    }

    // Ignore phantom media click that follows hardware next/prev within 500ms
    if (_hardwareButtonTime != null) {
      final elapsed = DateTime.now()
          .difference(_hardwareButtonTime!)
          .inMilliseconds;
      if (elapsed < 500) {
        debugPrint(
          '[Handler] Ignoring phantom media click (${elapsed}ms after hardware button)',
        );
        _hardwareButtonTime = null;
        return;
      }
      _hardwareButtonTime = null;
    }

    // Suppress phantom play commands within 5s of a BT/auto disconnect
    if (_noisyPauseAt != null) {
      final elapsed = DateTime.now().difference(_noisyPauseAt!).inMilliseconds;
      if (elapsed < _noisyGuardMs) {
        debugPrint(
          '[Handler] Ignoring phantom click (${elapsed}ms after noisy pause)',
        );
        return;
      }
      _noisyPauseAt = null;
    }

    // AA-disconnect phantom: a delayed MediaButton.media event arrives in
    // background, not playing, after we last played on BT/AA — and BT is
    // gone now. On devices where AA disconnect doesn't fire becomingNoisy
    // (Pixel 10 Pro / Android 16 observed), this is the only way to catch
    // the lingering MediaSession resume that the OS sends minutes later.
    final lastBt = AudioPlayerService._lastPlayedOnBtAt;
    final bg = _service?.isBackgrounded ?? false;
    if (bg && !_player.playing && lastBt != null && !btNow) {
      final ageMs = DateTime.now().difference(lastBt).inMilliseconds;
      if (ageMs < 600000) {
        debugPrint(
          '[Handler] Ignoring phantom click after AA/BT disconnect '
          '(${ageMs}ms since last BT-on, btNow=false, bg=true, playing=false)',
        );
        _service?._logEvent(
          PlaybackEventType.clickDebounce,
          detail: 'phantom AA/BT click suppressed | sinceBtMs=$ageMs',
        );
        // Re-arm the 5s noisy guard so a follow-up click in the same
        // burst is also ignored, matching the BT-disconnect suppression flow.
        _noisyPauseAt = DateTime.now();
        _noisyGuardMs = 5000;
        return;
      }
    }

    // Stash the keycode for the resolver if it belongs to this click. Only
    // do this for clicks that actually count - early-return guards above
    // skip the stash so they can't poison the keycode of a click that does
    // make it to the resolver. 500ms cap is a safety margin; typical
    // keyAgeMs from the Java side is 0-2ms.
    if (diagSnap != null) {
      final age = diagSnap['lastKeyAgeMs'];
      final kc = diagSnap['lastKeyCode'];
      if (age is int && age >= 0 && age < 500 && kc is int && kc != 0) {
        _lastClickKeyCode = kc;
        final pkg = diagSnap['lastKeyPkg'];
        _lastClickKeyPkg = pkg is String ? pkg : null;
      }
    }

    // Second half of the fast path below: a press landing right after an
    // instant resume is the double-press the debounce would normally have
    // caught, so honour it as a skip. We are already playing by now, which is
    // exactly the state a double-press-to-skip expects.
    final fastPlay = _fastPathPlayAt;
    if (fastPlay != null &&
        DateTime.now().difference(fastPlay) < const Duration(milliseconds: 600)) {
      _fastPathPlayAt = null;
      debugPrint('[Handler] -> second press after instant play -> SKIP FORWARD');
      await fastForward();
      return;
    }

    // Resume from an explicit MEDIA_PLAY does not wait for the multi-press
    // window. The 400ms timer is punctual while audio runs - every pause press
    // resolves in ~407ms - but once paused the process gets throttled and the
    // same timer fired 7-8 SECONDS late (measured 2026-08-13, with total log
    // silence in the gap). The keypress itself always arrives instantly.
    //
    // Deliberately play-only: pause never had the latency, and pausing
    // instantly would eat the second press of a double-press-to-skip, which is
    // the gesture people use while listening. PLAY_PAUSE (85) and HEADSETHOOK
    // stay on the debounce too - for a single-button remote the second press is
    // genuinely ambiguous until the window closes.
    if (_clickCount == 0 &&
        !(_clickTimer?.isActive ?? false) &&
        _lastClickKeyCode == 126 &&
        !_player.playing) {
      _lastClickKeyCode = null;
      _inClickResolver = true;
      try {
        debugPrint('[Handler] -> MEDIA_PLAY while paused, no debounce -> PLAY');
        await play();
      } finally {
        _inClickResolver = false;
      }
      _fastPathPlayAt = DateTime.now();
      return;
    }

    _clickCount++;
    _clickTimer?.cancel();
    _clickTimer = Timer(const Duration(milliseconds: 400), () async {
      final count = _clickCount;
      _clickCount = 0;
      debugPrint(
        '[Handler] click resolved: count=$count playing=${_player.playing}',
      );
      final resolveBt = await AudioPlayerService._isBluetoothAudioConnected();
      debugPrint(
        '[ClickDebug] click resolve (count=$count): ${_clickDebugSnapshot(btNow: resolveBt)}',
      );
      switch (count) {
        case 1:
          // Sleep-timer snooze (GH #333): during the wind-down window a
          // single press resets the timer instead of pausing. Sits after all
          // the phantom guards so a spurious AA/BT click can't reset it, and
          // inside the resolver so double/triple presses still skip.
          if (await SleepTimerService().snoozeFromMediaButton()) {
            _lastClickKeyCode = null;
            debugPrint('[Handler] → single press consumed by sleep timer snooze');
            break;
          }
          _inClickResolver = true;
          try {
            // Honor the actual keycode the system dispatched when we can.
            // audio_service collapses MEDIA_PLAY / MEDIA_PAUSE / PLAY_PAUSE /
            // HEADSETHOOK all into MediaButton.media, but Android Auto sends
            // MEDIA_PAUSE specifically when the user switches to another media
            // app - blindly toggling there resumes us right after we paused
            // (GH #243). For the unambiguous play / pause keycodes, follow the
            // intent. PLAY_PAUSE / HEADSETHOOK / unknown / stale stay as
            // toggles so single-button BT remotes keep working.
            const keycodeMediaPlay = 126;
            const keycodeMediaPause = 127;
            final kc = _lastClickKeyCode;
            final pkg = _lastClickKeyPkg;
            _lastClickKeyCode = null;
            _lastClickKeyPkg = null;
            final sincePause = _lastHandlerPauseAt == null
                ? null
                : DateTime.now().difference(_lastHandlerPauseAt!);
            // A key that reaches us while something else is audible was
            // probably meant for that something else (an earbud pausing a
            // video) - unless we paused a moment ago, in which case the
            // user is toggling us back and the other sound is beside the
            // point. A beta tester with a car link could not resume from
            // his headset or his widget for two hours because of this.
            Future<bool> meantForOtherAudio() async {
              if (_isOwnPackage(pkg)) return false;
              if (sincePause != null && sincePause < const Duration(minutes: 3)) {
                return false;
              }
              return _otherAudioActive();
            }
            if (kc == keycodeMediaPause) {
              if (_player.playing) {
                debugPrint('[Handler] → single press (MEDIA_PAUSE) → PAUSE');
                await pause();
              } else if (_isCarPackage(pkg) ||
                  (pkg == null && await _carClientRecentlySeen())) {
                // A car never means play with a pause key: Android Auto
                // repeats MEDIA_PAUSE right after we pause (#243), and sends
                // it again when the head unit switches to its radio, which
                // started the book back up over the radio. Its own play
                // button comes in as a play command, not this key.
                debugPrint(
                  '[Handler] -> single press (MEDIA_PAUSE while paused, car, '
                  '${sincePause?.inMilliseconds ?? -1}ms after pausing) -> no-op',
                );
              } else if (await meantForOtherAudio()) {
                debugPrint(
                  '[Handler] -> single press (MEDIA_PAUSE while paused, other audio active) -> no-op',
                );
              } else {
                // Some BT headsets (Shokz seen in the wild) send MEDIA_PAUSE
                // for a play press when their idea of our state went stale.
                debugPrint(
                  '[Handler] -> single press (MEDIA_PAUSE while paused, pkg=$pkg) -> PLAY',
                );
                await play();
              }
            } else if (kc == keycodeMediaPlay) {
              if (!_player.playing) {
                debugPrint('[Handler] → single press (MEDIA_PLAY) → PLAY');
                await play();
              } else {
                debugPrint(
                  '[Handler] → single press (MEDIA_PLAY while playing) → no-op',
                );
              }
            } else if (_player.playing) {
              debugPrint('[Handler] → single press → PAUSE');
              await pause();
            } else if (await meantForOtherAudio()) {
              debugPrint(
                '[Handler] -> single press while paused, other audio active -> no-op',
              );
            } else {
              debugPrint('[Handler] → single press (pkg=$pkg) → PLAY');
              await play();
            }
          } finally {
            _inClickResolver = false;
          }
          break;
        case 2:
          debugPrint('[Handler] → double press → SKIP FORWARD');
          await fastForward();
          break;
        case 3:
        default:
          debugPrint('[Handler] → triple press → SKIP BACK');
          await rewind();
          break;
      }
    });
  }

  /// Cancel any pending media-button click so a BT disconnect doesn't
  /// accidentally resume playback on the phone speaker. [guardMs] is how long
  /// a play that follows is treated as the platform echoing a resume.
  void cancelPendingClick({int guardMs = 5000}) {
    _noisyPauseAt = DateTime.now();
    _noisyGuardMs = guardMs;
    if (_clickTimer?.isActive ?? false) {
      debugPrint('[Handler] Cancelling pending click (noisy pause)');
      _clickTimer!.cancel();
      _clickCount = 0;
    }
  }

  @override
  Future<void> setSpeed(double speed) => _player.setSpeed(speed);

  @override
  Future<dynamic> customAction(
    String name, [
    Map<String, dynamic>? extras,
  ]) async {
    debugPrint('[Handler] customAction($name)');
    switch (name) {
      case 'nextChapter':
        if (_service != null) await _service!.skipToNextChapter();
        break;
      case 'previousChapter':
        if (_service != null) await _service!.skipToPreviousChapter();
        break;
      case 'cycleSpeed':
        await _cycleSpeed();
        break;
      case 'bookmark':
        return await _bookmarkCurrentPosition();
    }
  }

  /// Step playback speed up to the next configured preset, wrapping back to the
  /// slowest once past the top. Used by the CarPlay / Android Auto speed button.
  Future<void> _cycleSpeed() async {
    final presets = await PlayerSettings.getSpeedPresets();
    if (presets.isEmpty) return;
    final cur = _service?.speed ?? _player.speed;
    var next = presets.first; // wrap to slowest when already at/above the top
    for (final p in presets) {
      if (p > cur + 0.001) {
        next = p;
        break;
      }
    }
    if (_service != null) {
      await _service!.setSpeed(next);
    } else {
      await setSpeed(next);
    }
  }

  /// Save a bookmark at the current position, mirroring the in-app car-mode
  /// button (chapter title as the label, pushed to the server via the API).
  /// A podcast episode is bookmarked under its own key, which keeps it on the
  /// device - ABS bookmarks have nowhere to put an episode id.
  Future<bool> _bookmarkCurrentPosition() async {
    final svc = _service;
    if (svc == null) return false;
    final itemId = svc.currentItemId;
    if (itemId == null) return false;
    final pos = svc.position.inMilliseconds / 1000.0;
    final chTitle = svc.currentChapter?['title'] as String?;
    await BookmarkService().addBookmark(
      itemId: playbackDownloadKey(itemId, svc.currentEpisodeId),
      positionSeconds: pos,
      title: (chTitle != null && chTitle.isNotEmpty) ? chTitle : 'Bookmark',
      api: svc.currentApi,
    );
    if (AppPlatform.isAndroid) {
      // Flash a checkmark on the Android Auto bookmark button for ~2s. iOS gets
      // its confirmation via the CarPlay banner instead.
      _bookmarkSavedFlash = true;
      refreshPlaybackState();
      _bookmarkFlashTimer?.cancel();
      _bookmarkFlashTimer = Timer(const Duration(seconds: 2), () {
        _bookmarkSavedFlash = false;
        refreshPlaybackState();
      });
    }
    return true;
  }

  // ─── Chapter queue (for Android Auto queue button) ─────────────────

  /// Populate the MediaSession queue with chapter entries so AA shows
  /// a chapter list via the queue button on the Now Playing screen.
  void updateChaptersQueue(List<dynamic> chapters) {
    if (chapters.isEmpty) {
      queue.add(const []);
      return;
    }
    final items = chapters.asMap().entries.map((e) {
      final ch = e.value as Map<String, dynamic>;
      final start = (ch['start'] as num?)?.toDouble() ?? 0;
      final end = (ch['end'] as num?)?.toDouble() ?? 0;
      return MediaItem(
        id: 'chapter_${e.key}',
        title: ch['title'] as String? ?? 'Chapter ${e.key + 1}',
        duration: Duration(milliseconds: ((end - start) * 1000).round()),
      );
    }).toList();
    queue.add(items);
  }

  @override
  Future<void> skipToQueueItem(int index) async {
    debugPrint('[Handler] skipToQueueItem($index)');
    if (_service == null) return;
    final chapters = _service!.chapters;
    if (index < 0 || index >= chapters.length) return;
    final start = (chapters[index]['start'] as num?)?.toDouble() ?? 0;
    await _service!.seekTo(Duration(milliseconds: (start * 1000).round()));
  }

  // ─── Android Auto browse tree ──────────────────────────────────────

  final _autoService = AndroidAutoService();

  @override
  Future<List<MediaItem>> getChildren(
    String parentMediaId, [
    Map<String, dynamic>? options,
  ]) async {
    debugPrint('[Handler] getChildren($parentMediaId)');
    if (AppPlatform.isAndroid) unawaited(_maybeAutoplayOnCarConnect());
    // Don't await refresh() here — getChildrenOf() handles it:
    // downloads are populated instantly, server data loads in background.
    return _autoService.getChildrenOf(parentMediaId);
  }

  DateTime? _lastCarBrowseSeen;

  /// GH #371: opt-in autoplay when Android Auto connects with nothing loaded.
  ///
  /// A browse request alone isn't a car - Bluetooth stereos browse over AVRCP
  /// too - so this trusts the Java-side gearhead stamp, and only a stamp a few
  /// seconds old counts as "the car just connected". A book already loaded
  /// means the session is alive and Android Auto's own resume setting owns the
  /// warm case (and it keeps a deliberate mid-drive pause from being undone by
  /// a later browse). Browses during the same drive keep refreshing
  /// [_lastCarBrowseSeen], so only a fresh stamp after a quiet gap fires.
  Future<void> _maybeAutoplayOnCarConnect() async {
    try {
      final service = _service;
      if (service == null) return;
      final snap = await _absorbDiagSnapshot();
      final age = snap?['carClientAgeMs'];
      final carFresh = age is int && age >= 0 && age < 15000;
      if (!carFresh) return;
      final now = DateTime.now();
      final last = _lastCarBrowseSeen;
      _lastCarBrowseSeen = now;
      final isNewConnection =
          last == null || now.difference(last) > const Duration(minutes: 5);
      if (!isNewConnection) return;
      if (service.hasBook) return;
      if (!await PlayerSettings.getAutoplayOnCarConnect()) return;
      // Let the browse tree and session setup settle before starting audio.
      await Future.delayed(const Duration(milliseconds: 1500));
      if (service.hasBook || service.isPlaying) return;
      final restore = AudioPlayerService.onColdStartPlayRequested;
      if (restore == null) return;
      debugPrint('[AutoPlay] Android Auto connected - resuming last played');
      await restore();
    } catch (e) {
      debugPrint('[AutoPlay] car-connect autoplay failed: $e');
    }
  }

  @override
  Future<MediaItem?> getMediaItem(String mediaId) async {
    debugPrint('[Handler] getMediaItem($mediaId)');
    return _autoService.getMediaItem(mediaId);
  }

  @override
  Future<List<MediaItem>> search(
    String query, [
    Map<String, dynamic>? extras,
  ]) async {
    debugPrint('[Handler] search("$query")');
    return _autoService.search(query);
  }

  @override
  Future<void> prepareFromMediaId(
    String mediaId, [
    Map<String, dynamic>? extras,
  ]) async {
    debugPrint('[Handler] prepareFromMediaId($mediaId)');
    await _playFromAutoMediaId(mediaId);
  }

  @override
  Future<void> playFromMediaId(
    String mediaId, [
    Map<String, dynamic>? extras,
  ]) async {
    debugPrint('[Handler] playFromMediaId($mediaId)');
    await _playFromAutoMediaId(mediaId);
  }

  Future<void> _playFromAutoMediaId(String mediaId) async {
    final absId = AutoMediaIds.absItemId(mediaId);
    if (absId == null) {
      debugPrint('[Handler] Invalid media ID for playback: $mediaId');
      return;
    }

    if (_service == null) {
      debugPrint('[Handler] No service bound — cannot play');
      return;
    }

    final api = await _autoService.getApi();
    if (api == null) {
      debugPrint('[Handler] No API credentials — cannot play');
      return;
    }

    // Detect podcast episodes via compound key (showId-episodeId, length > 36)
    final isEpisode = absId.length > 36;
    final showId = isEpisode ? absId.substring(0, 36) : null;
    final episodeId = isEpisode ? absId.substring(37) : null;
    // For API calls, use the show ID (not compound key) for podcast episodes
    final apiItemId = showId ?? absId;

    // Try to find in cached entries first
    var entry = _autoService.findEntry(absId);

    // If not in AA cache, check if the item is downloaded locally.
    // This handles cold-start scenarios where the AA browse tree hasn't
    // been populated yet but the user taps a downloaded item.
    if (entry == null) {
      final ds = DownloadService();
      if (ds.isDownloaded(absId)) {
        debugPrint(
          '[Handler] Item not in AA cache but downloaded locally: $absId',
        );
        final dl = ds.getInfo(absId);
        double duration = 0;
        List<dynamic> chapters = [];
        if (dl.sessionData != null) {
          try {
            final session = jsonDecode(dl.sessionData!) as Map<String, dynamic>;
            duration = (session['duration'] as num?)?.toDouble() ?? 0;
            chapters = session['chapters'] as List<dynamic>? ?? [];
          } catch (_) {}
        }
        entry = AutoBookEntry(
          id: absId,
          title: dl.title ?? 'Unknown',
          author: dl.author ?? '',
          duration: duration,
          coverUrl: AndroidAutoService.localCoverUri(apiItemId),
          chapters: chapters,
          episodeId: episodeId,
          showId: showId,
          libraryId: dl.libraryId,
        );
      }
    }

    // If still not found, fetch the item details from server
    if (entry == null) {
      debugPrint('[Handler] Item not cached, fetching from server: $apiItemId');
      try {
        final response = await api.getLibraryItem(apiItemId);
        if (response != null) {
          final media = response['media'] as Map<String, dynamic>?;
          final metadata = media?['metadata'] as Map<String, dynamic>? ?? {};

          if (isEpisode) {
            // Find the specific episode in the show's episode list
            final episodes = media?['episodes'] as List<dynamic>? ?? [];
            final ep = episodes.cast<Map<String, dynamic>?>().firstWhere(
              (e) => e?['id'] == episodeId,
              orElse: () => null,
            );
            if (ep != null) {
              entry = AutoBookEntry(
                id: absId,
                title: ep['title'] as String? ?? 'Episode',
                author: metadata['title'] as String? ?? '', // show name
                duration: (ep['duration'] as num?)?.toDouble() ?? 0,
                coverUrl: AndroidAutoService.localCoverUri(apiItemId),
                chapters: ep['chapters'] as List<dynamic>? ?? [],
                episodeId: episodeId,
                showId: showId,
                libraryId: response['libraryId'] as String?,
              );
            }
          } else {
            entry = AutoBookEntry(
              id: absId,
              title: metadata['title'] as String? ?? 'Unknown',
              author: metadata['authorName'] as String? ?? '',
              duration: (media?['duration'] as num?)?.toDouble() ?? 0,
              coverUrl: AndroidAutoService.localCoverUri(absId),
              chapters: media?['chapters'] as List<dynamic>? ?? [],
              libraryId: response['libraryId'] as String?,
            );
          }
        }
      } catch (e) {
        debugPrint('[Handler] Error fetching item: $e');
      }
    }

    if (entry == null) {
      debugPrint('[Handler] Item not found: $absId');
      return;
    }

    debugPrint(
      '[Handler] Android Auto play: "${entry.title}" by ${entry.author}',
    );

    // Always generate a fresh HTTP cover URL for Now Playing — api is
    // available here, so use it directly rather than relying on the cached
    // entry.coverUrl (which may be a content:// URI when offline).
    final nowPlayingCoverUrl = api.getCoverUrl(apiItemId, width: 400);

    await _service!.playItem(
      api: api,
      itemId: apiItemId,
      title: entry.title,
      author: entry.author,
      coverUrl: nowPlayingCoverUrl,
      totalDuration: entry.duration,
      chapters: entry.chapters,
      startTime: entry.currentTime ?? 0,
      episodeId: entry.episodeId,
      episodeTitle: entry.episodeId != null ? entry.title : null,
      libraryId: entry.libraryId,
    );
  }
}

// ─── Singleton service ───

class AudioPlayerService extends ChangeNotifier {
  static final AudioPlayerService _instance = AudioPlayerService._();
  factory AudioPlayerService() => _instance;
  AudioPlayerService._();

  /// Called when a book completes naturally (before player state is cleared).
  /// Register via [setOnBookFinishedCallback]. Used by LibraryProvider to
  /// update local finished state immediately without waiting for a server refresh.
  static void Function(String itemId)? _onBookFinishedCallback;
  // Buffers the most recent completion key when the callback fires before
  // LibraryProvider is ready to handle it (e.g. Android Auto cold-start).
  // LibraryProvider calls [drainPendingBookFinished] once its absorbing cache
  // is loaded so auto-advance has the state it needs.
  static String? _pendingBookFinishedKey;
  /// A book started or resumed from the app's own controls.
  static void Function(String itemId)? onAppPlay;

  static void setOnBookFinishedCallback(void Function(String itemId)? cb) {
    _onBookFinishedCallback = cb;
  }

  // Pre-buffer callback. AudioPlayerService asks LibraryProvider for the next
  // manual-queue item ~15s before current ends, so the next AVQueuePlayer item
  // is already in the queue when the current one finishes. iOS auto-advances
  // natively (no fresh setAudioSource in background, so iOS keeps granting
  // audio output). The map must contain at least: itemId, title, author,
  // duration, and either localPaths or audioTracks.
  static Future<Map<String, dynamic>?> Function(String currentItemId)?
  _onPeekNextItemCallback;
  static void setOnPeekNextItemCallback(
    Future<Map<String, dynamic>?> Function(String)? cb,
  ) {
    _onPeekNextItemCallback = cb;
  }

  // Fired when the AVQueuePlayer natively auto-advances from the current item
  // to a pre-buffered next item. LibraryProvider uses this to mark the old
  // item finished WITHOUT triggering its normal auto-advance flow (which would
  // call playItem and rebuild the source, defeating the pre-buffer).
  static void Function(String oldItemId)? _onAutoQueueAdvancedCallback;
  static void setOnAutoQueueAdvancedCallback(void Function(String)? cb) {
    _onAutoQueueAdvancedCallback = cb;
  }

  static void drainPendingBookFinished() {
    final cb = _onBookFinishedCallback;
    final pending = _pendingBookFinishedKey;
    if (cb == null || pending == null) return;
    _pendingBookFinishedKey = null;

    // If something is loaded in the player by the time the drain fires, the
    // user already moved on (manually selected a new item in AA, or is paused
    // mid-book). Replaying the completion here would auto-advance on top of
    // their current state — the "phantom resume after pause" regression.
    // Drop the stale completion instead.
    final loaded = _instance._currentItemId;
    if (loaded != null) {
      debugPrint(
        '[Player] Dropping stale book-finished drain (player has item=$loaded, buffered key=$pending)',
      );
      return;
    }

    debugPrint('[Player] Draining buffered book-finished key=$pending');
    cb(pending);
  }

  /// Called when a new item starts playing. Used by LibraryProvider to trigger
  /// rolling downloads for the next items in a series/podcast.
  static Future<void> Function(String key, double duration)?
  _onPlayStartedCallback;
  static void setOnPlayStartedCallback(
    Future<void> Function(String key, double duration)? cb,
  ) {
    _onPlayStartedCallback = cb;
  }

  /// Called when a podcast episode starts playing. Used by AppShell to
  /// auto-navigate to the Absorbing tab.
  static void Function()? _onEpisodePlayStartedCallback;
  static void setOnEpisodePlayStartedCallback(void Function()? cb) {
    _onEpisodePlayStartedCallback = cb;
  }

  /// Called when playback state changes (playing/paused). Used by
  /// LibraryProvider for battery-saving socket lifecycle.
  static void Function(bool isPlaying)? _onPlaybackStateChangedCallback;
  static void setOnPlaybackStateChangedCallback(
    void Function(bool isPlaying)? cb,
  ) {
    _onPlaybackStateChangedCallback = cb;
  }

  /// Invoked when `play()` fires on a cold-started service that has no
  /// current item loaded (typical headphone / lock-screen tap after the OS
  /// killed the app). Registered by main.dart to delegate the restore to
  /// HomeWidgetService (which has the item-fetch + ApiService construction
  /// logic), avoiding a circular import.
  static Future<void> Function()? onColdStartPlayRequested;

  static AudioPlayerHandler? _handler;
  static AudioPlayerHandler? get handler => _handler;
  static Completer<void> _initCompleter = Completer<void>();
  AudioPlayer? get _player => _handler?.player;

  String? _currentItemId;
  String? _currentTitle;
  String? _currentAuthor;
  String? _currentCoverUrl;
  double _totalDuration = 0;
  // The item's metadata duration as passed to playItem. _totalDuration gets
  // replaced by the playback session's track-sum once a stream opens, and the
  // two can disagree by minutes when the server's metadata is off - but the
  // in-app cards display the metadata number, so time surfaces that need to
  // match them (the iOS widget) read this instead.
  double _metaDuration = 0;
  List<dynamic> _chapters = [];
  ApiService? _api;
  ApiService? get currentApi => _api;
  String? _playbackSessionId;

  /// The server session this phone is playing on, so its own syncs echoed
  /// back over the socket can be told apart from another device's.
  String? get playbackSessionId => _playbackSessionId;

  // A source swap started by pausing. A seek waits for it: the swap reloads
  // at the spot it saw, so a seek that landed first was undone (GH #433).
  Future<void>? _pauseSwap;

  /// Phase 1.7: latest streaming URLs (with auth token already in the
  /// query string) and custom HTTP headers needed by reverse proxies like
  /// Cloudflare Access. Stashed to the iOS app group on each player update
  /// so the native widget core can keep playing if Flutter dies.
  List<String> _activeStreamUrls = const [];
  Map<String, String> _activeStreamHeaders = const {};
  List<String> get activeStreamUrls => _activeStreamUrls;
  Map<String, String> get activeStreamHeaders => _activeStreamHeaders;
  bool _isOfflineMode = false;

  /// True while the current play started from downloaded files and is reporting
  /// to the server via the client-owned LOCAL session model (GH #276/#280)
  /// instead of a live `/play` session. Position still syncs via /me/progress.
  bool _localSessionMode = false;

  // Set when a loadOnly playItem skipped starting the local session; the
  // first real play() begins it, so listening time still gets recorded.
  ({
    String progressKey,
    String itemId,
    String? episodeId,
    double duration,
    String title,
    String author,
    bool streamed,
  })? _pendingLoadOnlySession;

  /// Externally-pushed signal that the server is currently unreachable.
  /// AuthProvider mirrors `serverReachable` here on each ping result so we
  /// can short-circuit pre-play server calls (e.g. session creation) for
  /// instant offline playback - no need to wait for a network timeout to
  /// discover what the auth layer already knows. Other services
  /// (AndroidAuto/CarPlay browse) read it via [knownOffline] to skip
  /// their own server fetches.
  bool _knownOffline = false;
  bool get knownOffline => _knownOffline;
  void setKnownOffline(bool offline) {
    _knownOffline = offline;
  }

  bool _isBackgrounded = false;
  bool get isBackgrounded => _isBackgrounded;
  SharedPreferences? _prefs;
  StreamSubscription? _syncSub;
  StreamSubscription? _completionSub;
  StreamSubscription? _nativeAutoAdvanceSub;
  StreamSubscription<Object>? _audioServiceErrorSub;

  // ── Pre-buffer next book in queue (iOS background auto-advance fix) ──
  // iOS denies background audio output to freshly-loaded AVPlayerItems.
  // Workaround: append the next book to the live ConcatenatingAudioSource
  // ~15s before current ends. AVQueuePlayer auto-advances natively, audio
  // engine stays continuous, iOS keeps granting output.
  ConcatenatingAudioSource? _activeConcatSource;
  int _currentBookTrackCount = 0;
  bool _nextBookPreloading = false;
  Map<String, dynamic>? _preloadedNextBook;
  bool _autoQueueAdvancing = false;
  Timer? _bgSaveTimer;
  Timer? _advanceBufferingBackstop;
  Timer? _pauseStopTimer;
  static const _pauseStopTimeout = Duration(minutes: 10);
  // A streamed book's cover isn't in the content-provider cache on first play,
  // so the notification's first art request races the on-demand fetch and the
  // OS caches the empty result against the fixed cover URI. We re-push the
  // MediaItem once with a cache-busting URI so the OS re-requests it after the
  // cover has been fetched. Tracks the item already scheduled for this.
  String? _coverRepushItem;
  Timer? _coverRepushTimer;

  void _beginAdvanceBuffering() {
    if (!AppPlatform.isAndroid) return;
    _handler?.setAdvanceBuffering(
      true,
      minimumDuration: const Duration(milliseconds: 900),
    );
    _advanceBufferingBackstop?.cancel();
    _advanceBufferingBackstop = Timer(const Duration(seconds: 30), () {
      _advanceBufferingBackstop = null;
      _handler?.setAdvanceBuffering(false);
    });
  }

  void _endAdvanceBuffering() {
    if (!AppPlatform.isAndroid) return;
    _advanceBufferingBackstop?.cancel();
    _advanceBufferingBackstop = null;
    _handler?.setAdvanceBuffering(false);
  }

  /// Last known position in seconds — used to detect end→0 position jumps.
  double _lastKnownPositionSec = 0;
  // Where the latest seek was headed, a start's own seek included. A stream
  // that fails before that seek lands has no known position yet, and the
  // retry began the book again from zero.
  double? _lastSeekTargetSec;
  DateTime? _lastSeekAt;

  /// When this phone last moved the position itself: a seek, a chapter jump,
  /// a start at a chosen spot. A server position saved before then is not
  /// newer than where you are.
  DateTime? get lastSeekAt => _lastSeekAt;
  // ── Stream error retry tracking ──
  int _streamRetryCount = 0;
  static const _maxStreamRetries = 3;
  bool _retryInProgress = false;
  // ── Stuck position detection (xHE-AAC/USAC iOS seek failures) ──
  Timer? _stuckCheckTimer;
  double _stuckCheckLastPosition = -1;
  int _stuckConsecutiveCount = 0; // consecutive checks with no advancement
  int _stuckReseekAttempts = 0; // how many re-seeks we've tried
  static const _maxStuckReseekAttempts = 2;
  // ── Play verification (iOS USAC can silently fail to start after seek) ──
  Timer? _playVerifyTimer;
  // ── Multi-file track offset tracking ──
  // For ConcatenatingAudioSource, _player.position is track-relative.
  // We store cumulative start offsets so we can compute absolute book position.
  List<double> _trackStartOffsets = []; // [0, dur0, dur0+dur1, ...]
  List<double> get trackStartOffsets => _trackStartOffsets;
  int _currentTrackIndex = 0;

  // When a downloaded file decodes shorter than the book's metadata duration
  // (an incomplete or corrupt download), this holds the real playable length
  // in seconds. Seeks are clamped to it, and the truncation-end position is
  // never saved over a further-along stored position. null = file looks fine.
  // GH #278: a half-downloaded book otherwise clamped every resume back to the
  // file's end (50% of the book) and saved that over the user's real progress.
  double? _shortLocalDurationSec;
  // Ignore small encoder/container rounding when comparing decoded vs metadata.
  static const double _kLocalTruncationMarginSec = 60.0;
  int _lastNotifiedChapterIndex = -1;
  int _lastChapterCheckSec = -1;
  StreamSubscription? _indexSub;

  // ── iOS premature-completion guard (GH #219) ──
  // ConcatenatingAudioSource on iOS sometimes fires ProcessingState.completed
  // when advancing to the LAST item without actually rendering its audio,
  // making books appear to "skip" the final chapter. We watch how recently
  // _currentTrackIndex flipped to the last track; if completion fires within
  // a few seconds of that advance for a substantial last track, treat it as
  // spurious and seek-resume into the last track. Capped to prevent loops
  // if recovery itself can't get the player unstuck.
  DateTime? _lastIndexAdvanceTime;
  int _iosLastTrackRecoveryAttempts = 0;
  static const _maxIosLastTrackRecoveries = 2;

  // Force one lock-screen state push after an intra-book track advance.
  bool _pendingTrackAdvanceRefresh = false;

  // ── Notification chapter progress mode ──
  bool _notifChapterMode = false;
  double _currentChapterStart = 0;
  double _currentChapterEnd = 0;
  bool get notifChapterMode => _notifChapterMode && _chapters.isNotEmpty;
  NowPlayingLayout _nowPlayingLayout = NowPlayingLayout.standard;
  String _nowPlayingLayoutJson = '';
  bool _speedAdjustedTime = true;
  // The moving parts (percent, minutes left) the media controls last showed.
  String _lastNowPlayingTicker = '-1|-1';
  String? _currentNarrator;
  String? _currentSeries;
  double get currentChapterStart => _currentChapterStart;
  double get currentChapterEnd => _currentChapterEnd;

  void _onSettingsChanged() {
    Future.wait<Object>([
      PlayerSettings.getNotificationChapterProgress(),
      PlayerSettings.getNowPlayingLayout(),
      PlayerSettings.getSpeedAdjustedTime(),
    ]).then((v) {
      final chapterMode = v[0] as bool;
      final layoutJson = v[1] as String;
      final speedAdjusted = v[2] as bool;
      final chapterModeChanged = chapterMode != _notifChapterMode;
      final textChanged = layoutJson != _nowPlayingLayoutJson ||
          (speedAdjusted != _speedAdjustedTime &&
              _nowPlayingLayout.uses(NowPlayingPiece.timeLeft));
      _notifChapterMode = chapterMode;
      _speedAdjustedTime = speedAdjusted;
      if (layoutJson != _nowPlayingLayoutJson) {
        _nowPlayingLayoutJson = layoutJson;
        _nowPlayingLayout = NowPlayingLayout.fromJson(layoutJson);
      }
      if (!chapterModeChanged && !textChanged) return;
      // Re-push MediaItem + PlaybackState so notification updates immediately
      if (_currentItemId != null) {
        _repushNotifiedMediaItem();
        if (chapterModeChanged) _handler?.refreshPlaybackState();
      }
    });
    // Update cached skip amounts so notification icons stay in sync
    _syncNotifSkipCache();
    PlayerSettings.getMediaControlsSpeedBookmark().then((v) {
      if (_handler != null && v != _handler!._cachedNotifSpeedBookmark) {
        _handler!._cachedNotifSpeedBookmark = v;
        _handler!.refreshPlaybackState();
      }
    });
    PlayerSettings.getLockSeekBar().then((v) {
      if (_handler != null && v != _handler!._cachedLockSeekBar) {
        _handler!._cachedLockSeekBar = v;
        _handler!.refreshPlaybackState();
      }
    });
    if (AppPlatform.isAndroid) {
      PlayerSettings.getDuckBriefInterruptions().then((v) async {
        if (v == _duckBriefInterruptions) return;
        final previousVolume = _volumeBeforeInterruptionDuck;
        _volumeBeforeInterruptionDuck = null;
        _clearDuckWatchdog();
        if (previousVolume != null) {
          await _player?.setVolume(previousVolume);
        }
        await _configureAudioSession();
      });
      PlayerSettings.getKeepPlayingWithOtherApps().then((v) {
        _keepPlayingWithOtherApps = v;
      });
    }
  }

  static const _playerCoreChannel = MethodChannel('com.absorb.player_core');
  static const _audioServiceClientChannel = MethodChannel(
    'com.ryanheise.audio_service.client.methods',
  );

  /// Point the iOS lock screen skip buttons at [forward] / [backward] seconds.
  /// Unlike Android, iOS doesn't ask how far to skip on each press - it reads
  /// the amounts off MPRemoteCommandCenter, which audio_service writes once at
  /// startup and the native core armed with the defaults, so changing the
  /// setting never reached the lock screen. Tell both, since they write the
  /// same properties and whoever goes last wins.
  static Future<void> _pushIosSkipIntervals(int forward, int backward) async {
    try {
      await _playerCoreChannel.invokeMethod('setSkipIntervals', {
        'forward': forward,
        'backward': backward,
      });
    } catch (e) {
      debugPrint('[SkipDebug] native core setSkipIntervals failed: $e');
    }
    try {
      await _audioServiceClientChannel.invokeMethod('updateSkipIntervals', {
        'fastForwardInterval': forward * 1000,
        'rewindInterval': backward * 1000,
      });
    } catch (e) {
      debugPrint('[SkipDebug] audio_service updateSkipIntervals failed: $e');
    }
  }

  /// Refresh the notification's cached skip labels with the amounts for the
  /// current library. Called on settings changes and whenever the loaded
  /// item changes.
  void _syncNotifSkipCache() {
    final libId = _currentLibraryId;
    final fwdFuture = PlayerSettings.getEffectiveForwardSkip(libraryId: libId);
    final backFuture = PlayerSettings.getEffectiveBackSkip(libraryId: libId);
    fwdFuture.then((v) {
      debugPrint(
        '[SkipDebug] notif cache: lib=$libId fwd=${v}s (was ${_handler?._cachedForwardSkip})',
      );
      if (_handler != null && v != _handler!._cachedForwardSkip) {
        _handler!._cachedForwardSkip = v;
        _handler!.refreshPlaybackState();
      }
    });
    backFuture.then((v) {
      if (_handler != null && v != _handler!._cachedBackSkip) {
        _handler!._cachedBackSkip = v;
        _handler!.refreshPlaybackState();
      }
    });
    if (AppPlatform.isIOS) {
      unawaited(
        Future.wait([fwdFuture, backFuture])
            .then((v) => _pushIosSkipIntervals(v[0], v[1])),
      );
    }
  }

  /// Fill in a missing library id for the playing item so per-library skip
  /// amounts apply outside the in-app UI too (notification, headset, home
  /// widget, Android Auto). Lean shelf items and merged-library podcast
  /// entries often arrive without one; try download metadata synchronously,
  /// then the server.
  void _resolveMissingLibraryId(String itemId, String? episodeId) {
    if (itemId.isEmpty) return;
    if (_currentLibraryId != null && _currentLibraryId!.isNotEmpty) return;
    final key = episodeId != null ? '$itemId-$episodeId' : itemId;
    final fromDownload = DownloadService().getInfo(key).libraryId;
    if (fromDownload != null && fromDownload.isNotEmpty) {
      debugPrint(
        '[SkipDebug] libraryId resolved from download metadata: $fromDownload',
      );
      _currentLibraryId = fromDownload;
      return;
    }
    final api = _api;
    if (api == null) return;
    unawaited(() async {
      try {
        final item = await api.getLibraryItem(itemId);
        final libId = item?['libraryId'] as String?;
        if (libId == null || libId.isEmpty) return;
        // Only adopt if this item is still the one playing and nothing else
        // resolved the library in the meantime (e.g. the play session).
        if (_currentItemId != itemId) return;
        if (_currentLibraryId != null && _currentLibraryId!.isNotEmpty) return;
        debugPrint('[SkipDebug] libraryId resolved from server: $libId');
        _currentLibraryId = libId;
        _syncNotifSkipCache();
        notifyListeners();
      } catch (e) {
        debugPrint('[SkipDebug] libraryId lookup failed: $e');
      }
    }());
  }

  /// The last seek target in seconds (absolute book position).
  /// UI can use this to immediately snap to the target before stream catches up.
  double? _lastSeekTargetSeconds;
  DateTime? _lastSeekTime;

  /// If a seek happened recently, returns the seek target.
  /// Otherwise returns null (use the stream position).
  double? get activeSeekTarget {
    if (_lastSeekTargetSeconds == null || _lastSeekTime == null) return null;
    final elapsed = DateTime.now().difference(_lastSeekTime!).inMilliseconds;
    if (elapsed > 8000) {
      _lastSeekTargetSeconds = null;
      _lastSeekTime = null;
      return null;
    }
    return _lastSeekTargetSeconds;
  }

  /// Clear the seek target once the stream has caught up.
  void clearSeekTarget() {
    _lastSeekTargetSeconds = null;
    _lastSeekTime = null;
  }

  final _progressSync = ProgressSyncService();
  final _downloadService = DownloadService();
  final _history = PlaybackHistoryService();

  /// Log a playback event to history.
  void _logEvent(
    PlaybackEventType type, {
    String? detail,
    double? overridePosition,
  }) {
    if (_currentItemId == null) return;
    _history.log(
      itemId: _currentItemId!,
      type: type,
      positionSeconds: overridePosition ?? position.inMilliseconds / 1000.0,
      detail: detail,
    );
  }

  static String _formatPos(Duration d) {
    final h = d.inHours;
    final m = d.inMinutes % 60;
    final s = d.inSeconds % 60;
    if (h > 0)
      return '$h:${m.toString().padLeft(2, '0')}:${s.toString().padLeft(2, '0')}';
    return '$m:${s.toString().padLeft(2, '0')}';
  }

  String? get currentItemId => _currentItemId;
  String? get currentTitle => _currentTitle;
  String? get currentAuthor => _currentAuthor;
  String? get currentCoverUrl => _currentCoverUrl;
  double get totalDuration => _totalDuration;
  double get displayDuration =>
      _metaDuration > 0 ? _metaDuration : _totalDuration;
  List<dynamic> get chapters => _chapters;

  /// GH #298: how every "now playing" surface (lock screen, CarPlay, Android
  /// Auto, home widget) labels the current item — the chapter goes on the
  /// primary line and the book sits beside the author ("Author · Book").
  /// Chapterless content (podcasts, books with no chapters) keeps the
  /// book/episode on the primary line.
  static ({String title, String subtitle}) nowPlayingLabels(
    String primaryTitle,
    String author,
    String? chapter,
  ) {
    final ch = chapter?.trim() ?? '';
    if (ch.isEmpty) return (title: primaryTitle, subtitle: author);
    final a = author.trim();
    final String subtitle;
    if (a.isEmpty) {
      subtitle = primaryTitle;
    } else if (primaryTitle.isEmpty) {
      subtitle = a;
    } else {
      subtitle = '$a · $primaryTitle';
    }
    return (title: ch, subtitle: subtitle);
  }

  /// Chapter-aware primary line for the current item (GH #298).
  String get nowPlayingTitle => nowPlayingLabels(
    _currentTitle ?? '',
    _currentAuthor ?? '',
    currentChapter?['title'] as String?,
  ).title;

  /// Chapter-aware secondary line ("Author · Book") for the current item.
  String get nowPlayingSubtitle => nowPlayingLabels(
    _currentTitle ?? '',
    _currentAuthor ?? '',
    currentChapter?['title'] as String?,
  ).subtitle;

  void updateChapters(List<dynamic> chapters) {
    _chapters = chapters;
    _handler?.updateChaptersQueue(chapters);
    notifyListeners();
  }

  bool get hasBook => _currentItemId != null;

  /// True when a loaded item is in an active session - playing OR paused.
  /// stop() drops the engine to idle while keeping _currentItemId, so this is
  /// false for a stopped session even though [hasBook] stays true.
  bool get hasActiveSession =>
      _currentItemId != null &&
      (_player?.processingState ?? ProcessingState.idle) !=
          ProcessingState.idle;
  bool get isPlaying => _player?.playing ?? false;

  /// True while [playItem] is setting up a new audio source.
  bool _isLoadingNewItem = false;
  bool get isLoadingNewItem => _isLoadingNewItem;
  bool get isLoadingOrBuffering {
    if (_isLoadingNewItem) return true;
    final s = _player?.processingState;
    return s == ProcessingState.loading || s == ProcessingState.buffering;
  }

  bool get isOfflineMode => _isOfflineMode;
  double get volume => _player?.volume ?? 1.0;
  Future<void> setVolume(double v) async => _player?.setVolume(v);

  static const _eqChannelForDiag = MethodChannel('com.absorb.equalizer');
  static const _queueAdvancerChannel = MethodChannel(
    'com.absorb.queue_advancer',
  );
  void _resetPreBufferState() {
    _activeConcatSource = null;
    _currentBookTrackCount = 0;
    _nextBookPreloading = false;
    _preloadedNextBook = null;
    _iosResyncPending = false;
    if (AppPlatform.isIOS) {
      _queueAdvancerChannel.invokeMethod('clear').catchError((Object e) {
        debugPrint('[QueueAdvance] clear failed: $e');
        return null;
      });
    }
  }

  void _maybePreloadNextBook() {
    if (_nextBookPreloading) return;
    if (_preloadedNextBook != null) return;
    if (_activeConcatSource == null) return;
    if (_currentBookTrackCount == 0) return;
    if (_totalDuration <= 0) return;
    final remaining = _totalDuration - _lastKnownPositionSec;
    if (remaining <= 0 || remaining > 15) return;
    if (_currentItemId == null) return;
    final cb = _onPeekNextItemCallback;
    if (cb == null) return;

    _nextBookPreloading = true;
    final currentId = _currentEpisodeId != null
        ? '$_currentItemId-$_currentEpisodeId'
        : _currentItemId!;
    unawaited(_preloadNextBookAsync(cb, currentId));
  }

  Future<void> _preloadNextBookAsync(
    Future<Map<String, dynamic>?> Function(String) cb,
    String currentId,
  ) async {
    try {
      final next = await cb(currentId);
      if (next == null) {
        debugPrint('[PreBuffer] No next item to preload');
        return;
      }
      final nextItemId = next['itemId'] as String?;
      if (nextItemId == null) {
        debugPrint('[PreBuffer] Next item has no itemId');
        return;
      }
      // Resolve the next book's resume position once and stash it on the map
      // so commitAdvance, Now Playing, and _onAutoQueueAdvanced all agree.
      double startS = 0;
      final progressKey = next['episodeId'] != null
          ? '$nextItemId-${next['episodeId']}'
          : nextItemId;
      double localS = 0;
      final saved = await _progressSync.getLocal(progressKey);
      if (saved != null && !(saved['isFinished'] as bool? ?? false)) {
        localS = (saved['currentTime'] as num?)?.toDouble() ?? 0;
      }
      startS = localS;
      // Local storage can be empty or behind when the progress lives on the
      // server (another device, fresh install). Server-ahead wins, same as
      // the playItem position pick.
      double serverS = 0;
      if (_api != null && !_isOfflineMode) {
        try {
          final server = await _api!
              .getItemProgress(progressKey)
              .timeout(const Duration(seconds: 5), onTimeout: () => null);
          final serverTime = (server?['currentTime'] as num?)?.toDouble() ?? 0;
          final serverFinished = server?['isFinished'] as bool? ?? false;
          if (!serverFinished) serverS = serverTime;
          if (serverS > startS) startS = serverS;
        } catch (_) {}
      }
      debugPrint(
        '[PreBuffer] Resume pick for $progressKey: '
        'local=${localS.toStringAsFixed(1)}s server=${serverS.toStringAsFixed(1)}s '
        '-> start=${startS.toStringAsFixed(1)}s',
      );
      next['startS'] = startS;

      // Build audio source for the next item.
      final localPaths = (next['localPaths'] as List<dynamic>?)?.cast<String>();
      final audioTracks = next['audioTracks'] as List<dynamic>?;
      final audioHeaders = next['audioHeaders'] as Map<String, String>?;

      List<AudioSource>? nextTrackSources;
      if (localPaths != null && localPaths.isNotEmpty) {
        nextTrackSources = localPaths.map((p) => localAudioSource(p)).toList();
      } else if (audioTracks != null && audioTracks.isNotEmpty) {
        nextTrackSources = audioTracks
            .map(
              (t) =>
                  AudioSource.uri(
                        Uri.parse((t as Map<String, dynamic>)['url'] as String),
                        headers: audioHeaders,
                        options: mp3ExtractorOptions(),
                      )
                      as AudioSource,
            )
            .toList();
      }
      if (nextTrackSources == null || nextTrackSources.isEmpty) {
        debugPrint('[PreBuffer] No playable sources for next item');
        return;
      }
      if (nextTrackSources.length != 1) {
        debugPrint(
          '[PreBuffer] Next item is multi-track, skipping (MVP supports single-track only)',
        );
        return;
      }

      if (AppPlatform.isIOS) {
        // Native engine owns the cross-book swap. Skip concat.add entirely.
        final source = nextTrackSources.length == 1
            ? nextTrackSources.first
            : ConcatenatingAudioSource(children: nextTrackSources);
        final ok = await _player!.setNextSource(
          source,
          startPositionS: startS,
          totalDurationS: (next['duration'] as num?)?.toDouble() ?? 0,
          itemId: nextItemId,
        );
        if (!ok) {
          debugPrint('[PreBuffer] Native setNextSource failed');
          return;
        }
        _preloadedNextBook = next;
        debugPrint(
          '[PreBuffer] Pre-loaded native: ${next['title']} ($nextItemId) start=${startS.toStringAsFixed(1)}s',
        );
        return;
      }

      final concat = _activeConcatSource;
      if (concat == null) {
        debugPrint('[PreBuffer] Concat source went away mid-preload');
        return;
      }
      for (final s in nextTrackSources) {
        await concat.add(s);
      }
      _preloadedNextBook = next;
      debugPrint(
        '[PreBuffer] Pre-loaded next item: ${next['title']} ($nextItemId) '
        'start=${startS.toStringAsFixed(1)}s',
      );

      if (AppPlatform.isIOS) {
        // Legacy native queue advancer kick (flag-off path).
        unawaited(
          _primeNativeQueueAdvancer(
            next,
            localPaths,
            audioTracks,
            audioHeaders,
          ),
        );
      }
    } catch (e, st) {
      debugPrint('[PreBuffer] Failed: $e\n$st');
    }
    // _nextBookPreloading stays true regardless of outcome — single attempt per
    // play session. Reset happens in _resetPreBufferState on the next playItem.
  }

  Future<bool> _primeNativeQueueAdvancer(
    Map<String, dynamic> next,
    List<String>? localPaths,
    List<dynamic>? audioTracks,
    Map<String, String>? audioHeaders,
  ) async {
    try {
      String? url;
      bool isLocal = false;
      if (localPaths != null && localPaths.isNotEmpty) {
        url = localPaths.first;
        isLocal = true;
      } else if (audioTracks != null && audioTracks.isNotEmpty) {
        url = (audioTracks.first as Map<String, dynamic>)['url'] as String?;
      }
      if (url == null || url.isEmpty) return false;

      String? coverPath;
      final itemId = next['itemId'] as String?;
      if (itemId != null) {
        final local = DownloadService().getInfo(itemId).localCoverPath;
        if (local != null && local.isNotEmpty) coverPath = local;
      }

      final startS = (next['startS'] as num?)?.toDouble() ?? 0;

      // Label the pre-buffered next book like the lock screen: the same
      // layout, at its resume point.
      final nextTitle = (next['title'] as String?) ?? '';
      final nextChapters = (next['chapters'] as List<dynamic>?) ?? const [];
      final nextChapterIndex = _chapterIndexAt(nextChapters, startS);
      final nextLabels = _nowPlayingLines(
        title: nextTitle,
        author: (next['author'] as String?) ?? '',
        chapter: nextChapterIndex >= 0
            ? (nextChapters[nextChapterIndex] as Map<String, dynamic>)['title']
                as String?
            : null,
        chapterIndex: nextChapterIndex,
        chapterCount: nextChapters.length,
        posSec: startS,
        totalDuration: (next['duration'] as num?)?.toDouble() ?? 0,
      );

      final ok = await _queueAdvancerChannel.invokeMethod<bool>('prepareNext', {
        'url': url,
        'isLocal': isLocal,
        'headers': audioHeaders ?? <String, String>{},
        'title': nextLabels.title,
        'artist': nextLabels.subtitle,
        'album': nextTitle,
        'durationS': (next['duration'] as num?)?.toDouble() ?? 0,
        'coverPath': coverPath,
        'startS': startS,
      });
      debugPrint('[PreBuffer] native prepareNext returned $ok');
      return ok ?? false;
    } catch (e) {
      debugPrint('[PreBuffer] native prepareNext failed: $e');
      return false;
    }
  }

  void _onAutoQueueAdvanced() {
    final next = _preloadedNextBook;
    if (next == null) return;
    if (_autoQueueAdvancing) return;
    _autoQueueAdvancing = true;
    _beginAdvanceBuffering();
    debugPrint('[PreBuffer] Auto-queue advanced to ${next['title']}');
    final oldTrackCount = _currentBookTrackCount;

    final oldItemId = _currentItemId;
    final oldEpisodeId = _currentEpisodeId;
    final oldKey = oldEpisodeId != null
        ? '$oldItemId-$oldEpisodeId'
        : oldItemId;

    // Promote next book's metadata to current state
    _currentItemId = next['itemId'] as String?;
    _currentEpisodeId = next['episodeId'] as String?;
    _currentLibraryId = next['libraryId'] as String?;
    _resolveMissingLibraryId(_currentItemId ?? '', _currentEpisodeId);
    _syncNotifSkipCache();
    _currentTitle = next['title'] as String?;
    _currentAuthor = next['author'] as String?;
    _currentNarrator = null;
    _currentSeries = null;
    _currentCoverUrl = next['coverUrl'] as String?;
    _totalDuration = (next['duration'] as num?)?.toDouble() ?? 0;
    _metaDuration = _totalDuration;
    _chapters = (next['chapters'] as List<dynamic>?) ?? [];
    _handler?.updateChaptersQueue(_chapters);
    _trackStartOffsets = [0.0, _totalDuration];
    _currentTrackIndex = 0;
    _playbackSessionId = null;
    final startS = (next['startS'] as num?)?.toDouble() ?? 0;
    _lastKnownPositionSec = startS;
    final newKey = _currentEpisodeId != null
        ? '$_currentItemId-$_currentEpisodeId'
        : _currentItemId;
    debugPrint(
      '[PreBuffer] Promoted $oldKey -> $newKey start=${startS.toStringAsFixed(1)}s',
    );
    _lastNotifiedChapterIndex = -1;
    _currentBookTrackCount = 1;
    _preloadedNextBook = null;
    _nextBookPreloading = false;

    // Push new media item to update Now Playing / lock screen
    final initChapter = _initChapterInfo(startS);
    _pushMediaItem(
      _currentItemId!,
      _currentTitle ?? '',
      _currentAuthor ?? '',
      _currentCoverUrl,
      _totalDuration,
      chapter: initChapter,
    );
    unawaited(
      _primeNowPlaying(
        title: _currentTitle ?? '',
        artist: _currentAuthor ?? '',
        duration: _totalDuration,
        elapsed: startS,
        chapter: initChapter,
      ),
    );

    if (AppPlatform.isIOS) {
      unawaited(_iosAutoAdvanceKick());
    } else {
      unawaited(_finalizeAndroidAutoAdvance(oldTrackCount, startS));
    }

    // Notify LibraryProvider via auto-queue-specific callback (skipAutoAdvance
    // inside markFinishedLocally — next item is already playing, no playItem).
    if (oldKey != null) {
      final cb = _onAutoQueueAdvancedCallback;
      if (cb != null) cb(oldKey);
    }
    if (oldItemId != null && oldEpisodeId == null) {
      unawaited(ReviewService.onBookFinished(isForeground: !_isBackgrounded));
    }

    notifyListeners();
    _autoQueueAdvancing = false;
  }

  /// ExoPlayer walks into the pre-buffered book at position 0 with the
  /// finished item's tracks still in front of it in the concat, so absolute
  /// seeks map into the dead item (and clamp at its end) and the saved resume
  /// position is never applied. Drop the old tracks so the book becomes
  /// index 0, restore single-file offsets, and jump to where the user left it.
  Future<void> _finalizeAndroidAutoAdvance(
    int oldTrackCount,
    double startS,
  ) async {
    try {
      final concat = _activeConcatSource;
      if (concat != null &&
          oldTrackCount > 0 &&
          concat.length > oldTrackCount) {
        await concat.removeRange(0, oldTrackCount);
        debugPrint(
          '[PreBuffer] Dropped $oldTrackCount finished track(s); concat now ${concat.length}',
        );
      }
      _trackStartOffsets = [0.0];
      _currentTrackIndex = 0;
      if (startS > 0) {
        await _seekAbsolute(startS);
        clearSeekTarget();
        debugPrint(
          '[PreBuffer] Resumed advanced book at ${startS.toStringAsFixed(1)}s',
        );
      }
    } catch (e) {
      debugPrint('[PreBuffer] Android advance finalize failed: $e');
    }
  }

  // Set when native commitAdvance swaps in a foreign AVPlayerItem. just_audio
  // sees _index = -1 from then on; we need to rebuild its source the next
  // time the app is foregrounded so position and pause work normally.
  bool _iosResyncPending = false;

  Future<void> _iosAutoAdvanceKick() async {
    final speed = _player?.speed ?? 1.0;
    try {
      await _setAudioSessionActive(true);
    } catch (e) {
      debugPrint('[QueueAdvance] setActive failed: $e');
    }
    if (_isBackgrounded) {
      try {
        final ok = await _queueAdvancerChannel.invokeMethod<bool>(
          'commitAdvance',
          {'speed': speed},
        );
        if (ok == true) {
          _iosResyncPending = true;
          debugPrint('[QueueAdvance] native commit succeeded, resync armed');
        }
      } catch (e) {
        debugPrint('[QueueAdvance] commitAdvance failed: $e');
      }
    }
    try {
      await _player?.setSpeed(speed);
    } catch (e) {
      debugPrint('[QueueAdvance] setSpeed kick failed: $e');
    }
    Future.delayed(const Duration(milliseconds: 300), () {
      _handler?.refreshPlaybackState();
    });
  }

  Future<void> _iosForegroundResyncIfNeeded() async {
    if (!_iosResyncPending) return;
    _iosResyncPending = false;
    final itemId = _currentItemId;
    final api = _api;
    if (itemId == null || api == null) {
      debugPrint('[QueueAdvance] resync: missing item or api, skipping');
      return;
    }
    double startS = 0;
    try {
      final pos = await _queueAdvancerChannel.invokeMethod<double>(
        'getPositionS',
      );
      if (pos != null && pos > 0) startS = pos;
    } catch (e) {
      debugPrint('[QueueAdvance] getPositionS failed: $e');
    }
    debugPrint(
      '[QueueAdvance] Resyncing just_audio for $itemId at ${startS.toStringAsFixed(1)}s',
    );
    try {
      await playItem(
        api: api,
        itemId: itemId,
        title: _currentTitle ?? '',
        author: _currentAuthor ?? '',
        coverUrl: _currentCoverUrl,
        totalDuration: _totalDuration,
        chapters: _chapters,
        startTime: startS,
        forceStartTime: true,
        episodeId: _currentEpisodeId,
        libraryId: _currentLibraryId,
      );
    } catch (e) {
      debugPrint('[QueueAdvance] resync playItem failed: $e');
    }
  }

  /// iOS: re-take the Now Playing claim after something may have knocked it
  /// out while paused - a stretch suspended in the background where an
  /// interruption came and went unseen, the user opening another app that
  /// played something, or the headphones being stowed. iOS deactivates the
  /// session for the interrupter, and a paused app that never re-activates
  /// quietly falls out of Now Playing candidacy: the next headset press then
  /// goes to Apple Music instead.
  ///
  /// Deliberately NOT called when an interruption ends while paused. Plenty
  /// of apps deactivate their session on pause, which arrives here as an
  /// interruption ending, and claiming at that moment would take the headset
  /// away from the app the user just paused. The foreground and
  /// route-disconnect calls pick the claim back up the next time the user
  /// comes back to Absorb.
  ///
  /// Re-activating and republishing metadata is NOT enough on its own. iOS
  /// only hands the slot to an app that has actually rendered audio, which is
  /// what build 249 got wrong and 251 fixed with a silent blip - so the claim
  /// goes through the native primer rather than being done here. Doing it in
  /// Dart looked like it worked, because setActive succeeds either way.
  ///
  /// Only runs when nothing else is audibly playing: the claim matters
  /// exactly when the next press should reach this app, and grabbing it out
  /// from under an app mid-playback would be rude. The primer re-checks that
  /// and activates the session itself, so nothing is activated from Dart and
  /// the guard and the activation stay together with no gap between them.
  Future<void> reassertIosClaimWhilePaused(String reason) async {
    if (!AppPlatform.isIOS || !hasBook || isPlaying) return;
    try {
      final info = await _eqChannelForDiag
          .invokeMethod<Map<dynamic, dynamic>>('getAudioDiagnostics');
      if (info?['isOtherAudioPlaying'] == true ||
          info?['secondaryAudioShouldBeSilencedHint'] == true) {
        debugPrint(
          '[AudioSession] claim reassert skipped ($reason) - other audio is playing',
        );
        return;
      }
      // Publish this book before the blip, so the slot we take back shows the
      // right title rather than whatever the app that stole it left behind.
      _handler?.refreshPlaybackState();
      final started = await _eqChannelForDiag.invokeMethod<bool>(
        'reclaimNowPlaying',
        {'reason': reason},
      );
      debugPrint(
        '[AudioSession] claim reassert ($reason): blip started=$started',
      );
    } catch (e) {
      debugPrint('[AudioSession] claim reassert failed ($reason): $e');
    }
  }

  /// iOS: a headset press can cold-launch the app into the background with
  /// the native core already driving the shared engine (its remote commands
  /// arm at app launch). Dart then boots with no book loaded, so
  /// audio_service publishes a blank Now Playing over the native core's and
  /// every later press defers to a player that knows nothing - the lock
  /// screen shows audio running with no title, cover or progress. Adopt
  /// instead: restore the last-played item at the engine's own live position,
  /// which re-publishes full metadata and puts Dart in charge of the audio
  /// that is already running. Called once from main.dart after init.
  Future<void> adoptBackgroundEngineIfRunning() async {
    if (!AppPlatform.isIOS) return;
    if (_currentItemId != null) return;
    final player = _player;
    if (player == null) return;
    try {
      var state = await player.engineState();
      // A press-launched process races this check twice over: Dart init can
      // get here before the native core has even LOADED the engine (a field
      // log had this check lose by two milliseconds), and a stream then
      // buffers for a while before isPlaying flips. Deciding on the first
      // read left Dart bookless under live audio. So poll: a press-loaded
      // engine shows up within the first second, and once it is loaded, give
      // the buffer the rest of the budget. On a normal launch nothing ever
      // loads and this waits out the budget then does nothing - harmless,
      // since the primer has the lock screen and the command center routes
      // any early press to the cold-start restore.
      var waited = 0;
      while ((state == null || !state.isLoaded || !state.isPlaying) &&
          waited < 4000) {
        await Future.delayed(const Duration(milliseconds: 500));
        waited += 500;
        // Dart started something itself while this waited - a card tap, a
        // CarPlay autoplay, a headset press routed through the handler. That
        // is Dart's own playback, not an orphaned engine: the restore below
        // is the play/pause toggle, and calling it now would pause it.
        if (_currentItemId != null) return;
        state = await player.engineState();
      }
      if (_currentItemId != null) return;
      if (state != null && state.isLoaded && state.isPlaying) {
        debugPrint(
          '[Player] boot: native engine already playing at '
          '${state.globalPositionS.toStringAsFixed(1)}s with no book loaded - adopting'
          '${waited > 0 ? " (waited ${waited}ms for the stream to start)" : ""}',
        );
        if (state.globalPositionS > 0) {
          await HomeWidgetService().stashLivePosition(state.globalPositionS);
        }
        final restore = AudioPlayerService.onColdStartPlayRequested;
        if (restore != null) await restore();
        return;
      }
      // Idle engine: leave the player empty. The book only loads when the
      // user actually plays - an early headset press still works because the
      // handler routes play-with-nothing-loaded to the cold-start restore.
      // (This used to load the last played book paused as a press target,
      // which put an unasked-for book in the player on every launch.)
    } catch (e) {
      debugPrint('[Player] boot engine adopt failed: $e');
    }
  }

  /// iOS foreground reconciliation after a possible widget-driven session.
  ///
  /// The shared engine (AbsorbAudioEngine) persists across Flutter suspension,
  /// so when the user tapped the widget while we were suspended the engine kept
  /// playing the same book. On resume we must NOT reload it - that restarts the
  /// stream. Instead, if the engine is still on our current book, adopt its
  /// playing-state, track index, and global position. If the engine has been
  /// stopped or holds a different book, leave the existing paths to handle it
  /// (the idle-on-resume re-init in play(), or a fresh playItem).
  Future<void> _iosReconcileEngineOnForeground() async {
    if (!AppPlatform.isIOS) return;
    final player = _player;
    final itemId = _currentItemId;
    if (player == null || itemId == null) return;
    final state = await player.engineState();
    if (state == null) return;
    // Engine isn't on our book (stopped, disposed, or swapped) - nothing to
    // adopt; the normal play()/idle-reinit path will rebuild if needed.
    if (!state.isLoaded || state.itemId != itemId) {
      debugPrint(
        '[Player] iOS resume: engine not on current book '
        '(engine=${state.itemId} loaded=${state.isLoaded}) - skipping adopt',
      );
      return;
    }
    // Sync our track index to whatever track the engine actually reached while
    // we were suspended, so absolute-position math is correct.
    if (_trackStartOffsets.length > 1) {
      final clamped = state.trackIndex.clamp(0, _trackStartOffsets.length - 2);
      if (clamped != _currentTrackIndex) {
        debugPrint(
          '[Player] iOS resume: track index $_currentTrackIndex -> $clamped (from engine)',
        );
        _currentTrackIndex = clamped;
      }
    }
    // Adopt the engine's playing-state without issuing a new command, then let
    // the handler re-publish so the lock screen / notification reflect reality.
    final wasPlaying = isPlaying;
    player.adoptPlayingState(state.isPlaying);
    debugPrint(
      '[Player] iOS resume: adopted engine state playing=${state.isPlaying} '
      '(was $wasPlaying) global=${state.globalPositionS.toStringAsFixed(1)}s',
    );
    // Persist the adopted position only when the engine actually moved on
    // while Flutter was suspended (a widget or lock screen session), so a
    // later save can't overwrite it with a stale value. A paused engine
    // sitting where Dart left it has nothing new to say: saving it anyway
    // re-stamped a stale position as fresh on every foreground, which blocked
    // pulling another device's newer progress and, after a session-start
    // rewind, pushed the server a few seconds backwards per relaunch.
    if (state.globalPositionS > _lastKnownPositionSec + 1.0) {
      _lastKnownPositionSec = state.globalPositionS;
      await _saveProgressLocal(
        Duration(milliseconds: (state.globalPositionS * 1000).round()),
      );
    }
    // The engine may have crossed chapters while Dart was suspended (a widget
    // or headset session driven by the native core). Chapter detection runs
    // off position ticks and a paused engine emits none, so the lock screen
    // kept the old chapter clamped at its end with no progress while the book
    // was chapters ahead. Work out the chapter for the adopted position and
    // republish.
    // Use this service's own position, which adds the track offset: when Dart
    // drives the engine one track at a time, the engine's "global" position is
    // the position within the current track (160s into track 25, not 11026s
    // into the book), and the chapter for that number is the wrong one.
    final adoptedItemId = _currentItemId;
    if (adoptedItemId != null) {
      final chapterTitle = _initChapterInfo(position.inMilliseconds / 1000.0);
      _pushMediaItem(
        adoptedItemId,
        _currentTitle ?? '',
        _currentAuthor ?? '',
        _currentCoverUrl,
        _totalDuration,
        chapter: chapterTitle,
      );
    }
    _handler?.refreshPlaybackState();
    notifyListeners();
  }

  Future<void> _primeNowPlaying({
    required String title,
    required String artist,
    required double duration,
    required double elapsed,
    String? chapter,
  }) async {
    if (!AppPlatform.isIOS) return;
    // Match the lock screen, which uses the same layout.
    final labels = _nowPlayingLines(
      title: title,
      author: artist,
      chapter: chapter,
      chapterIndex: chapter == null ? -1 : _lastNotifiedChapterIndex,
      chapterCount: _chapters.length,
      posSec: elapsed,
      totalDuration: duration,
      narrator: _currentNarrator,
      series: _currentSeries,
    );
    try {
      await _eqChannelForDiag.invokeMethod('primeNowPlaying', {
        'title': labels.title,
        'artist': labels.subtitle,
        'album': title,
        'duration': duration,
        'elapsed': elapsed,
      });
      debugPrint(
        '[Player] primeNowPlaying title="${labels.title}" elapsed=${elapsed.toStringAsFixed(1)}',
      );
    } catch (e) {
      debugPrint('[Player] primeNowPlaying failed: $e');
    }
  }

  /// Diagnostic snapshot for the "tap play, no sound" issue. Logs both
  /// just_audio player state AND iOS AVAudioSession route/volume info so
  /// we can tell apart "player thinks it's playing but no audio reaches
  /// speakers" from "player is buffering forever" from "wrong output
  /// route" etc.
  /// The system's record of how the last process ended, for deaths the log
  /// itself cannot see coming.
  static Future<void> _reportPreviousExit() async {
    final snap = await AudioPlayerHandler._absorbDiagSnapshot();
    final info = snap?['lastExit'];
    if (info != null) debugPrint('[Init] Previous process exit: $info');
  }

  Future<void> _logAudioDiagnostics(String stage) async {
    try {
      final p = _player;
      final pos = p?.position;
      final dur = p?.duration;
      final buffered = p?.bufferedPosition;
      final pieces = <String>[
        'stage=$stage',
        'playing=${p?.playing}',
        'state=${p?.processingState.name}',
        'volume=${p?.volume.toStringAsFixed(2)}',
        'speed=${p?.speed.toStringAsFixed(2)}',
        'pos=${pos != null ? "${(pos.inMilliseconds / 1000.0).toStringAsFixed(1)}s" : "null"}',
        'dur=${dur != null ? "${(dur.inMilliseconds / 1000.0).toStringAsFixed(1)}s" : "null"}',
        'buf=${buffered != null ? "${(buffered.inMilliseconds / 1000.0).toStringAsFixed(1)}s" : "null"}',
        'item=$_currentItemId',
        'ep=$_currentEpisodeId',
      ];

      if (AppPlatform.isAndroid) {
        // Which output the sound is actually leaving through. A player that
        // advances with nothing audible and a Bluetooth route here means the
        // audio went to a device the listener was not wearing.
        final snap = await AudioPlayerHandler._absorbDiagSnapshot();
        if (snap != null) {
          pieces.add('route=[${snap['route']}]');
          pieces.add('outputs=[${snap['outputs']}]');
          pieces.add('musicVol=${snap['musicVolume']}');
        }
      }

      if (AppPlatform.isIOS) {
        try {
          final info = await _eqChannelForDiag
              .invokeMethod<Map<dynamic, dynamic>>('getAudioDiagnostics');
          if (info != null) {
            final outputs =
                (info['outputs'] as List?)
                    ?.map((o) => '${(o as Map)["type"]}:${o["name"]}')
                    .join(',') ??
                '?';
            pieces.addAll([
              'ios.cat=${info["category"]}',
              'ios.mode=${info["mode"]}',
              'ios.policy=${info["routeSharingPolicy"]}',
              'ios.outVol=${info["outputVolume"]}',
              'ios.otherAudio=${info["isOtherAudioPlaying"]}',
              'ios.silenceHint=${info["secondaryAudioShouldBeSilencedHint"]}',
              'ios.route=[$outputs]',
              'ios.sampleRate=${info["sampleRate"]}',
              'ios.npHasInfo=${info["nowPlayingHasInfo"]}',
              'ios.npTitle="${info["nowPlayingTitle"]}"',
              'ios.npRate=${info["nowPlayingRate"]}',
              'ios.npElapsed=${info["nowPlayingElapsed"]}',
            ]);
          }
        } catch (e) {
          pieces.add('ios.err=$e');
        }
      }

      debugPrint('[AudioDiag] ${pieces.join(' ')}');
    } catch (e) {
      debugPrint('[AudioDiag] log failed: $e');
    }
  }

  /// Schedule a sequence of diagnostic snapshots after starting playback so
  /// we can see whether state advanced as expected ("playing then
  /// position-stuck-at-0" is a classic no-sound fingerprint).
  void _scheduleAudioDiagnostics(String startStage) {
    _logAudioDiagnostics('$startStage:t0');
    Future.delayed(
      const Duration(seconds: 1),
      () => _logAudioDiagnostics('$startStage:t1s'),
    );
    Future.delayed(
      const Duration(seconds: 3),
      () => _logAudioDiagnostics('$startStage:t3s'),
    );
    Future.delayed(
      const Duration(seconds: 10),
      () => _logAudioDiagnostics('$startStage:t10s'),
    );
  }

  Stream<Duration> get positionStream =>
      _player?.positionStream ?? const Stream.empty();
  Stream<Duration?> get durationStream =>
      _player?.durationStream ?? const Stream.empty();
  Stream<PlayerState> get playerStateStream =>
      _player?.playerStateStream ?? const Stream.empty();

  /// Absolute book position (accounts for multi-file track offsets).
  Duration get position {
    if (_player == null) return Duration.zero;
    // While swapping to a new item, return the target seek position so the UI
    // doesn't flash stale progress from the previous book.
    final seekTarget = _lastSeekTargetSeconds;
    if (_isLoadingNewItem && seekTarget != null && seekTarget > 0) {
      return Duration(milliseconds: (seekTarget * 1000).round());
    }
    final trackRelative = _player!.position;
    if (_trackStartOffsets.length <= 1) return trackRelative; // single file
    final offsetMs = (_trackStartOffsets[_currentTrackIndex] * 1000).round();
    final result = trackRelative + Duration(milliseconds: offsetMs);
    // Don't log every call — this is called very frequently by sync and UI
    return result;
  }

  /// Absolute book position stream (adjusted for multi-file offsets).
  /// IMPORTANT: Always returns a mapped stream that checks offsets at event time.
  /// Do NOT short-circuit to raw positionStream — the caller may subscribe before
  /// track offsets are built, and would miss the offset transform forever.
  Stream<Duration> get absolutePositionStream {
    if (_player == null) return const Stream.empty();
    return _player!.positionStream.map((trackRelative) {
      if (_trackStartOffsets.length <= 1)
        return trackRelative; // single file, no offset
      final trackIdx = _currentTrackIndex;
      final offsetMs = (_trackStartOffsets[trackIdx] * 1000).round();
      final absolute = trackRelative + Duration(milliseconds: offsetMs);
      return absolute;
    });
  }

  Duration get duration => _player?.duration ?? Duration.zero;
  double get speed => _player?.speed ?? 1.0;

  /// Build track start offsets from audioTracks list.
  void _buildTrackOffsets(List<dynamic> audioTracks) {
    _trackStartOffsets = [0.0];
    double acc = 0;
    for (final t in audioTracks) {
      final track = t as Map<String, dynamic>;
      final dur = (track['duration'] as num?)?.toDouble() ?? 0;
      acc += dur;
      _trackStartOffsets.add(acc);
    }
    debugPrint('[Player] Track offsets: $_trackStartOffsets');
  }

  /// Phase 1.7: snapshot the URLs and HTTP headers used to build the
  /// streaming AudioSource so the iOS native widget core can hit the same
  /// endpoints if Flutter dies. Auth is in the URL (session id or token);
  /// custom headers (Cloudflare Access etc.) ride along for reverse-proxy auth.
  void _captureStreamUrls(
    List<dynamic> audioTracks,
    ApiService api, {
    String? sessionId,
    int? playMethod,
  }) {
    final urls = <String>[];
    for (final t in audioTracks) {
      final track = t as Map<String, dynamic>;
      final contentUrl = track['contentUrl'] as String? ?? '';
      if (contentUrl.isEmpty) continue;
      urls.add(api.buildTrackUrl(
        contentUrl,
        sessionId: sessionId,
        trackIndex: (track['index'] as num?)?.toInt(),
        playMethod: playMethod,
      ));
    }
    if (urls.isNotEmpty) {
      final u = Uri.parse(urls.first);
      final form = u.path.contains('/public/session/')
          ? 'public session'
          : (u.queryParameters.containsKey('token') ? 'tokened' : 'other');
      debugPrint('[Player] Stream URL form: $form (${u.path})');
    }
    _activeStreamUrls = urls;
    _activeStreamHeaders = Map<String, String>.from(api.playbackSessionHeaders);
  }

  /// Subscribe to track index changes for multi-file playback.
  void _subscribeTrackIndex() {
    _indexSub?.cancel();
    if (_player == null) return;
    _indexSub = _player!.currentIndexStream.listen(
      (index) {
        if (index == null) return;
        // Pre-buffer auto-advance: if the queue has grown past the current
        // book's tracks and AVQueuePlayer has stepped into the pre-loaded
        // next book's range, fire the book transition.
        if (_currentBookTrackCount > 0 &&
            index >= _currentBookTrackCount &&
            _preloadedNextBook != null) {
          debugPrint(
            '[PreBuffer] currentIndex=$index crossed book boundary at $_currentBookTrackCount',
          );
          _onAutoQueueAdvanced();
          return;
        }
        // Within-book multi-track advance (existing behavior).
        if (_trackStartOffsets.length > 1) {
          final clamped = index.clamp(0, _trackStartOffsets.length - 2);
          if (clamped != _currentTrackIndex) {
            _lastIndexAdvanceTime = DateTime.now();
            _pendingTrackAdvanceRefresh = true;
            debugPrint(
              '[Player] Track index advance: $_currentTrackIndex -> $clamped',
            );
          }
          _currentTrackIndex = clamped;
        }
      },
      onError: (Object e, StackTrace st) {
        debugPrint('[Player] Index stream error: $e');
      },
    );
  }

  static const _startSeekStall = Duration(seconds: 7);
  static const _maxStartSeekRetries = 2;

  /// The first seek of a streamed start. When the server refuses the range
  /// request the seek sits in buffering with nothing loaded, and a start that
  /// awaits it never reaches play() - Play then does nothing until something
  /// else seeks. A fresh seek unsticks it, so send one; if it still hasn't
  /// landed, let the start carry on and the player keeps loading on its own.
  Future<void> _seekForStart(double seconds, int generation) async {
    for (var attempt = 0; ; attempt++) {
      final landed = await _seekAbsolute(seconds)
          .then((_) => true)
          .timeout(_startSeekStall, onTimeout: () => false);
      if (landed || _player == null || _startSuperseded(generation)) return;
      final ahead = _player!.bufferedPosition - _player!.position;
      if (ahead > const Duration(seconds: 2) ||
          attempt >= _maxStartSeekRetries) {
        debugPrint(
          '[Player] Start seek to ${seconds.toStringAsFixed(1)}s still pending '
          '(buffered ahead ${ahead.inMilliseconds}ms) - starting anyway',
        );
        return;
      }
      debugPrint(
        '[Player] Start seek to ${seconds.toStringAsFixed(1)}s stalled with '
        'nothing buffered - seeking again (${attempt + 1}/$_maxStartSeekRetries)',
      );
    }
  }

  /// Seek to an absolute book position, handling multi-file offset conversion.
  // A seek that lands at the very end of a file never answers on Android,
  // and everything waiting on it hung with it (GH #428).
  static const _seekCap = Duration(seconds: 6);
  void _seekTimedOut() => debugPrint('[Player] Seek got no answer in ${_seekCap.inSeconds}s - carrying on');

  Future<void> _seekAbsolute(double absoluteSeconds) async {
    if (_player == null) return;
    final swap = _pauseSwap;
    if (swap != null) {
      _pauseSwap = null;
      try {
        await swap;
      } catch (_) {}
      if (_player == null) return;
    }
    _lastSeekTargetSec = absoluteSeconds;
    _lastSeekAt = DateTime.now();

    // A seek already interrupts audio, so if a fresh session is waiting this
    // is the free moment to swap the source onto its tokenless URLs - the
    // rebuild lands directly at the target instead of seeking the old source.
    // The same free moment takes a finished download first: the files load
    // straight at the target and the stream is left behind.
    if (_pendingLocalSwapKey != null) {
      final resume = _player!.playing;
      if (await _applyPendingLocalSwap(
        seekToSeconds: absoluteSeconds,
        resumeAfter: resume,
      )) {
        return;
      }
    }
    if (_pendingSessionUpgrade != null) {
      final resume = _player!.playing;
      if (await _applyPendingSessionUpgrade(
        seekToSeconds: absoluteSeconds,
        resumeAfter: resume,
      )) {
        return;
      }
    }

    // Incomplete download: there's no audio past the decoded end, so clamp the
    // target there instead of letting the player report a phantom position
    // beyond the file (which would then get saved/bookmarked). GH #278.
    if (_shortLocalDurationSec != null &&
        absoluteSeconds > _shortLocalDurationSec!) {
      absoluteSeconds = _shortLocalDurationSec!;
    }

    // Record seek target so UI can snap immediately
    _lastSeekTargetSeconds = absoluteSeconds;
    _lastSeekTime = DateTime.now();

    if (_trackStartOffsets.length <= 1) {
      // Single file — seek directly
      await _player!
          .seek(Duration(milliseconds: (absoluteSeconds * 1000).round()))
          .timeout(_seekCap, onTimeout: _seekTimedOut);
      notifyListeners();
      return;
    }
    // Multi-file — find the right track and local offset
    for (int i = 0; i < _trackStartOffsets.length - 1; i++) {
      final trackStart = _trackStartOffsets[i];
      final trackEnd = _trackStartOffsets[i + 1];
      if (absoluteSeconds < trackEnd || i == _trackStartOffsets.length - 2) {
        final localOffset = absoluteSeconds - trackStart;
        debugPrint(
          '[Player] Seek ${absoluteSeconds.toStringAsFixed(1)}s -> track $i '
          'at ${localOffset.toStringAsFixed(1)}s '
          '(${_trackStartOffsets.length - 1} tracks)',
        );
        // Update index BEFORE seeking so positionStream events use the right offset
        _currentTrackIndex = i;
        await _player!
            .seek(Duration(milliseconds: (localOffset * 1000).round()), index: i)
            .timeout(_seekCap, onTimeout: _seekTimedOut);
        notifyListeners();
        return;
      }
    }
  }

  /// MUST be called after Activity is ready.
  /// Whether the phone is on Wi-Fi or wired, where a server push is cheap.
  /// On cellular each push holds the modem awake for a while after, so
  /// progress goes up less often there.
  static bool _onUnmeteredNetwork = true;
  static StreamSubscription<List<ConnectivityResult>>? _connectivitySub;
  static void _noteConnectivity(List<ConnectivityResult> result) {
    _onUnmeteredNetwork = result.contains(ConnectivityResult.wifi) ||
        result.contains(ConnectivityResult.ethernet);
  }

  static Future<void> init() async {
    if (_handler != null) return; // Already initialized
    if (_connectivitySub == null) {
      try {
        _noteConnectivity(await Connectivity().checkConnectivity());
        _connectivitySub =
            Connectivity().onConnectivityChanged.listen(_noteConnectivity);
      } catch (e) {
        debugPrint('[Player] connectivity watch failed: $e');
      }
    }
    // Reset for hot restart — previous completer may already be completed
    // while _handler was reset to null by the Dart VM restart.
    if (_initCompleter.isCompleted) {
      _initCompleter = Completer<void>();
    }
    try {
      final fwdSkip = await PlayerSettings.getForwardSkip();
      final backSkip = await PlayerSettings.getBackSkip();
      // Windows has no audio_service or just_audio implementation: without
      // this AudioService.init threw, no player existed, and play spun
      // forever. media_kit plays the audio; the handler runs standalone.
      if (AppPlatform.isWindows) {
        JustAudioMediaKit.ensureInitialized(windows: true, linux: false);
        _handler = AudioPlayerHandler();
      } else {
        _handler = await AudioService.init<AudioPlayerHandler>(
          builder: () => AudioPlayerHandler(),
          config: AudioServiceConfig(
            androidNotificationChannelId: 'com.audiobookshelf.app.channel.audio',
            androidNotificationChannelName: 'Absorb',
            // Keep foreground service alive when paused — prevents Android from
            // killing audio after notification interruptions on locked screen.
            androidStopForegroundOnPause: false,
            androidNotificationIcon: 'drawable/ic_notification',
            fastForwardInterval: Duration(seconds: fwdSkip),
            rewindInterval: Duration(seconds: backSkip),
            androidBrowsableRootExtras: {
              AndroidContentStyle.supportedKey: true,
              AndroidContentStyle.browsableHintKey:
                  AndroidContentStyle.categoryListItemHintValue,
              AndroidContentStyle.playableHintKey:
                  AndroidContentStyle.gridItemHintValue,
              'android.media.browse.SEARCH_SUPPORTED': true,
            },
          ),
        );
      }
      // Bind service so handler routes play/pause through service (for auto-rewind)
      _handler!.bindService(_instance);
      _instance._audioServiceErrorSub ??= AudioService.asyncError.listen(
        (error) => debugPrint('[AudioService] Platform error: $error'),
      );
      // Wire the EQ service's skip-silence toggle through to just_audio.
      // Android-only: just_audio's setSkipSilenceEnabled is a no-op on iOS.
      if (AppPlatform.isAndroid) {
        EqualizerService().setSkipSilenceApplier((enabled) {
          try {
            _handler?.player.setSkipSilenceEnabled(enabled);
          } catch (e) {
            debugPrint('[Player] setSkipSilenceEnabled failed: $e');
          }
        });
        // Pitch is a ratio to ExoPlayer; the slider is in semitones.
        EqualizerService().setPitchApplier((semitones) {
          try {
            _handler?.player.setPitch(math.pow(2.0, semitones / 12.0).toDouble());
          } catch (e) {
            debugPrint('[Player] setPitch failed: $e');
          }
        });
      }
      // iOS native engine: keep the processing tap attached whenever any
      // EQ/effect is active so effects work with the band EQ off.
      if (AppPlatform.isIOS) {
        EqualizerService().setTapApplier((active) {
          try {
            if (active) {
              _handler?.player.attachEqualizerTap();
            } else {
              _handler?.player.detachEqualizerTap();
            }
          } catch (e) {
            debugPrint('[Player] tap applier failed: $e');
          }
        });
      }
      // Initialize cached skip amounts so notification icons show the correct values
      _handler!._cachedForwardSkip = fwdSkip;
      _handler!._cachedBackSkip = backSkip;
      // Nothing is loaded yet so there's no library override to apply; the
      // per-library amounts follow from _syncNotifSkipCache once an item does.
      if (AppPlatform.isIOS) {
        unawaited(_pushIosSkipIntervals(fwdSkip, backSkip));
      }
      _handler!._cachedNotifSpeedBookmark =
          await PlayerSettings.getMediaControlsSpeedBookmark();
      _handler!._cachedLockSeekBar = await PlayerSettings.getLockSeekBar();
      debugPrint('[Player] AudioService initialized');
      if (AppPlatform.isIOS) unawaited(_reportPreviousBackgroundDeath());
      if (AppPlatform.isAndroid) unawaited(_reportPreviousExit());
      unawaited(TranscriptionService.instance.reportInterruptedRun());
      // Configure streaming cache if enabled
      final cacheSizeMb = await PlayerSettings.getStreamingCacheSizeMb();
      debugPrint('[Player] Streaming cache setting: $cacheSizeMb MB');
      if (!AppPlatform.lacksPhonePlugins && cacheSizeMb > 0) {
        try {
          await AudioPlayer.configureStreamingCache(cacheSizeMb);
          debugPrint('[Player] Streaming cache configured: $cacheSizeMb MB');
        } catch (e) {
          debugPrint('[Player] Streaming cache init failed: $e');
        }
      }
      // Load notification chapter progress setting and watch for changes
      _instance._notifChapterMode =
          await PlayerSettings.getNotificationChapterProgress();
      _instance._nowPlayingLayoutJson =
          await PlayerSettings.getNowPlayingLayout();
      _instance._nowPlayingLayout =
          NowPlayingLayout.fromJson(_instance._nowPlayingLayoutJson);
      _instance._speedAdjustedTime = await PlayerSettings.getSpeedAdjustedTime();
      PlayerSettings.settingsChanged.addListener(_instance._onSettingsChanged);
      // Configure audio session for audiobook playback
      await _configureAudioSession();
    } catch (e, st) {
      debugPrint('[Player] AudioService.init failed: $e\n$st');
    } finally {
      if (!_initCompleter.isCompleted) _initCompleter.complete();
    }
  }

  static StreamSubscription? _interruptSub;
  static StreamSubscription? _noisySub;
  static StreamSubscription? _devicesSub;
  // Output routes whose disappearance should pause playback. becomingNoisy only
  // fires when the LAST external output leaves (audio falling back to the phone
  // speaker). With two outputs connected at once (e.g. car stereo + earbuds),
  // dropping one just reroutes to the other and never fires it, so the book
  // plays on silently. Watching device removal covers that gap.
  // Set true when BT/headphones disconnect so the interruption handler
  // won't auto-resume playback onto the phone speaker.
  static bool _noisyPause = false;
  // Whether BT audio was connected when the current interruption began.
  static bool _wasOnBluetooth = false;
  static bool _duckBriefInterruptions = false;
  static bool _keepPlayingWithOtherApps = false;
  static double? _volumeBeforeInterruptionDuck;
  // Safety net for a duck whose matching "end" event never arrives - a known
  // flaky spot on Android, more so over Bluetooth where focus changes route
  // through an extra AVRCP arbitration layer. A duck is supposed to be brief
  // (a notification chime, a voice prompt); if it's still down after this
  // long with nothing having restored it, force it back rather than leaving
  // playback parked at 35% volume for the rest of the session.
  static Timer? _duckWatchdogTimer;
  static const _duckWatchdogTimeout = Duration(seconds: 4);

  static void _armDuckWatchdog() {
    _duckWatchdogTimer?.cancel();
    _duckWatchdogTimer = Timer(_duckWatchdogTimeout, () {
      final stuckVolume = _volumeBeforeInterruptionDuck;
      if (stuckVolume == null) return;
      _volumeBeforeInterruptionDuck = null;
      debugPrint(
        '[AudioSession] Duck watchdog: no end event after '
        '${_duckWatchdogTimeout.inSeconds}s - forcing volume back to $stuckVolume',
      );
      unawaited(_instance._player?.setVolume(stuckVolume));
    });
  }

  static void _clearDuckWatchdog() {
    _duckWatchdogTimer?.cancel();
    _duckWatchdogTimer = null;
  }
  // Last time the app entered the foreground. Used by [ClickDebug] to see
  // whether a MediaSession click's 400ms debounce window overlapped with
  // an app-foreground event — the fingerprint of an Android Auto disconnect
  // handing control back to the phone.
  static DateTime? _lastForegroundAt;
  // Last time we observed BT/AA to be the audio route while playing/pausing.
  // Stamped from interruption begin/end and from service.pause(). Used at
  // click arrival to detect the AA-disconnect phantom: BT was the route
  // recently, isn't now, click came in while bg + not playing. Some devices
  // (Pixel 10 Pro on Android 16 with Android Auto observed) never fire
  // becomingNoisy on AA disconnect, so the 5s _noisyPauseAt guard alone
  // can't catch the delayed phantom MediaButton.media event.
  static DateTime? _lastPlayedOnBtAt;
  static const _eqChannel = MethodChannel('com.absorb.equalizer');

  /// Check if BT audio (A2DP/SCO) is currently connected via native AudioManager.
  static Future<bool> _isBluetoothAudioConnected() async {
    if (AppPlatform.lacksPhonePlugins) return false;
    try {
      final result = await _eqChannel.invokeMethod<bool>(
        'isBluetoothAudioConnected',
      );
      return result ?? false;
    } catch (e) {
      debugPrint('[AudioSession] BT check failed: $e');
      return false;
    }
  }

  /// Public view of the BT check, for callers that need to compensate for
  /// the delay Bluetooth adds between the playhead and your ears.
  static Future<bool> isBluetoothAudioConnected() =>
      _isBluetoothAudioConnected();

  /// True when BT/headphones just disconnected — callers can check before
  /// starting new playback to avoid blasting audio on the phone speaker.
  static bool get wasNoisyPause => _noisyPause;

  /// Whether the phone is ringing or in a call (including VoIP), read from
  /// the audio mode, which needs no permission. False where unknown.
  static Future<bool> _isInCall() async {
    if (!AppPlatform.isAndroid) return false;
    try {
      final mode = await _eqChannelForDiag.invokeMethod<int>('audioMode');
      return mode != null && mode != 0;
    } catch (_) {
      return false;
    }
  }

  static Future<void> _configureAudioSession() async {
    if (AppPlatform.lacksPhonePlugins) return;
    final session = await AudioSession.instance;
    _duckBriefInterruptions =
        AppPlatform.isAndroid &&
        await PlayerSettings.getDuckBriefInterruptions();
    _keepPlayingWithOtherApps =
        AppPlatform.isAndroid &&
        await PlayerSettings.getKeepPlayingWithOtherApps();

    await session.configure(
      AudioSessionConfiguration(
        // iOS: playback category — no duckOthers so iOS properly recognises this
        // app as the Now Playing app and shows lock screen / Control Center controls.
        avAudioSessionCategory: AVAudioSessionCategory.playback,
        avAudioSessionMode: AVAudioSessionMode.spokenAudio,
        avAudioSessionRouteSharingPolicy:
            AVAudioSessionRouteSharingPolicy.longFormAudio,
        avAudioSessionCategoryOptions: AppPlatform.isIOS
            ? AVAudioSessionCategoryOptions.none
            : AVAudioSessionCategoryOptions.duckOthers,
        // Android: speech content type enables OS voice-intelligibility
        // processing so audiobooks play at normal listening levels. Matches the
        // reference ABS Android client.
        androidAudioAttributes: AndroidAudioAttributes(
          contentType: AndroidAudioContentType.speech,
          usage: AndroidAudioUsage.media,
        ),
        androidAudioFocusGainType: AndroidAudioFocusGainType.gain,
        androidWillPauseWhenDucked: !_duckBriefInterruptions,
      ),
    );
    // Don't activate the session here — defer to first playback.
    // Activating during init creates a stale MediaSession that Android
    // can garbage-collect after hours in background, leaving bluetooth /
    // notification / widget controls permanently broken.
    // play() and startLocalPlayback() call setActive(true) before playing.

    _interruptSub?.cancel();
    _interruptSub = session.interruptionEventStream.listen(
      (event) async {
        try {
          final service = _instance;

          if (event.begin) {
            if (event.type == AudioInterruptionType.duck &&
                _duckBriefInterruptions) {
              if (service.isPlaying && _volumeBeforeInterruptionDuck == null) {
                final currentVolume = service._player?.volume ?? 1.0;
                _volumeBeforeInterruptionDuck = currentVolume;
                await service._player?.setVolume(
                  (currentVolume * 0.35).clamp(0.0, 1.0).toDouble(),
                );
                _armDuckWatchdog();
                debugPrint(
                  '[AudioSession] Interrupted (${event.type}) — ducking',
                );
              }
              return;
            }

            final duckedVolume = _volumeBeforeInterruptionDuck;
            if (duckedVolume != null) {
              _volumeBeforeInterruptionDuck = null;
              _clearDuckWatchdog();
              await service._player?.setVolume(duckedVolume);
            }
            // Android reports another app taking the audio for good as
            // `unknown`, and on a Pixel an incoming call arrives the same
            // way, so the phone's audio mode tells the two apart. With the
            // setting on, another app is the one case to play through.
            final lossType = AppPlatform.isAndroid &&
                event.type == AudioInterruptionType.unknown;
            final inCall = lossType && await _isInCall();
            if (_keepPlayingWithOtherApps && lossType && !inCall) {
              debugPrint(
                '[AudioSession] Another app took the audio - keeping playing',
              );
              return;
            }
            if (service.isPlaying) {
              debugPrint(
                '[AudioSession] Interrupted (${event.type}) — pausing',
              );
              _wasOnBluetooth = await _isBluetoothAudioConnected();
              if (_wasOnBluetooth) _lastPlayedOnBtAt = DateTime.now();
              debugPrint('[AudioSession] Was on BT: $_wasOnBluetooth');
              // Pause the underlying player directly, not service.pause(), to keep
              // the interruption lightweight (service.pause() also saves and syncs,
              // which a transient duck doesn't need). Still stamp _lastPauseTime so
              // resume runs auto-rewind per the user's settings: calls and nav
              // prompts rewind like a manual pause, gated by activationDelay.
              await service._player?.pause();
              service._lastPauseTime = DateTime.now();
              // Keep the spot on this phone, though: without it a server copy
              // up to a sync behind could be taken for newer (GH #440).
              unawaited(service._saveProgressLocal(service.position));
              // Android reports a permanent focus loss (another app or the
              // car's own source took the audio for good) as `unknown`; calls
              // and nav prompts come as transient `pause`/`duck`. Only a
              // transient one should come back by itself - resuming after a
              // permanent one talked over the radio the user switched to.
              // A call that came in as a permanent loss is still a call:
              // it ends, and the book should come back like any other.
              final permanentLoss = lossType && !inCall;
              service._wasPlayingBeforeInterrupt = !permanentLoss;
              if (permanentLoss) {
                debugPrint(
                  '[AudioSession] Permanent focus loss - not resuming on its own',
                );
              }
              // The notification reads the player directly, but the home
              // widget, cards and watch only refresh on notify - without this
              // the widget kept showing "playing" and ticking its clock
              // through the whole interruption.
              service.notifyListeners();
            }
          } else {
            if (event.type == AudioInterruptionType.duck &&
                _duckBriefInterruptions) {
              final previousVolume = _volumeBeforeInterruptionDuck;
              _volumeBeforeInterruptionDuck = null;
              _clearDuckWatchdog();
              if (previousVolume != null) {
                await service._player?.setVolume(previousVolume);
                debugPrint(
                  '[AudioSession] Interruption ended — volume restored',
                );
              }
              return;
            }

            // iOS says whether the interrupter wants us back: shouldResume is
            // set after a call, Siri or an alarm, and clear when the user
            // started another app's audio. audio_session surfaces that as
            // type `pause` (resume) versus `unknown` (don't). Resuming over a
            // clear flag would cut off the app the user had just chosen - it
            // only failed to because the activation was refused while that
            // app still held the audio.
            if (AppPlatform.isIOS &&
                event.type == AudioInterruptionType.unknown &&
                service._wasPlayingBeforeInterrupt) {
              debugPrint(
                '[AudioSession] Interruption ended without shouldResume - staying paused',
              );
              service._wasPlayingBeforeInterrupt = false;
              return;
            }
            // Don't auto-resume if the pause was caused by BT/headphone disconnect.
            // Some devices fire interruption-end AFTER becoming-noisy, which would
            // resume playback on the phone speaker.
            if (_noisyPause) {
              debugPrint(
                '[AudioSession] Interruption ended after noisy — skipping resume',
              );
              service._wasPlayingBeforeInterrupt = false;
              return;
            }
            if (service._wasPlayingBeforeInterrupt) {
              service._wasPlayingBeforeInterrupt = false;
              await Future.delayed(const Duration(milliseconds: 600));
              // Re-check: another event (like becoming-noisy) might have fired
              // during the delay.
              if (_noisyPause) return;
              // Don't double-resume: Assistant may already have called play().
              if (service._player?.playing == true) return;
              // If we were on BT when interrupted, check if BT is still connected.
              // Some car head units never send AUDIO_BECOMING_NOISY on disconnect,
              // so _noisyPause alone is not enough.
              if (_wasOnBluetooth) {
                final stillOnBt = await _isBluetoothAudioConnected();
                debugPrint(
                  '[AudioSession] Interruption ended — was BT, still BT: $stillOnBt',
                );
                if (!stillOnBt) {
                  debugPrint(
                    '[AudioSession] BT disconnected during interruption — skipping resume',
                  );
                  _noisyPause = true;
                  return;
                }
                _lastPlayedOnBtAt = DateTime.now();
              }
              debugPrint('[AudioSession] Interruption ended — resuming');
              await service.play(logDetail: 'Auto-resumed after interruption');
            }
          }
        } catch (e) {
          debugPrint('[AudioSession] Interruption handler error: $e');
        }
      },
      onError: (e) {
        debugPrint(
          '[AudioSession] Interruption stream error - re-subscribing: $e',
        );
        _configureAudioSession();
      },
    );

    // Headphones unplugged / BT disconnected — pause, no auto-resume
    _noisySub?.cancel();
    _noisySub = session.becomingNoisyEventStream.listen(
      (_) async {
        try {
          final service = _instance;
          debugPrint('[AudioSession] Becoming noisy — pausing');
          debugPrint(
            '[ClickDebug] becoming-noisy fired: bg=${service._isBackgrounded}, playing=${service.isPlaying}',
          );
          _noisyPause = true;
          service._wasPlayingBeforeInterrupt = false;
          // Cancel any pending media-button click from the BT disconnect so the
          // delayed click handler doesn't resume playback on the phone speaker.
          _handler?.cancelPendingClick();
          if (service.isPlaying) {
            await service.pause();
          }
        } catch (e) {
          debugPrint('[AudioSession] Noisy handler error: $e');
        }
      },
      onError: (e) {
        debugPrint('[AudioSession] Noisy stream error - re-subscribing: $e');
        _configureAudioSession();
      },
    );

    // Pause when an output route we could be playing through disappears, even
    // if another output stays connected - the silent-playback case becomingNoisy
    // misses. Mirrors the noisy handler. Android only; iOS already pauses on
    // route loss. Tradeoff: a rare false pause if you power off a second output
    // you weren't actually listening on, undone with a single tap on play.
    _devicesSub?.cancel();
    if (AppPlatform.isAndroid) {
      _devicesSub = session.devicesChangedEventStream.listen(
        (event) async {
          try {
            final service = _instance;
            if (!service.isPlaying) return;
            final lost = event.devicesRemoved
                .where(
                  (d) =>
                      d.isOutput && externalAudioOutputTypes.contains(d.type),
                )
                .toSet();
            if (lost.isEmpty) return;
            debugPrint(
              '[AudioSession] Output route removed: '
              '${lost.map((d) => '${d.type.name} "${d.name}"').join(', ')}',
            );
            // Settle re-check: some devices drop and re-add a route when
            // playback starts or the link hiccups. Only pause if it stays gone.
            await Future.delayed(const Duration(seconds: 2));
            if (!service.isPlaying) return;
            final current = await session.getDevices(includeInputs: false);
            if (!lost.any((d) => !current.contains(d))) {
              debugPrint('[AudioSession] Output route came back - keeping playback');
              return;
            }
            // Android Auto carries the audio itself, over USB or WiFi. The
            // Bluetooth link to the head unit or a helmet runs beside it and
            // can drop and come back every few minutes without the audio ever
            // stopping, and pausing on those drops stopped the book every
            // 2-3 minutes on a motorcycle head unit (#369). If Android Auto
            // goes away for real it sends its own pause.
            if (await AudioPlayerHandler._carClientRecentlySeen()) {
              debugPrint(
                '[AudioSession] Output route removed while playing - car client seen, keeping playback',
              );
              return;
            }
            debugPrint(
              '[AudioSession] Output route removed while playing - pausing',
            );
            _noisyPause = true;
            service._wasPlayingBeforeInterrupt = false;
            // Short guard: this pause is ours, not a platform disconnect, so
            // a Play a couple of seconds later is the user. The full 5s threw
            // those away and Play looked dead (#369).
            _handler?.cancelPendingClick(guardMs: 1500);
            if (service.isPlaying) await service.pause();
          } catch (e) {
            debugPrint('[AudioSession] Device-change handler error: $e');
          }
        },
        onError: (e) {
          debugPrint(
            '[AudioSession] Device-change stream error - re-subscribing: $e',
          );
          _configureAudioSession();
        },
      );
    }
  }

  /// Refresh the media session when the app returns to foreground.
  /// After a long background idle, Android can garbage-collect the stale
  /// MediaSession, leaving bluetooth / notification / widget controls dead.
  /// Re-activating the audio session and re-pushing handler state recovers it.
  static void onAppBackgrounded() {
    _instance._isBackgrounded = true;
    debugPrint('[ClickDebug] App backgrounded');
    if (AppPlatform.isIOS) _trimMemoryForBackground();
  }

  /// iOS: a paused app in the background has no audio keeping it alive, is
  /// suspended within seconds, and is a jetsam candidate whenever memory gets
  /// tight. When iOS evicts it, the audio session goes with it, and any app
  /// Absorb interrupted earlier is told to resume - it starts playing and owns
  /// Now Playing from then on. Nothing keeps a paused app alive for hours, so
  /// the lever is footprint: drop the decoded covers (up to 100MB) on the way
  /// out. They reload lazily on return, and the screen is off meanwhile.
  static void _trimMemoryForBackground() {
    final cache = PaintingBinding.instance.imageCache;
    final beforeMb = cache.currentSizeBytes ~/ 1048576;
    cache.clear();
    cache.clearLiveImages();
    final rssMb = kIsWeb ? -1 : ProcessInfo.currentRss ~/ 1048576;
    unawaited(_logBackgroundMemory(rssMb, beforeMb));
  }

  static const _bgMarkerKey = 'ios_bg_marker';

  /// iOS memory figures from the native side: `footprint` is what jetsam
  /// judges (phys_footprint, not RSS) and `available` is how much more the
  /// process may take before it is killed. Both in MB, -1 when unavailable.
  static Future<({int footprintMb, int availableMb})> iosMemoryInfo() async {
    try {
      final info = await _eqChannelForDiag
          .invokeMethod<Map<dynamic, dynamic>>('getMemoryInfo');
      int mb(dynamic v) {
        final n = (v as num?)?.toInt() ?? -1;
        return n < 0 ? -1 : n ~/ 1048576;
      }
      return (
        footprintMb: mb(info?['footprint']),
        availableMb: mb(info?['available']),
      );
    } catch (_) {
      return (footprintMb: -1, availableMb: -1);
    }
  }

  /// Log the footprint on the way out and leave a marker that the next
  /// foreground clears. If a later launch still finds it, the process never
  /// came back from the background: iOS ended it there (or the user swiped
  /// it away).
  static Future<void> _logBackgroundMemory(int rssMb, int droppedMb) async {
    final m = await iosMemoryInfo();
    final playing = _instance.isPlaying;
    debugPrint('[Memory] Backgrounded: footprint=${m.footprintMb}MB '
        'available=${m.availableMb}MB rss=${rssMb}MB playing=$playing, '
        'dropped ${droppedMb}MB of decoded covers');
    try {
      final prefs = await SharedPreferences.getInstance();
      await prefs.setString(
        _bgMarkerKey,
        '${DateTime.now().millisecondsSinceEpoch}|${m.footprintMb}|'
        '${m.availableMb}|$playing',
      );
    } catch (_) {}
  }

  static Future<void> _logForegroundMemory() async {
    try {
      final prefs = await SharedPreferences.getInstance();
      await prefs.remove(_bgMarkerKey);
    } catch (_) {}
    final m = await iosMemoryInfo();
    debugPrint('[Memory] Foregrounded: footprint=${m.footprintMb}MB '
        'available=${m.availableMb}MB');
  }

  static Future<void> _reportPreviousBackgroundDeath() async {
    try {
      final prefs = await SharedPreferences.getInstance();
      final raw = prefs.getString(_bgMarkerKey);
      if (raw == null) return;
      await prefs.remove(_bgMarkerKey);
      final parts = raw.split('|');
      final at = int.tryParse(parts[0]) ?? 0;
      final ago = DateTime.now()
          .difference(DateTime.fromMillisecondsSinceEpoch(at))
          .inMinutes;
      String part(int i) => parts.length > i ? parts[i] : '?';
      debugPrint('[Memory] Previous process ended in the background, '
          '${ago}min after it went there (or was swiped away): '
          'footprint=${part(1)}MB available=${part(2)}MB playing=${part(3)}');
    } catch (_) {}
  }

  /// Flutter forwards iOS memory warnings here (and drops its image cache on
  /// its own). Logging them with the numbers says how close to the edge the
  /// app was, before jetsam makes the decision for it.
  static void onMemoryPressure() {
    if (!AppPlatform.isIOS) return;
    unawaited(() async {
      final m = await iosMemoryInfo();
      debugPrint('[Memory] iOS memory warning: footprint=${m.footprintMb}MB '
          'available=${m.availableMb}MB');
    }());
  }

  static Future<void> onAppForegrounded() async {
    final service = _instance;
    service._isBackgrounded = false;
    _lastForegroundAt = DateTime.now();
    if (AppPlatform.isIOS) unawaited(_logForegroundMemory());
    // Relative timing on foreground arrival is the second half of the
    // AA-disconnect fingerprint (variant 3): raw pause, then foreground
    // within ~2s. Log sincePrevPauseMs / sincePrevPlayMs so the disconnect
    // pattern is obvious on one line.
    final handler = _handler;
    int sincePrevPauseMs = -1;
    int sincePrevPlayMs = -1;
    if (handler != null) {
      if (handler._lastHandlerPauseAt != null) {
        sincePrevPauseMs = _lastForegroundAt!
            .difference(handler._lastHandlerPauseAt!)
            .inMilliseconds;
      }
      if (handler._lastHandlerPlayAt != null) {
        sincePrevPlayMs = _lastForegroundAt!
            .difference(handler._lastHandlerPlayAt!)
            .inMilliseconds;
      }
    }
    final aaDisconnectSuspect =
        sincePrevPauseMs >= 0 && sincePrevPauseMs < 3000;
    debugPrint(
      '[ClickDebug] App foregrounded: sincePrevPauseMs=$sincePrevPauseMs, '
      'sincePrevPlayMs=$sincePrevPlayMs, aaDisconnectSuspect=$aaDisconnectSuspect',
    );
    service.resetServerSyncBackoff();
    if (AppPlatform.isIOS && service._iosResyncPending) {
      unawaited(service._iosForegroundResyncIfNeeded());
    }
    // After a widget-driven session the shared engine may have kept playing
    // (or advanced) while Flutter was suspended. Adopt its live state rather
    // than reloading - reloading would restart the same stream (bug #285).
    if (AppPlatform.isIOS && service.hasBook) {
      await service._iosReconcileEngineOnForeground();
    }
    if (!service.hasBook) return;
    final sessionAlive = service._playbackSessionId != null;
    debugPrint(
      '[MediaSession] Foregrounded - refreshing (playing=${service.isPlaying}, session=$sessionAlive, item=${service._currentItemId})',
    );
    // Alpha: when session=false, the playback session was closed (pause
    // timeout) and likely handler.stop() ran too. Log handler state so we
    // can see whether the MediaSession is recoverable. Strip before beta.
    if (!sessionAlive && handler != null) {
      try {
        final ps = handler.playbackState.value;
        debugPrint(
          '[MediaSession] Recovery diagnostic: handlerPlaying=${ps.playing}, '
          'processingState=${ps.processingState.name}, '
          'playerPlaying=${handler.player.playing}, '
          'playerProcessing=${handler.player.processingState.name}',
        );
      } catch (e) {
        debugPrint('[MediaSession] Recovery diagnostic error: $e');
      }
    }
    // Flush missed UI updates from background
    service.notifyListeners();
    // Flush overdue server sync
    if (service.isPlaying && service._currentItemId != null) {
      final sinceSync = DateTime.now()
          .difference(service._lastServerSync)
          .inSeconds;
      if (sinceSync > 20) {
        service._syncToServer(service.position);
      }
    }
    // Re-activate audio session to get a fresh system token — but only while
    // actually playing. Doing it on every foreground grabbed AUDIOFOCUS_GAIN
    // even when paused/idle, pausing other apps' audio (e.g. Spotify) the
    // moment Absorb was opened without the user ever pressing play. When not
    // playing we don't need focus; the MediaSession refresh below doesn't
    // require it, and play()/startLocalPlayback reacquire focus themselves.
    if (service.isPlaying) {
      try {
        await _setAudioSessionActive(true);
      } catch (_) {}
    } else if (AppPlatform.isIOS && service.hasBook) {
      // Paused with a book loaded: an interruption while iOS had this app
      // suspended may have silently dropped the Now Playing claim. The
      // Android concern above (activation grabbing focus and pausing other
      // apps) doesn't apply - the reassert has its own other-audio guard.
      await service.reassertIosClaimWhilePaused('foreground');
    }
    // Re-push playback state so the system re-registers the MediaSession
    _handler?.refreshPlaybackState();
    // Re-push media item so notification metadata is fresh
    if (service._currentItemId != null && service._currentTitle != null) {
      final chapterTitle =
          service._lastNotifiedChapterIndex >= 0 && service._chapters.isNotEmpty
          ? (service._chapters[service._lastNotifiedChapterIndex]
                    as Map<String, dynamic>)['title']
                as String?
          : null;
      service._pushMediaItem(
        service._mediaItemKey,
        service._currentTitle!,
        service._currentAuthor ?? '',
        service._currentCoverUrl,
        service._totalDuration,
        chapter: chapterTitle,
      );
      debugPrint('[MediaSession] Re-pushed media item and playback state');
    }
  }

  String? _currentEpisodeId;
  String? get currentEpisodeId => _currentEpisodeId;

  // Which ABS library the currently-loaded item belongs to, so per-library
  // skip overrides (see PlayerSettings.getSkipOverride) can resolve. Set
  // wherever _currentItemId/_currentEpisodeId are (playItem + queue advance);
  // null when the caller didn't have it available (falls back to global skip).
  String? _currentLibraryId;
  String? get currentLibraryId => _currentLibraryId;

  /// MediaSession / AA item id. Podcast episodes use the compound
  /// `parentId-episodeId` key so AA doesn't treat them as a separate item
  /// from the initial load. Books use the plain itemId.
  String get _mediaItemKey => _currentEpisodeId != null
      ? '${_currentItemId!}-$_currentEpisodeId'
      : _currentItemId!;

  String? _currentEpisodeTitle;
  String? get currentEpisodeTitle => _currentEpisodeTitle;

  Future<String?> playItem({
    required ApiService api,
    required String itemId,
    required String title,
    required String author,
    required String? coverUrl,
    required double totalDuration,
    required List<dynamic> chapters,
    double startTime = 0,
    bool forceStartTime = false,
    String? episodeId,
    String? episodeTitle,
    String? libraryId,
    // Started from the app's own screen. Only those wait (briefly, capped)
    // for the server's saved position before audio; plays from Android
    // Auto, the widget, headphones or a cold-start restore begin at the
    // phone's own position immediately. See play().
    bool fromUi = false,
    // Load the item into the player at its resume position but leave it
    // paused, with no playback session: a headset press then always has a
    // live target and the live transcript can build its runway, without
    // deciding for the user that audio starts now. Downloaded items only -
    // a streamed item plays normally.
    bool loadOnly = false,
  }) async {
    _pauseRequested = false;
    _playFromUi = fromUi;
    if (_handler == null) {
      debugPrint('[Player] Handler not yet initialized, waiting…');
      // If startup never got as far as init, this would wait forever and the
      // play button would spin with no error.
      await _initCompleter.future
          .timeout(const Duration(seconds: 15), onTimeout: () {});
    }
    if (_handler == null) {
      debugPrint('[Player] Handler init failed, cannot play');
      return 'Player failed to initialize';
    }

    // Alpha: catalog every playItem caller so we can find the phantom
    // resume that fires after an AA disconnect without going through
    // Handler.play() / Service.play(). Strip before next beta.
    debugPrint(
      '[PlayItemEntry] itemId=$itemId episodeId=$episodeId '
      'startTime=$startTime forceStartTime=$forceStartTime fromUi=$fromUi\n'
      'Caller:\n${StackTrace.current}',
    );

    // Don't start local playback while casting
    final cast = ChromecastService();
    if (cast.isCasting) {
      debugPrint('[Player] Cast active - skipping local playback');
      return null;
    }

    _beginAdvanceBuffering();

    final playbackGeneration = ++_playbackGeneration;

    // Stop old audio immediately so it doesn't keep playing while the new
    // source is loading (avoids briefly hearing the previous book).
    await _player?.pause();

    // Podcast episodes arrive two ways: episode-shaped (title = the episode)
    // and show-shaped continue/queue entries (title = the show, episodeTitle =
    // the episode, author often blank). Normalise to episode-as-title +
    // show-as-artist so the episode shows everywhere — notification, lock
    // screen, Android Auto, and the server listening session.
    if (episodeId != null &&
        episodeTitle != null &&
        episodeTitle.isNotEmpty &&
        episodeTitle != title) {
      if (author.isEmpty) author = title; // `title` is the show name here
      title = episodeTitle;
    }

    _isLoadingNewItem = true;
    _api = api;
    _currentItemId = itemId;
    _currentEpisodeId = episodeId;
    _currentLibraryId = libraryId;
    debugPrint(
      '[SkipDebug] playItem libraryId=$libraryId (item=$itemId ep=$episodeId)',
    );
    _resolveMissingLibraryId(itemId, episodeId);
    _syncNotifSkipCache();
    // Reset local-session mode for every new play; _playFromLocal re-enables it
    // for downloaded items. Without this it leaks from a prior downloaded play
    // into a following streaming play and misroutes the listening time.
    _localSessionMode = false;
    _pendingLoadOnlySession = null;
    _currentEpisodeTitle = episodeTitle;
    _currentTitle = title;
    _currentAuthor = author;
    _currentNarrator = null;
    _currentSeries = null;
    _currentCoverUrl = coverUrl;
    _totalDuration = totalDuration;
    _metaDuration = totalDuration;
    _chapters = chapters;
    _shortLocalDurationSec = null; // re-evaluated per source in _playFromLocal
    _handler?.updateChaptersQueue(chapters);
    // New book = fresh session — clear any auto sleep dismissal
    SleepTimerService().resetDismiss();

    // Progress key: compound for episodes, plain for books
    final progressKey = playbackDownloadKey(itemId, episodeId);

    // Notify rolling download listener that a new item is playing
    try {
      await _onPlayStartedCallback?.call(progressKey, totalDuration);
    } catch (e) {
      debugPrint('[Player] Playback-start preparation failed: $e');
    }

    // Check for local saved position (skip if startTime was forced).
    // Always prefer the local position when it's further ahead - the
    // caller's startTime may be stale (e.g. Android Auto browse tree
    // entry cached before the user listened further).
    final localProgressAtStart = await _progressSync.getLocal(progressKey);
    final localPos =
        (localProgressAtStart?['currentTime'] as num?)?.toDouble() ?? 0;
    var localTimestampAtStart =
        (localProgressAtStart?['timestamp'] as num?)?.toInt() ?? 0;
    if (localPos > 0 && !forceStartTime) {
      if (startTime == 0 || localPos > startTime + 1.0) {
        debugPrint(
          '[Player] Resuming from local position: ${localPos}s (caller startTime was ${startTime}s)',
        );
        startTime = localPos;
      }
    }

    // The widget stash is independent of the scoped SharedPreferences cache.
    // That matters on Android Auto cold starts, where a long-lived headless
    // engine can have an older browse entry and an older preferences snapshot.
    if (!forceStartTime) {
      final stashedPos = await HomeWidgetService().getStashedNowPlayingPosition(
        itemId,
        episodeId,
      );
      final newerStashedPos = HomeWidgetService.newerStashedNowPlayingPosition(
        startTime,
        stashedPos,
      );
      if (newerStashedPos != null) {
        debugPrint(
          '[Player] Resuming from stashed widget position: ${newerStashedPos}s (was ${startTime}s)',
        );
        startTime = newerStashedPos;
        localTimestampAtStart = DateTime.now().millisecondsSinceEpoch;
      }
      // iOS: the shared engine may be playing this very item right now (the
      // native core started it from a headset press and Dart never adopted
      // it). Its position is the live truth - the stash was written once at
      // press time and local progress stopped at the last pause, so resuming
      // from either threw away everything listened since. The stash match
      // above ties the engine's content to this episode; the engine itself
      // only knows the library item.
      if (AppPlatform.isIOS && (episodeId == null || stashedPos != null)) {
        try {
          final engine = await _player?.engineState();
          if (engine != null &&
              engine.isLoaded &&
              engine.itemId == itemId &&
              engine.globalPositionS > startTime + 1.0) {
            debugPrint(
              '[Player] Resuming from live engine position: '
              '${engine.globalPositionS.toStringAsFixed(1)}s (was ${startTime}s)',
            );
            startTime = engine.globalPositionS;
            localTimestampAtStart = DateTime.now().millisecondsSinceEpoch;
          }
        } catch (_) {}
      }
    }

    // Set seek target early so the UI doesn't flash chapter 1 while loading
    if (startTime > 0) {
      _lastSeekTargetSeconds = startTime;
      _lastSeekTime = DateTime.now();
    }
    notifyListeners();

    // Cancel old sync/completion listeners before switching sources.
    // Without this, stale position or processingState events from the
    // previous book can fire during setAudioSource() and trigger
    // _onPlaybackComplete(), killing the new playback before it starts.
    _syncSub?.cancel();
    _syncSub = null;
    _completionSub?.cancel();
    _completionSub = null;
    _nativeAutoAdvanceSub?.cancel();
    _nativeAutoAdvanceSub = null;
    _indexSub?.cancel();
    _indexSub = null;
    _lastKnownPositionSec = 0;
    _lastSeekTargetSec = null;
    _isCompletingBook = false;

    // Check if downloaded — play locally
    String? result;
    if (episodeId == null && !api.isBookOrbit && NarratedBooks.contains(itemId) &&
        !_downloadService.isDownloaded(progressKey)) {
      // An Audiobookshelf EPUB that reads itself aloud: its audio files play
      // straight out of the EPUB on the server, and otherwise like a download.
      final prefs = await SharedPreferences.getInstance();
      final offline = (prefs.getBool('manual_offline_mode') ?? false) || _knownOffline;
      final stream = offline ? null : await NarrationStream.instance.open(api, itemId, startTime: startTime);
      if (_startSuperseded(playbackGeneration)) {
        return _abandonStart(null, null, 'narration, after opening the stream');
      }
      if (stream == null) {
        debugPrint('[Player] $itemId is narration that is not downloaded and '
            '${offline ? 'this phone is offline' : 'could not be streamed'} - not starting');
        _endAdvanceBuffering();
        _clearState();
        return 'Download this book to play its narration';
      }
      // The stream's timeline is laid on the audio's real lengths.
      totalDuration = stream.duration;
      _totalDuration = stream.duration;
      if (stream.chapters.isNotEmpty) {
        chapters = stream.chapters;
        _chapters = stream.chapters;
        _handler?.updateChaptersQueue(stream.chapters);
      }
      result = await _playFromLocal(
        progressKey,
        title,
        author,
        coverUrl,
        totalDuration,
        chapters,
        startTime,
        forceStartTime,
        loadOnly,
        playbackGeneration,
        stream,
      );
    } else if (_downloadService.isDownloaded(progressKey)) {
      result = await _playFromLocal(
        progressKey,
        title,
        author,
        coverUrl,
        totalDuration,
        chapters,
        startTime,
        forceStartTime,
        loadOnly,
        playbackGeneration,
      );
    } else {
      // Check manual offline — don't stream from server
      final prefs = await SharedPreferences.getInstance();
      final manualOffline = prefs.getBool('manual_offline_mode') ?? false;
      if (_startSuperseded(playbackGeneration)) {
        return _abandonStart(null, null, 'before choosing a stream path');
      }
      if (manualOffline) {
        debugPrint(
          '[Player] Manual offline — cannot stream non-downloaded item',
        );
        _endAdvanceBuffering();
        _clearState();
        return 'This item isn\'t downloaded and offline mode is on';
      }
      // Try to play from cached session metadata first (instant start)
      final cachedSession = await SessionCache.load(
        itemId: itemId,
        episodeId: episodeId,
      );
      if (cachedSession != null) {
        // Race the real session against the cache. When the server answers
        // inside the window (LAN, good WiFi) the play starts through the
        // fresh path with tokenless session URLs - immune to token expiry -
        // and its saved position; only a slow server falls back to the
        // instant cached start. An app-screen play waits the full position
        // cap since that is its one chance to pick up another device's
        // progress before audio; everything else keeps the short window.
        // The in-flight POST is handed to the background refresh either way
        // so a second session is never opened.
        final pendingSession = episodeId != null
            ? api.startEpisodePlaybackSession(itemId, episodeId)
            : api.startPlaybackSession(itemId);
        final raceWindow =
            fromUi ? _serverPositionCheckCap : _sessionRaceWindow;
        Map<String, dynamic>? racedSession;
        try {
          racedSession = await pendingSession.timeout(raceWindow);
        } catch (_) {
          racedSession = null;
        }
        if (racedSession != null) {
          debugPrint(
            '[Player] Session answered within the race window - using fresh path',
          );
          result = await _playFromServer(
            api,
            itemId,
            title,
            author,
            coverUrl,
            totalDuration,
            chapters,
            startTime,
            forceStartTime: forceStartTime,
            preFetchedSession: racedSession,
            generation: playbackGeneration,
          );
        } else {
          result = await _playFromSessionCache(
            api,
            itemId,
            title,
            author,
            coverUrl,
            totalDuration,
            chapters,
            startTime,
            cachedSession,
            localTimestampAtStart,
            playbackGeneration,
            forceStartTime,
            pendingSession,
          );
          // Fall through to normal server path if cache was stale/invalid.
          // The cached path never consumed the in-flight POST on this route,
          // so hand its result over instead of opening a second session.
          if (result == 'cache-miss') {
            Map<String, dynamic>? lateSession;
            try {
              lateSession = await pendingSession;
            } catch (_) {}
            result = await _playFromServer(
              api,
              itemId,
              title,
              author,
              coverUrl,
              totalDuration,
              chapters,
              startTime,
              forceStartTime: forceStartTime,
              preFetchedSession: lateSession,
              generation: playbackGeneration,
            );
          }
        }
      } else {
        // No cache - stream from server
        result = await _playFromServer(
          api,
          itemId,
          title,
          author,
          coverUrl,
          totalDuration,
          chapters,
          startTime,
          forceStartTime: forceStartTime,
          generation: playbackGeneration,
        );
      }
    }

    // A start that lost leaves the loading flags to the one that won, which
    // may still be loading.
    if (_startSuperseded(playbackGeneration)) return null;

    _isLoadingNewItem = false;
    if (result != null) _endAdvanceBuffering();
    notifyListeners();

    if (result == null && playbackGeneration == _playbackGeneration) {
      _onPlaybackStateChangedCallback?.call(true);
      // Auto-navigate to Absorbing tab when an episode starts playing.
      if (episodeId != null) _onEpisodePlayStartedCallback?.call();
      if (fromUi && episodeId == null) onAppPlay?.call(itemId);
    }
    return result;
  }

  /// Session-start rewind (setting): pull a new session's start position back
  /// by maxRewind so playback opens with a little re-orientation. Scaled by
  /// speed so the perceived amount is the same at 1.5x, and capped at the
  /// chapter start when the barrier is on. Applied to the start position
  /// BEFORE the first seek - it used to run after play() and audibly jumped
  /// 50-90ms into live audio. Callers pass the speed they're about to set.
  Future<double> _sessionStartRewound(
    double startTime, {
    required bool forceStartTime,
    required double speed,
  }) async {
    if (forceStartTime || startTime <= 0) return startTime;
    final rewindSettings = await AutoRewindSettings.load();
    if (!rewindSettings.enabled || !rewindSettings.sessionStartRewind) {
      return startTime;
    }
    final rewindSeconds = rewindSettings.maxRewind;
    if (rewindSeconds <= 0.5) return startTime;
    var newPos = startTime - (rewindSeconds * speed);
    if (newPos < 0) newPos = 0;
    if (rewindSettings.chapterBarrier && _chapters.isNotEmpty) {
      for (final ch in _chapters) {
        final start = (ch['start'] as num?)?.toDouble() ?? 0;
        final end = (ch['end'] as num?)?.toDouble() ?? 0;
        if (startTime >= start && startTime < end) {
          if (newPos < start) newPos = start;
          break;
        }
      }
    }
    final actualDelta = startTime - newPos;
    if (actualDelta <= 0) return startTime;
    final detail = speed == 1.0
        ? '${rewindSeconds.toStringAsFixed(1)}s (session start)'
        : '${rewindSeconds.toStringAsFixed(1)}s (${actualDelta.toStringAsFixed(1)}s at ${speed.toStringAsFixed(2)}x, session start)';
    _logEvent(PlaybackEventType.autoRewind, detail: detail);
    debugPrint(
      '[Player] Session-start rewind ${rewindSeconds.toStringAsFixed(1)}s '
      '(${actualDelta.toStringAsFixed(1)}s at ${speed.toStringAsFixed(2)}x) '
      '-> starting at ${newPos.toStringAsFixed(1)}s',
    );
    return newPos;
  }

  // A finished download waiting for a quiet moment to take over from the
  // stream: the progress key of the item, and the start it belongs to.
  String? _pendingLocalSwapKey;
  int _pendingLocalSwapGeneration = -1;

  /// A download finished for [itemId]. Moving a playing stream onto the files
  /// means reloading the source, a short gap in the middle of a sentence, and
  /// nothing is wrong with the stream, so while audio is running the move
  /// waits for the next pause or seek, where a reload cannot be heard. Paused,
  /// it happens now. A stream that errors before then restarts through
  /// playItem, which picks the files up by itself.
  Future<bool> switchToLocal(String itemId) async {
    final currentItemId = _currentItemId;
    if (currentItemId == null ||
        playbackDownloadKey(currentItemId, _currentEpisodeId) != itemId) {
      return false;
    }
    if (!_downloadService.isDownloaded(itemId)) return false;
    if (_player == null || _localSessionMode) return false;

    _pendingLocalSwapKey = itemId;
    _pendingLocalSwapGeneration = _playbackGeneration;
    if (_player!.playing) {
      debugPrint(
        '[Player] Download finished - holding the move to local files for the next pause or seek',
      );
      return true;
    }
    return _applyPendingLocalSwap(resumeAfter: false);
  }

  /// Move the source onto the finished download. Called only where playback
  /// is already interrupted (paused, mid-seek, or a source that has to be
  /// rebuilt anyway), so the reload rides inside that interruption. The files
  /// load straight at [seekToSeconds] (or the current position) - no start at
  /// zero followed by a seek. Returns true when the move happened and already
  /// landed there; the caller must then skip its own seek.
  Future<bool> _applyPendingLocalSwap({
    double? seekToSeconds,
    bool resumeAfter = false,
  }) async {
    final key = _pendingLocalSwapKey;
    if (key == null || _player == null) return false;
    final currentItemId = _currentItemId;
    if (_pendingLocalSwapGeneration != _playbackGeneration ||
        currentItemId == null ||
        playbackDownloadKey(currentItemId, _currentEpisodeId) != key ||
        _localSessionMode ||
        !_downloadService.isDownloaded(key)) {
      _pendingLocalSwapKey = null;
      return false;
    }
    // While casting, the local player isn't the real output - keep the move
    // for when local playback matters again.
    if (ChromecastService().isCasting) return false;
    final localPaths = _downloadService.getLocalPaths(key);
    if (localPaths == null || localPaths.isEmpty) {
      _pendingLocalSwapKey = null;
      return false;
    }
    _pendingLocalSwapKey = null; // one-shot, success or not

    final currentSpeed = _player!.speed;
    // Audio that ran up to this moment is still owed to the stream session.
    // Paused, the pause sync already reported the tail and the span since is
    // idle time, not listening.
    final finalStreamingSeconds = !resumeAfter
        ? 0
        : DateTime.now().difference(_lastServerSync).inSeconds.clamp(0, 300);
    final target = (seekToSeconds ?? position.inMilliseconds / 1000.0)
        .clamp(0.0, double.infinity)
        .toDouble();
    debugPrint(
      '[Player] Moving to local files at ${target.toStringAsFixed(1)}s (resume=$resumeAfter)',
    );

    // Track durations from the download's stored session, for multi-file
    // seeking. Same book, so the offsets match the stream's; without them
    // the stream's own are kept when they fit the files.
    final cachedJson = _downloadService.getCachedSessionData(key);
    List<dynamic>? audioTracks;
    if (cachedJson != null) {
      try {
        final session = jsonDecode(cachedJson) as Map<String, dynamic>;
        audioTracks = session['audioTracks'] as List<dynamic>?;
      } catch (_) {}
    }
    if (audioTracks != null && audioTracks.length == localPaths.length) {
      _buildTrackOffsets(audioTracks);
    } else if (_trackStartOffsets.length - 1 != localPaths.length) {
      _trackStartOffsets = [0.0];
    }

    var oldSourceGone = false;
    try {
      var idx = 0;
      for (int i = 0; i < _trackStartOffsets.length - 1; i++) {
        if (target < _trackStartOffsets[i + 1] ||
            i == _trackStartOffsets.length - 2) {
          idx = i;
          break;
        }
      }
      final trackStart = idx < _trackStartOffsets.length ? _trackStartOffsets[idx] : 0.0;
      final localPos = Duration(
        milliseconds: ((target - trackStart) * 1000).round(),
      );
      // Stamp the seek target so position readers (UI, progress save) hold at
      // the target while the files load instead of flashing 0.
      _lastSeekTargetSeconds = target;
      _lastSeekTime = DateTime.now();

      final trackSources = localPaths.map((p) => localAudioSource(p)).toList();
      final source = ConcatenatingAudioSource(children: trackSources);
      _pendingSessionUpgrade = null; // going local, its URLs no longer matter
      _resetPreBufferState();
      // Update index BEFORE loading so positionStream events use the right offset
      _currentTrackIndex = idx;
      oldSourceGone = true;
      await _player!.setAudioSource(
        source,
        initialIndex: idx,
        initialPosition: localPos,
        itemId: _currentItemId,
      );
      _activeConcatSource = source;
      _currentBookTrackCount = trackSources.length;
      _subscribeTrackIndex();
      await _player!.setSpeed(currentSpeed);
      if (resumeAfter) _player!.play();

      await _switchHotSwapReportingToLocal(
        position: Duration(milliseconds: (target * 1000).round()),
        streamingSeconds: finalStreamingSeconds,
      );

      _logEvent(PlaybackEventType.play, detail: 'Switched to local playback');
      debugPrint('[Player] Now playing from local files');
      notifyListeners();
      return true;
    } catch (e) {
      debugPrint('[Player] Move to local files failed: $e');
      if (!oldSourceGone) return false;
      // The stream's source went with the failed load, so there is nothing
      // left for the caller to seek. When audio should be running, restart
      // through the normal path at the spot this was heading for; it falls
      // back to the server if the files really are unreadable. Paused, the
      // next play re-initialises the idle player.
      _lastKnownPositionSec = target;
      if (resumeAfter) unawaited(_attemptStreamRetry(e));
      return true;
    }
  }

  static Future<bool?> _setAudioSessionActive(bool active) async {
    if (AppPlatform.lacksPhonePlugins) return null;
    return (await AudioSession.instance).setActive(active);
  }

  Future<void> _switchHotSwapReportingToLocal({
    required Duration position,
    required int streamingSeconds,
  }) async {
    if (_localSessionMode || _currentItemId == null) return;

    final api = _api;
    final streamingSessionId = _playbackSessionId;
    final progressKey = playbackDownloadKey(_currentItemId!, _currentEpisodeId);
    final currentTime = position.inMilliseconds / 1000.0;

    try {
      await LocalSessionService().beginSession(
        progressKey: progressKey,
        libraryItemId: _currentItemId!,
        episodeId: _currentEpisodeId,
        mediaType: _currentEpisodeId != null ? 'podcast' : 'book',
        duration: _totalDuration,
        startTime: currentTime,
        displayTitle: _currentTitle,
        displayAuthor: _currentAuthor,
      );
    } catch (e) {
      debugPrint('[Player] Failed to start LOCAL reporting after hot-swap: $e');
      return;
    }

    _logEvent(PlaybackEventType.sessionEnd, detail: 'stream hot-swap');
    _localSessionMode = true;
    _playbackSessionId = null;
    _activeStreamUrls = const [];
    _activeStreamHeaders = const {};
    _lastServerSync = DateTime.now();
    _lastAccrual = _lastServerSync;
    _lastAccrualPos = null;
    _logEvent(PlaybackEventType.sessionStart, detail: 'local hot-swap');

    if (api == null || streamingSessionId == null) return;

    try {
      final pendingBefore = await _progressSync.getStreamingPendingTime(
        progressKey,
      );
      final synced = await api.syncPlaybackSession(
        streamingSessionId,
        currentTime: currentTime,
        duration: _totalDuration,
        timeListened: streamingSeconds,
      );
      if (synced) {
        if (streamingSeconds > 0) {
          unawaited(
            _progressSync.addTimeSaved(streamingSeconds, _player?.speed ?? 1.0),
          );
          if (!AppPlatform.lacksPhonePlugins) {
            unawaited(
              HomeWidgetService().addLocalListeningSeconds(streamingSeconds),
            );
          }
        }
        if (pendingBefore > 0) {
          unawaited(
            _progressSync.reduceStreamingPendingTime(
              progressKey,
              pendingBefore,
            ),
          );
        }
      }
    } catch (e) {
      debugPrint('[Player] Failed to finalize streaming hot-swap session: $e');
    }

    try {
      await api.closePlaybackSession(streamingSessionId);
    } catch (_) {}
  }

  Future<String?> _playFromLocal(
    String itemId,
    String title,
    String author,
    String? coverUrl,
    double totalDuration,
    List<dynamic> chapters,
    double startTime, [
    bool forceStartTime = false,
    bool loadOnly = false,
    int? generation,
    // A narration streamed out of its EPUB on the server: its files and
    // timeline stand in for a download's.
    NarrationStreamSource? stream,
  ]) async {
    final gen = generation ?? _playbackGeneration;
    if (_startSuperseded(gen)) return null;
    // This start's ids, read before anything awaits. The shared fields belong
    // to a newer start as soon as one begins.
    final rawItemId = _currentItemId!;
    final episodeId = _currentEpisodeId;
    debugPrint(stream != null
        ? '[Player] Streaming the narration out of the EPUB: $title'
        : '[Player] Playing from local files: $title');
    // Alpha [PodDur]: trace podcast-episode duration loading. Symptom:
    // Android Auto progress bar missing for ~60s on cold-start podcast play
    // because the first MediaItem push carries dur=0. We want to know what
    // value arrived at this function, and what's available from nearby state.
    debugPrint(
      '[PodDur] _playFromLocal entry: itemId=$itemId ep=$_currentEpisodeId totalDurationArg=${totalDuration.toStringAsFixed(1)}s _totalDuration=${_totalDuration.toStringAsFixed(1)}s chapters=${chapters.length}',
    );
    _isOfflineMode = false; // We still sync to server if possible
    _playbackSessionId = null;

    // Check if manual offline mode is on
    final prefs = await SharedPreferences.getInstance();
    final manualOffline = prefs.getBool('manual_offline_mode') ?? false;
    debugPrint('[Player] manualOffline=$manualOffline, api=${_api != null}');

    // Downloaded plays report to the server via the client-owned LOCAL session
    // model (GH #276 Local label, GH #280 per-day attribution), NOT a live
    // /play session. Position still syncs through /me/progress; here we only
    // reconcile the start position against the server's saved progress (when
    // online) the way the /play response used to, sourced from GET /me/progress.
    _localSessionMode = true;
    _logEvent(PlaybackEventType.sessionStart, detail: 'local-session');
    // `itemId` here is the progress key (already `id-episodeId` for a podcast),
    // so build the key from the raw parts to avoid double-appending the episode.
    final pKey = episodeId != null ? '$rawItemId-$episodeId' : rawItemId;
    // Only a play from the app screen waits on this, and only briefly: it is
    // the one moment a fresh start can pick up another device's progress
    // before audio. Headphone / widget / Android Auto / cold-start plays of
    // a download need nothing from the network to begin, so they don't ask
    // (GH #321) - unless this phone has no position for it at all, where
    // starting from zero would be the wrong guess and there is nothing to
    // preserve. Whatever position we start with, we keep - no seeking after.
    if (forceStartTime) {
      debugPrint(
        '[Player] Forced start time: ${startTime}s — skipping server/local position comparison',
      );
    } else if (_downloadService.isFromOtherAccount(rawItemId)) {
      // The server signed in now doesn't hold this book's place, and could
      // hold a different book's under the same id.
      debugPrint('[Player] Another account\'s download - playing its spot on this phone, ${startTime.toStringAsFixed(1)}s');
    } else if (!_playFromUi && startTime > 0) {
      debugPrint(
        '[Player] Skipping progress reconcile - not started from the app screen, playing local position ${startTime.toStringAsFixed(1)}s now',
      );
    } else if (_api != null && !manualOffline && !_knownOffline) {
      try {
        final serverProgress = await _api!
            .getItemProgress(pKey)
            .timeout(_serverPositionCheckCap, onTimeout: () => null);
        final serverPos =
            (serverProgress?['currentTime'] as num?)?.toDouble() ?? 0;
        final serverLastUpdate =
            (serverProgress?['lastUpdate'] as num?)?.toInt() ?? 0;
        final localTs = await _progressSync.getSavedTimestamp(pKey);
        if (serverPos > startTime + 1.0) {
          debugPrint(
            '[Player] Server position is ahead: server=${serverPos}s vs local=${startTime}s — using server',
          );
          startTime = serverPos;
          await _progressSync.saveLocal(
            itemId: itemId,
            currentTime: serverPos,
            duration: totalDuration,
            speed: 1.0,
          );
        } else if (startTime > 0) {
          // Local is ahead — verify via timestamp that this isn't stale data.
          // Skip the override if we have a pending local sync: local is the
          // truth, we just haven't shipped it to the server yet.
          bool useServer = false;
          final hasPending = await _progressSync.hasPendingSync(pKey);
          final gap = startTime - serverPos;
          if (localTs > 0 &&
              !hasPending &&
              gap <= SyncLogic.localAheadSafetySeconds &&
              serverLastUpdate > localTs) {
            debugPrint(
              '[Player] Local position is ahead but stale: local=${startTime}s (ts=$localTs) vs server=${serverPos}s (ts=$serverLastUpdate) — using server',
            );
            startTime = serverPos;
            useServer = true;
          }
          if (!useServer) {
            if (hasPending) {
              debugPrint(
                '[Player] Local position is ahead: local=${startTime}s vs server=${serverPos}s — keeping local (pending sync)',
              );
            } else if (gap > SyncLogic.localAheadSafetySeconds) {
              debugPrint(
                '[Player] Local position is ahead: local=${startTime}s vs server=${serverPos}s — keeping local (gap ${gap.toStringAsFixed(1)}s exceeds safety threshold)',
              );
            } else {
              debugPrint(
                '[Player] Local position is ahead: local=${startTime}s vs server=${serverPos}s — keeping local',
              );
            }
          }
        } else if (serverPos > 0) {
          debugPrint('[Player] No local position, using server: ${serverPos}s');
          startTime = serverPos;
        }
      } catch (e) {
        debugPrint('[Player] Local-play progress reconcile failed: $e');
      }
    } else {
      debugPrint(
        '[Player] Skipping progress reconcile — manual offline or no API',
      );
    }

    if (_startSuperseded(gen)) {
      return _abandonStart(null, null, 'local, after the position check');
    }
    final localPaths = stream?.urls ?? _downloadService.getLocalPaths(itemId);
    if (localPaths == null || localPaths.isEmpty) {
      debugPrint('[Player] No local files found');
      _clearState();
      return 'Downloaded files not found - try re-downloading';
    }

    // Get cached session data for track durations (and chapters if needed)
    final cachedJson = stream != null ? jsonEncode(stream.session) : _downloadService.getCachedSessionData(itemId);
    List<dynamic>? audioTracks;
    if (cachedJson != null) {
      try {
        final session = jsonDecode(cachedJson) as Map<String, dynamic>;
        audioTracks = session['audioTracks'] as List<dynamic>?;
        _captureNowPlayingCredits(session);
        // Fall back to the cached session duration when the caller didn't have
        // one (e.g. podcast cold-start from Android Auto pushes dur=0). Replaces
        // the old /play-response duration fallback now that local plays skip it.
        if (totalDuration <= 0) {
          final cachedDur = (session['duration'] as num?)?.toDouble();
          if (cachedDur != null && cachedDur > 0) {
            totalDuration = cachedDur;
            _totalDuration = cachedDur;
          }
        }
        // Pick up chapters from cached session when not already loaded
        if (chapters.isEmpty) {
          final cachedChapters = session['chapters'] as List<dynamic>? ?? [];
          if (cachedChapters.isNotEmpty) {
            chapters = cachedChapters;
            _chapters = cachedChapters;
            _handler?.updateChaptersQueue(cachedChapters);
            debugPrint(
              '[Player] Loaded ${cachedChapters.length} chapters from cached session',
            );
          }
        }
      } catch (_) {}
    }

    try {
      if (_startSuperseded(gen)) {
        return _abandonStart(null, null, 'local, before building the source');
      }
      _currentTrackIndex = 0;

      // Build multi-file track offsets for absolute position tracking
      if (audioTracks != null) {
        _buildTrackOffsets(audioTracks);
      } else {
        _trackStartOffsets = [0.0]; // single file fallback
      }

      final trackSources = localPaths.map((p) => localAudioSource(p)).toList();
      final source = ConcatenatingAudioSource(children: trackSources);

      await _configureAudioSession();
      try {
        final activated = await _setAudioSessionActive(true);
        debugPrint('[Player] Pre-source setActive(true)=$activated (local)');
      } catch (e) {
        debugPrint('[Player] Pre-source setActive failed (local): $e');
      }
      if (_startSuperseded(gen)) {
        return _abandonStart(null, null, 'local, before loading the source');
      }
      _resetPreBufferState();
      final decoded = await _player!.setAudioSource(
        source,
        itemId: rawItemId,
      );
      if (_startSuperseded(gen)) {
        return _abandonStart(null, null, 'local, after loading the source');
      }
      _activeConcatSource = source;
      _currentBookTrackCount = trackSources.length;

      // Detect an incomplete/corrupt download: the audio on disk decodes to
      // materially less than the book's real length. If we trusted the
      // metadata duration we'd let the user seek past the end of the file,
      // clamp them to ~the file's end on resume, and save that over their real
      // progress (GH #278). Flag it so seeks clamp and saves are protected.
      //
      // Only valid for single-file books. On a multi-file
      // ConcatenatingAudioSource, setAudioSource returns just the first track's
      // duration (the current ExoPlayer window), not the whole book — so this
      // would flag every complete multi-file download as truncated and pin
      // playback to the first track, breaking seek and resume. The single-point
      // _shortLocalDurationSec clamp only models one truncated file anyway.
      final decodedSec = (decoded?.inMilliseconds ?? 0) / 1000.0;
      if (trackSources.length == 1 &&
          totalDuration > 0 &&
          decodedSec > 0 &&
          decodedSec < totalDuration - _kLocalTruncationMarginSec) {
        _shortLocalDurationSec = decodedSec;
        debugPrint(
          '[Player] Local audio decodes to ${decodedSec.toStringAsFixed(1)}s '
          'but book is ${totalDuration.toStringAsFixed(1)}s — download looks '
          'incomplete; clamping seeks and protecting saved progress (GH #278)',
        );
      }

      // If the saved position is at (or past) the end, restart from the beginning
      if (totalDuration > 0 && startTime >= totalDuration - 1.0) startTime = 0;
      final speedKey = _currentItemId ?? itemId;
      final bookSpeed = await PlayerSettings.getBookSpeed(speedKey);
      final speed = bookSpeed ??
          await PlayerSettings.defaultSpeedFor(libraryId: _currentLibraryId);
      startTime = await _sessionStartRewound(
        startTime,
        forceStartTime: forceStartTime,
        speed: speed,
      );
      if (startTime > 0) {
        await _seekAbsolute(startTime);
      }
      clearSeekTarget(); // Seek done; let position events flow immediately

      _subscribeTrackIndex();
      final initChapter = _initChapterInfo(startTime);
      // Speed must be applied before _pushMediaItem: the pushed duration is
      // speed-adjusted at push time, and nothing re-pushes it on load - so
      // pushing at the default 1.0x left the notification/AA/widget bar
      // lagging (the chapter "ended" at 1/speed) until a foreground re-push.
      await _player!.setSpeed(speed);
      _pushMediaItem(
        itemId,
        title,
        author,
        coverUrl,
        totalDuration,
        chapter: initChapter,
      );
      await _primeNowPlaying(
        title: title,
        artist: author,
        duration: totalDuration,
        elapsed: startTime,
        chapter: initChapter,
      );
      await EqualizerService().switchItem(speedKey);
      if (loadOnly) {
        // Loaded and idle at the resume position: the lock screen shows the
        // book paused, a headset press has a live target, and the transcript
        // can build its runway - but nothing plays and no session exists
        // until the user presses play, which creates the session then.
        debugPrint('[Player] Loaded paused (no session) at '
            '${startTime.toStringAsFixed(0)}s');
        _pendingLoadOnlySession = (
          progressKey: pKey,
          itemId: _currentItemId!,
          episodeId: _currentEpisodeId,
          duration: totalDuration,
          title: title,
          author: author,
          streamed: stream != null,
        );
        _handler?.refreshPlaybackState();
        notifyListeners();
        return null;
      }
      debugPrint('[Player] Starting local playback at ${speed}x');
      _handler?.refreshPlaybackState();
      await Future.delayed(const Duration(milliseconds: 200));
      try {
        await _setAudioSessionActive(true);
      } catch (_) {}
      if (_startSuperseded(gen)) {
        return _abandonStart(null, null, 'local, before play');
      }
      _player!.play();
      _scheduleAudioDiagnostics('local');
      notifyListeners();
      _setupSync();
      await LocalSessionService().beginSession(
        progressKey: pKey,
        libraryItemId: rawItemId,
        episodeId: episodeId,
        mediaType: episodeId != null ? 'podcast' : 'book',
        duration: totalDuration,
        startTime: startTime,
        displayTitle: title,
        displayAuthor: author,
        streamed: stream != null,
      );
      Future.delayed(const Duration(milliseconds: 500), () {
        _handler?.refreshPlaybackState();
      });
      // Fresh session — reset auto sleep dismiss and check
      final sleepTimer = SleepTimerService();
      sleepTimer.resetDismiss();
      sleepTimer.checkAutoSleep();

      return null;
    } catch (e, stack) {
      debugPrint('[Player] Local play error: $e\n$stack');

      if (_startSuperseded(gen)) {
        return _abandonStart(null, null, 'local, load interrupted');
      }

      // A downloaded original can still be unreadable by the device (for
      // example a very large MP4/M4B that ExoPlayer cannot parse). When the
      // server is reachable, retry once through ABS transcoding instead of
      // leaving the user stuck with an unusable local file.
      if (PlaybackErrorPolicy.shouldRetryWithTranscode(e) &&
          _api != null &&
          !manualOffline &&
          !_knownOffline &&
          _currentItemId != null) {
        debugPrint(
          '[Player] Local source failed - retrying with server transcoding',
        );
        _shortLocalDurationSec = null;
        _localSessionMode = false;
        final fallbackResult = await _playFromServer(
          _api!,
          rawItemId,
          title,
          author,
          coverUrl,
          totalDuration,
          chapters,
          startTime,
          forceStartTime: forceStartTime,
          forceTranscode: true,
          generation: gen,
        );
        if (fallbackResult == null) {
          // Streaming uses data the download was meant to save, so say so.
          final l = _l10n();
          showNavigatorOverlayToast(
            rootNavigatorKey.currentState,
            l?.playerDownloadStreamingInstead ??
                "This download couldn't be played, so it's streaming from the server. Downloading it again may fix it.",
            icon: Icons.cloud_download_outlined,
          );
          return null;
        }
        debugPrint(
          '[Player] Transcoded fallback after local failure did not start: $fallbackResult',
        );
        return fallbackResult;
      }

      _clearState();
      return 'Playback failed: ${e.toString().split('\n').first}';
    }
  }

  /// Play from cached session metadata. Starts playback instantly without
  /// waiting for a server round-trip. Fires _refreshServerSession() in the
  /// background to get a fresh session ID and cross-client progress check.
  Future<String?> _playFromSessionCache(
    ApiService api,
    String itemId,
    String title,
    String author,
    String? coverUrl,
    double totalDuration,
    List<dynamic> chapters,
    double startTime,
    Map<String, dynamic> cached,
    int localTimestampAtStart,
    int playbackGeneration, [
    bool forceStartTime = false,
    Future<Map<String, dynamic>?>? pendingSession,
  ]) async {
    // The session request still in flight is handed to nobody on this route;
    // close it when it lands so the server is not left with a stray one.
    void dropPendingSession() {
      pendingSession?.then((s) {
        final id = s?['id'] as String?;
        if (id != null) unawaited(api.closePlaybackSession(id));
      }).catchError((_) {});
    }

    if (_startSuperseded(playbackGeneration)) {
      dropPendingSession();
      return _abandonStart(null, null, 'before the cached start');
    }
    debugPrint('[Player] Playing from session cache: $title');
    final episodeIdAtStart = _currentEpisodeId;
    _isOfflineMode = false;
    _playbackSessionId =
        null; // No server session yet; _refreshServerSession will set it

    final audioTracks = cached['audioTracks'] as List<dynamic>?;
    if (audioTracks == null || audioTracks.isEmpty) {
      debugPrint('[Player] Cached session has no audio tracks - falling back');
      return 'cache-miss';
    }

    // Pick up cached chapters if the caller didn't provide any
    if (chapters.isEmpty) {
      final cachedChapters = cached['chapters'] as List<dynamic>? ?? [];
      if (cachedChapters.isNotEmpty) {
        chapters = cachedChapters;
        _chapters = cachedChapters;
        _handler?.updateChaptersQueue(cachedChapters);
      }
    }

    // Use cached duration if caller didn't have one
    if (totalDuration <= 0) {
      final cachedDur = (cached['totalDuration'] as num?)?.toDouble() ?? 0;
      if (cachedDur > 0) {
        totalDuration = cachedDur;
        _totalDuration = cachedDur;
      }
    }

    try {
      _currentTrackIndex = 0;
      final audioHeaders = api.playbackSessionHeaders;
      _buildTrackOffsets(audioTracks);
      _captureStreamUrls(audioTracks, api);
      AudioSource source;
      final trackSources = <AudioSource>[];
      for (final t in audioTracks) {
        final track = t as Map<String, dynamic>;
        final contentUrl = track['contentUrl'] as String? ?? '';
        final fullUrl = api.buildTrackUrl(contentUrl);
        trackSources.add(
          AudioSource.uri(
            Uri.parse(fullUrl),
            headers: audioHeaders,
            options: mp3ExtractorOptions(),
          ),
        );
      }
      source = ConcatenatingAudioSource(children: trackSources);

      await _configureAudioSession();
      try {
        final activated = await _setAudioSessionActive(true);
        debugPrint(
          '[Player] Pre-source setActive(true)=$activated (cached-session)',
        );
      } catch (e) {
        debugPrint('[Player] Pre-source setActive failed (cached-session): $e');
      }
      if (_startSuperseded(playbackGeneration)) {
        dropPendingSession();
        return _abandonStart(null, null, 'cached start, before loading the source');
      }
      _resetPreBufferState();
      await _player!.setAudioSource(source, itemId: itemId);
      if (_startSuperseded(playbackGeneration)) {
        dropPendingSession();
        return _abandonStart(null, null, 'cached start, after loading the source');
      }
      _activeConcatSource = source as ConcatenatingAudioSource;
      _currentBookTrackCount = trackSources.length;

      if (totalDuration > 0 && startTime >= totalDuration - 1.0) startTime = 0;
      final bookSpeed = await PlayerSettings.getBookSpeed(itemId);
      final speed = bookSpeed ??
          await PlayerSettings.defaultSpeedFor(libraryId: _currentLibraryId);
      startTime = await _sessionStartRewound(
        startTime,
        forceStartTime: forceStartTime,
        speed: speed,
      );
      if (startTime > 0) {
        await _seekForStart(startTime, playbackGeneration);
      }
      clearSeekTarget();

      _subscribeTrackIndex();
      final initChapter = _initChapterInfo(startTime);
      // Speed before _pushMediaItem - the pushed duration is speed-adjusted.
      await _player!.setSpeed(speed);
      _pushMediaItem(
        itemId,
        title,
        author,
        coverUrl,
        totalDuration,
        chapter: initChapter,
      );
      await _primeNowPlaying(
        title: title,
        artist: author,
        duration: totalDuration,
        elapsed: startTime,
        chapter: initChapter,
      );
      await EqualizerService().switchItem(itemId);
      debugPrint('[Player] Starting cached session playback at ${speed}x');
      _handler?.refreshPlaybackState();
      await Future.delayed(const Duration(milliseconds: 200));
      try {
        await _setAudioSessionActive(true);
      } catch (_) {}
      if (_startSuperseded(playbackGeneration)) {
        dropPendingSession();
        return _abandonStart(null, null, 'cached start, before play');
      }
      _cachedStartReconcileGeneration = playbackGeneration;
      _player!.play();
      _scheduleAudioDiagnostics('cached-session');
      notifyListeners();
      _setupSync();
      Future.delayed(const Duration(milliseconds: 500), () {
        _handler?.refreshPlaybackState();
      });
      final sleepTimer = SleepTimerService();
      sleepTimer.resetDismiss();
      sleepTimer.checkAutoSleep();
      // Refresh server session in background - gets fresh session ID and
      // handles cross-client progress sync without blocking playback start
      final progressKey = episodeIdAtStart != null
          ? '$itemId-$episodeIdAtStart'
          : itemId;
      _refreshServerSession(
        api,
        itemId,
        episodeIdAtStart: episodeIdAtStart,
        progressKey: progressKey,
        localTimestampAtStart: localTimestampAtStart,
        localTimeAtStart: startTime,
        playbackGeneration: playbackGeneration,
        pendingSession: pendingSession,
      );
      return null;
    } catch (e, stack) {
      debugPrint('[Player] Cached session play error: $e\n$stack');
      if (_cachedStartReconcileGeneration == playbackGeneration) {
        _cachedStartReconcileGeneration = null;
      }
      // Interrupted by a newer start, not a bad cache: leave the cache alone
      // and do not fall through to a full server start over the winner.
      if (_startSuperseded(playbackGeneration)) {
        dropPendingSession();
        return _abandonStart(null, null, 'cached start, load interrupted');
      }
      // Cache was stale or invalid - clear it and signal fallback
      SessionCache.clear(itemId: itemId, episodeId: episodeIdAtStart);
      return 'cache-miss';
    }
  }

  /// Re-create the server playback session in the background after starting
  /// playback from cache. Gets a fresh session ID so progress syncing works,
  /// and handles cross-client progress (seek to server position if ahead).
  void _refreshServerSession(
    ApiService api,
    String itemId, {
    required String? episodeIdAtStart,
    required String progressKey,
    required int localTimestampAtStart,
    required double localTimeAtStart,
    required int playbackGeneration,
    Future<Map<String, dynamic>?>? pendingSession,
  }) async {
    try {
      if (_isOfflineMode) return;
      final progressRequest = api.getItemProgress(progressKey);
      // The race in playItem may already have a POST in flight - consume it
      // rather than opening a second session.
      final sessionData = await (pendingSession ??
          (episodeIdAtStart != null
              ? api.startEpisodePlaybackSession(itemId, episodeIdAtStart)
              : api.startPlaybackSession(itemId)));
      if (sessionData == null) {
        debugPrint('[Player] Background session refresh returned null');
        return;
      }
      final serverProgress = await progressRequest;
      if (_playbackGeneration != playbackGeneration ||
          _currentItemId != itemId ||
          _currentEpisodeId != episodeIdAtStart) {
        debugPrint(
          '[Player] Ignoring stale background session refresh for $progressKey',
        );
        return;
      }
      _playbackSessionId = sessionData['id'] as String?;
      _lastServerSync = DateTime.now();
      debugPrint('[Player] Background session refreshed: $_playbackSessionId');
      _captureNowPlayingCredits(sessionData);
      _logEvent(PlaybackEventType.sessionStart, detail: 'refresh');

      // Update cached session with fresh track data in case it changed
      final audioTracks = sessionData['audioTracks'] as List<dynamic>?;
      final sessionChapters = sessionData['chapters'] as List<dynamic>? ?? [];
      final sessionDur = (sessionData['duration'] as num?)?.toDouble() ?? 0;
      if (audioTracks != null && audioTracks.isNotEmpty) {
        SessionCache.save(
          itemId: itemId,
          episodeId: _currentEpisodeId,
          audioTracks: audioTracks,
          chapters: sessionChapters.isNotEmpty ? sessionChapters : _chapters,
          totalDuration: sessionDur > 0 ? sessionDur : _totalDuration,
        );
        // The playing source still carries the cached tokened URLs; hold this
        // session so the next pause or seek can swap to its tokenless URLs.
        _stashSessionUpgrade(sessionData);
      }

      // Audio is already running from the cached start; the server's saved
      // position is only logged here, never seeked to - a jump a few seconds
      // into playback is worse than the stale spot. An app-screen play had
      // its chance to adopt it in the pre-start race window.
      final serverPos =
          (serverProgress?['currentTime'] as num?)?.toDouble() ??
          (sessionData['currentTime'] as num?)?.toDouble() ??
          0;
      final serverTs =
          (serverProgress?['lastUpdate'] as num?)?.toInt() ??
          (localTimestampAtStart == 0
              ? (sessionData['updatedAt'] as num?)?.toInt() ?? 0
              : 0);
      final localPos = position.inMilliseconds / 1000.0;
      if (SyncLogic.shouldAdoptServerAtCachedStart(
        serverTimestamp: serverTs,
        serverTime: serverPos,
        localTimestampAtStart: localTimestampAtStart,
        localTimeAtStart: localTimeAtStart,
        currentPlaybackTime: localPos,
      )) {
        debugPrint(
          '[Player] Server is ahead on cache-start: server=${serverPos}s vs local=${localPos}s - not seeking (audio already running)',
        );
      }
    } catch (e) {
      debugPrint('[Player] Background session refresh failed: $e');
    } finally {
      if (_cachedStartReconcileGeneration == playbackGeneration) {
        _cachedStartReconcileGeneration = null;
      }
    }
  }

  Future<String?> _playFromServer(
    ApiService api,
    String itemId,
    String title,
    String author,
    String? coverUrl,
    double totalDuration,
    List<dynamic> chapters,
    double startTime, {
    bool forceStartTime = false,
    bool forceTranscode = false,
    Map<String, dynamic>? preFetchedSession,
    int? generation,
  }) async {
    final gen = generation ?? _playbackGeneration;
    // A session fetched ahead of time is this start's to close if it lost.
    if (_startSuperseded(gen)) {
      return _abandonStart(api, preFetchedSession?['id'] as String?, 'before streaming');
    }
    debugPrint('[Player] Streaming from server: $title');
    _isOfflineMode = false;
    _localSessionMode = false;
    // Still this start's episode: nothing has awaited since the check above.
    // Reading the shared field later asked the server for whatever a newer
    // start had set, which is how one episode got two sessions.
    final episodeId = _currentEpisodeId;

    // Use episode endpoint if this is a podcast episode
    final sessionData = preFetchedSession ??
        (episodeId != null
            ? await api.startEpisodePlaybackSession(
                itemId,
                episodeId,
                forceTranscode: forceTranscode,
              )
            : await api.startPlaybackSession(
                itemId,
                forceTranscode: forceTranscode,
              ));
    String? ownSessionId = sessionData?['id'] as String?;
    if (_startSuperseded(gen)) {
      return _abandonStart(api, ownSessionId, 'after the session request');
    }
    if (sessionData == null) {
      debugPrint('[Player] Failed to start playback session');
      _clearState();
      return 'Could not connect to server';
    }

    _playbackSessionId = ownSessionId;
    _captureNowPlayingCredits(sessionData);
    // Sessions know their library; adopt it when the caller couldn't provide
    // one so per-library skip amounts work for lean/merged shelf items.
    final sessionLibId = sessionData['libraryId'] as String?;
    if ((_currentLibraryId == null || _currentLibraryId!.isEmpty) &&
        sessionLibId != null &&
        sessionLibId.isNotEmpty) {
      debugPrint(
        '[SkipDebug] libraryId adopted from play session: $sessionLibId',
      );
      _currentLibraryId = sessionLibId;
      _syncNotifSkipCache();
    }
    _lastServerSync = DateTime.now();
    _logEvent(PlaybackEventType.sessionStart, detail: 'stream');
    var audioTracks = sessionData['audioTracks'] as List<dynamic>?;
    var sessionPlayMethod = (sessionData['playMethod'] as num?)?.toInt();
    if (audioTracks == null || audioTracks.isEmpty) {
      _clearState();
      return 'No audio files found - this item may be missing on the server';
    }

    // Detect Dolby Atmos / EAC-3 / AC-3 tracks. Samsung has a hardware Dolby
    // decoder and iOS AVPlayer handles EAC3 natively, so only force transcode
    // on other Android devices where the software codec often fails or outputs silence.
    if (!forceTranscode &&
        AppPlatform.isAndroid &&
        !ApiService.deviceManufacturer.toLowerCase().contains('samsung')) {
      final needsTranscode = audioTracks.any((t) {
        final mime = ((t as Map<String, dynamic>)['mimeType'] as String? ?? '')
            .toLowerCase();
        final codec = (t['codec'] as String? ?? '').toLowerCase();
        return mime.contains('eac3') ||
            mime.contains('ac3') ||
            mime.contains('ac4') ||
            mime.contains('atmos') ||
            codec.contains('eac3') ||
            codec.contains('ac3') ||
            codec.contains('ac4') ||
            codec.contains('atmos');
      });
      if (needsTranscode) {
        debugPrint(
          '[Player] Dolby/EAC3 track detected - restarting with server transcoding',
        );
        if (ownSessionId != null) {
          try {
            await api.closePlaybackSession(ownSessionId);
          } catch (_) {}
        }
        if (_startSuperseded(gen)) {
          return _abandonStart(api, null, 'before the Dolby transcode retry');
        }
        _playbackSessionId = null;
        final retrySession = episodeId != null
            ? await api.startEpisodePlaybackSession(
                itemId,
                episodeId,
                forceTranscode: true,
              )
            : await api.startPlaybackSession(itemId, forceTranscode: true);
        ownSessionId = retrySession?['id'] as String?;
        if (_startSuperseded(gen)) {
          return _abandonStart(api, ownSessionId, 'after the Dolby transcode retry');
        }
        if (retrySession == null) {
          _clearState();
          return 'Could not start transcoded playback';
        }
        _playbackSessionId = ownSessionId;
        audioTracks = retrySession['audioTracks'] as List<dynamic>? ?? [];
        sessionPlayMethod = (retrySession['playMethod'] as num?)?.toInt();
        if (audioTracks.isEmpty) {
          _clearState();
          return 'No audio files in transcoded session';
        }
        final sessionChapters =
            retrySession['chapters'] as List<dynamic>? ?? [];
        if (sessionChapters.isNotEmpty) {
          chapters = sessionChapters;
          _chapters = sessionChapters;
          _handler?.updateChaptersQueue(sessionChapters);
        }
        final sessionDur = (retrySession['duration'] as num?)?.toDouble() ?? 0;
        if (sessionDur > 0) {
          totalDuration = sessionDur;
          _totalDuration = sessionDur;
        }
      }
    }

    // Pick up chapters from session (e.g. podcast episodes with embedded chapters)
    if (chapters.isEmpty) {
      final sessionChapters = sessionData['chapters'] as List<dynamic>? ?? [];
      if (sessionChapters.isNotEmpty) {
        chapters = sessionChapters;
        _chapters = sessionChapters;
        _handler?.updateChaptersQueue(sessionChapters);
        debugPrint(
          '[Player] Loaded ${sessionChapters.length} chapters from session',
        );
      }
    }

    // Update totalDuration from session if it was unknown (e.g. podcast episodes
    // where the embedded recentEpisode didn't include a duration field)
    if (totalDuration <= 0) {
      final sessionDur = (sessionData['duration'] as num?)?.toDouble() ?? 0;
      if (sessionDur > 0) {
        totalDuration = sessionDur;
        _totalDuration = sessionDur;
        debugPrint(
          '[Player] Updated totalDuration from session: ${sessionDur}s',
        );
      }
    }

    // Compare server position vs local.
    // Usually the furthest position wins, but if local is ahead we also
    // check timestamps to catch stale local saves.
    // Skip all of this when startTime was forced (bookmark/chapter jump).
    final serverPos = (sessionData['currentTime'] as num?)?.toDouble() ?? 0;
    final pKey = episodeId != null ? '$itemId-$episodeId' : itemId;
    final localTs = await _progressSync.getSavedTimestamp(pKey);
    if (forceStartTime) {
      debugPrint(
        '[Player] Forced start time: ${startTime}s — skipping server/local position comparison',
      );
    } else if (serverPos > startTime + 1.0) {
      debugPrint(
        '[Player] Server position is ahead: server=${serverPos}s vs local=${startTime}s — using server',
      );
      startTime = serverPos;
    } else if (startTime > 0) {
      // Skip the staleness override if we have a pending local sync: the
      // server's lastUpdate can be newer than the local timestamp for reasons
      // unrelated to listening progress, so trusting it would clobber offline
      // playback we haven't shipped yet. Also skip if local is meaningfully
      // ahead of server - a multi-minute gap is real listening progress, not
      // a save race.
      bool useServer = false;
      final hasPending = await _progressSync.hasPendingSync(pKey);
      final gap = startTime - serverPos;
      if (localTs > 0 &&
          !hasPending &&
          gap <= SyncLogic.localAheadSafetySeconds) {
        try {
          final serverProgress = await api.getItemProgress(pKey);
          final serverLastUpdate =
              (serverProgress?['lastUpdate'] as num?)?.toInt() ?? 0;
          if (serverLastUpdate > localTs) {
            debugPrint(
              '[Player] Local position is ahead but stale: local=${startTime}s (ts=$localTs) vs server=${serverPos}s (ts=$serverLastUpdate) — using server',
            );
            startTime = serverPos;
            useServer = true;
          }
        } catch (_) {}
      }
      if (!useServer) {
        if (hasPending) {
          debugPrint(
            '[Player] Local position is ahead: local=${startTime}s vs server=${serverPos}s — keeping local (pending sync)',
          );
        } else if (gap > SyncLogic.localAheadSafetySeconds) {
          debugPrint(
            '[Player] Local position is ahead: local=${startTime}s vs server=${serverPos}s — keeping local (gap ${gap.toStringAsFixed(1)}s exceeds safety threshold)',
          );
        } else {
          debugPrint(
            '[Player] Local position is ahead: local=${startTime}s vs server=${serverPos}s — keeping local',
          );
        }
      }
    } else if (serverPos > 0) {
      debugPrint('[Player] No local position, using server: ${serverPos}s');
      startTime = serverPos;
    }

    try {
      // Checked before the track offsets are rebuilt: they belong to
      // whichever start is current.
      if (_startSuperseded(gen)) {
        return _abandonStart(api, ownSessionId, 'before building the source');
      }
      _currentTrackIndex = 0;
      final audioHeaders = api.playbackSessionHeaders;

      // Build audio source - one source per track file
      _buildTrackOffsets(audioTracks);
      _captureStreamUrls(
        audioTracks,
        api,
        sessionId: _playbackSessionId,
        playMethod: sessionPlayMethod,
      );
      final trackSources = <AudioSource>[];
      for (final t in audioTracks) {
        final track = t as Map<String, dynamic>;
        final contentUrl = track['contentUrl'] as String? ?? '';
        final fullUrl = api.buildTrackUrl(
          contentUrl,
          sessionId: _playbackSessionId,
          trackIndex: (track['index'] as num?)?.toInt(),
          playMethod: sessionPlayMethod,
        );
        trackSources.add(
          AudioSource.uri(
            Uri.parse(fullUrl),
            headers: audioHeaders,
            options: mp3ExtractorOptions(),
          ),
        );
      }
      final source = ConcatenatingAudioSource(children: trackSources);

      await _configureAudioSession();
      try {
        final activated = await _setAudioSessionActive(true);
        debugPrint('[Player] Pre-source setActive(true)=$activated (stream)');
      } catch (e) {
        debugPrint('[Player] Pre-source setActive failed (stream): $e');
      }
      if (_startSuperseded(gen)) {
        return _abandonStart(api, ownSessionId, 'before loading the source');
      }
      _resetPreBufferState();
      await _player!.setAudioSource(source, itemId: itemId);
      if (_startSuperseded(gen)) {
        return _abandonStart(api, ownSessionId, 'after loading the source');
      }
      _activeConcatSource = source;
      _currentBookTrackCount = trackSources.length;

      // If the saved position is at (or past) the end, restart from the beginning
      if (totalDuration > 0 && startTime >= totalDuration - 1.0) startTime = 0;
      final bookSpeed = await PlayerSettings.getBookSpeed(itemId);
      final speed = bookSpeed ??
          await PlayerSettings.defaultSpeedFor(libraryId: _currentLibraryId);
      startTime = await _sessionStartRewound(
        startTime,
        forceStartTime: forceStartTime,
        speed: speed,
      );
      if (startTime > 0) {
        await _seekForStart(startTime, gen);
      }
      clearSeekTarget(); // Seek done; let position events flow immediately

      _subscribeTrackIndex();
      final initChapter = _initChapterInfo(startTime);
      // Speed before _pushMediaItem - the pushed duration is speed-adjusted.
      await _player!.setSpeed(speed);
      _pushMediaItem(
        itemId,
        title,
        author,
        coverUrl,
        totalDuration,
        chapter: initChapter,
      );
      await _primeNowPlaying(
        title: title,
        artist: author,
        duration: totalDuration,
        elapsed: startTime,
        chapter: initChapter,
      );
      await EqualizerService().switchItem(itemId);
      debugPrint('[Player] Starting stream playback at ${speed}x');
      _handler?.refreshPlaybackState();
      await Future.delayed(const Duration(milliseconds: 200));
      try {
        await _setAudioSessionActive(true);
      } catch (_) {}
      if (_startSuperseded(gen)) {
        return _abandonStart(api, ownSessionId, 'before play');
      }
      _player!.play();
      _scheduleAudioDiagnostics('stream');
      notifyListeners();
      _setupSync();
      Future.delayed(const Duration(milliseconds: 500), () {
        _handler?.refreshPlaybackState();
      });
      // Fresh session — reset auto sleep dismiss and check
      final sleepTimer = SleepTimerService();
      sleepTimer.resetDismiss();
      sleepTimer.checkAutoSleep();
      // Cache session metadata so next play can start instantly
      SessionCache.save(
        itemId: itemId,
        episodeId: episodeId,
        audioTracks: audioTracks,
        chapters: chapters,
        totalDuration: totalDuration,
      );
      return null;
    } catch (e, stack) {
      debugPrint('[Player] Stream error: $e\n$stack');

      // A newer start loading its source is what interrupts this one, so the
      // "error" is expected and the state now belongs to that start.
      if (_startSuperseded(gen)) {
        return _abandonStart(api, ownSessionId, 'load interrupted');
      }

      // Retry source and codec failures through ABS once. A distinct flag from
      // forceStartTime keeps bookmark/chapter seeks eligible for recovery while
      // still preventing a transcode loop.
      if (!forceTranscode && PlaybackErrorPolicy.shouldRetryWithTranscode(e)) {
        debugPrint(
          '[Player] Source or codec error detected - retrying with server transcoding',
        );
        if (ownSessionId != null) {
          try {
            await api.closePlaybackSession(ownSessionId);
          } catch (_) {}
          if (_playbackSessionId == ownSessionId) _playbackSessionId = null;
        }
        return _playFromServer(
          api,
          itemId,
          title,
          author,
          coverUrl,
          totalDuration,
          chapters,
          startTime,
          forceStartTime: forceStartTime,
          forceTranscode: true,
          generation: gen,
        );
      }

      _clearState();
      return 'Playback failed: ${e.toString().split('\n').first}';
    }
  }

  bool _transcodeRetryInFlight = false;

  // Set when the player failed while paused; the next play rebuilds it
  // instead of trusting its position or its decoder.
  bool _playerBroken = false;

  /// A downloaded book needs no server to come back from a decoder failure.
  /// Android can take the decoder away from a paused app, which surfaces as
  /// a renderer error; the file is fine. Playing: start over where it was.
  /// Paused: leave it alone and rebuild on the next play, from the saved
  /// position, so the error can't send the book back to the beginning.
  Future<void> _recoverLocalPlayback(Object e) async {
    if (_currentItemId == null || _api == null) return;
    final wasPlaying = _player?.playing ?? false;
    final startS = position.inMilliseconds / 1000.0;
    debugPrint(
      '[Player] Decoder failed on a local book at ${startS.toStringAsFixed(1)}s '
      '(playing=$wasPlaying) - '
      '${wasPlaying ? "restarting from there" : "rebuilding on the next play"}: $e',
    );
    if (!wasPlaying) {
      _playerBroken = true;
      return;
    }
    await playItem(
      api: _api!,
      itemId: _currentItemId!,
      title: _currentTitle ?? '',
      author: _currentAuthor ?? '',
      coverUrl: _currentCoverUrl,
      totalDuration: _totalDuration,
      chapters: _chapters,
      startTime: startS,
      forceStartTime: startS > 0,
      episodeId: _currentEpisodeId,
      episodeTitle: _currentEpisodeTitle,
      libraryId: _currentLibraryId,
    );
  }

  Future<void> _retryWithTranscode() async {
    if (_transcodeRetryInFlight) return;
    _transcodeRetryInFlight = true;
    try {
      final api = _api;
      if (api == null || _currentItemId == null) return;
      debugPrint(
        '[Player] Playback error in stream - retrying with server transcoding',
      );
      final itemId = _currentItemId!;
      final retryEpId = _currentEpisodeId;
      final retryEpTitle = _currentEpisodeTitle;
      final retryLibraryId = _currentLibraryId;
      final retryTitle = _currentTitle ?? '';
      final retryAuthor = _currentAuthor ?? '';
      final retryCover = _currentCoverUrl;
      final failedSessionId = _playbackSessionId;
      final startTime = position.inMilliseconds / 1000.0;
      // A start of its own: a load still in flight is about to be interrupted
      // by this one and has to see that it lost, not clear the state.
      final gen = ++_playbackGeneration;
      _clearState();
      _currentItemId = itemId;
      _currentEpisodeId = retryEpId;
      _currentEpisodeTitle = retryEpTitle;
      _currentLibraryId = retryLibraryId;
      _currentTitle = retryTitle;
      _currentAuthor = retryAuthor;
      _currentCoverUrl = retryCover;
      _shortLocalDurationSec = null;
      _syncNotifSkipCache();
      if (failedSessionId != null) {
        try {
          await api.closePlaybackSession(failedSessionId);
        } catch (_) {}
      }
      final retrySession = retryEpId != null
          ? await api.startEpisodePlaybackSession(
              itemId,
              retryEpId,
              forceTranscode: true,
            )
          : await api.startPlaybackSession(itemId, forceTranscode: true);
      final ownSessionId = retrySession?['id'] as String?;
      if (_startSuperseded(gen)) {
        _abandonStart(api, ownSessionId, 'transcode retry, after the session request');
        return;
      }
      if (retrySession == null) return;
      _playbackSessionId = ownSessionId;
      final retrySessionLibId = retrySession['libraryId'] as String?;
      if ((_currentLibraryId == null || _currentLibraryId!.isEmpty) &&
          retrySessionLibId != null &&
          retrySessionLibId.isNotEmpty) {
        _currentLibraryId = retrySessionLibId;
        _syncNotifSkipCache();
      }
      _lastServerSync = DateTime.now();
      final retryTracks = retrySession['audioTracks'] as List<dynamic>?;
      final totalDuration =
          (retrySession['duration'] as num?)?.toDouble() ?? _totalDuration;
      final chapters = retrySession['chapters'] as List<dynamic>? ?? _chapters;
      _chapters = chapters;
      _totalDuration = totalDuration;
      if (retryTracks == null || retryTracks.isEmpty) return;
      _currentTrackIndex = 0;
      _buildTrackOffsets(retryTracks);
      AudioSource retrySource;
      final audioHeaders = api.playbackSessionHeaders;
      if (retryTracks.length == 1) {
        final track = retryTracks.first as Map<String, dynamic>;
        final contentUrl = track['contentUrl'] as String? ?? '';
        retrySource = AudioSource.uri(
          Uri.parse(api.buildTrackUrl(contentUrl)),
          headers: audioHeaders,
          options: mp3ExtractorOptions(),
        );
      } else {
        final sources = <AudioSource>[];
        for (final t in retryTracks) {
          final track = t as Map<String, dynamic>;
          final contentUrl = track['contentUrl'] as String? ?? '';
          sources.add(
            AudioSource.uri(
              Uri.parse(api.buildTrackUrl(contentUrl)),
              headers: audioHeaders,
              options: mp3ExtractorOptions(),
            ),
          );
        }
        retrySource = ConcatenatingAudioSource(children: sources);
      }
      await _player!.setAudioSource(retrySource, itemId: itemId);
      if (_startSuperseded(gen)) {
        _abandonStart(api, ownSessionId, 'transcode retry, after loading the source');
        return;
      }
      if (startTime > 0) await _seekForStart(startTime, gen);
      clearSeekTarget();
      _subscribeTrackIndex();
      final initChapter = _initChapterInfo(startTime);
      // Speed before _pushMediaItem - the pushed duration is speed-adjusted.
      final bookSpeed = await PlayerSettings.getBookSpeed(itemId);
      final speed = bookSpeed ??
          await PlayerSettings.defaultSpeedFor(libraryId: _currentLibraryId);
      await _player!.setSpeed(speed);
      _pushMediaItem(
        itemId,
        retryTitle,
        retryAuthor,
        retryCover,
        totalDuration,
        chapter: initChapter,
      );
      await EqualizerService().switchItem(itemId);
      debugPrint('[Player] Transcoded playback starting at ${speed}x');
      try {
        await _setAudioSessionActive(true);
      } catch (_) {}
      if (_startSuperseded(gen)) {
        _abandonStart(api, ownSessionId, 'transcode retry, before play');
        return;
      }
      _player!.play();
      _scheduleAudioDiagnostics('transcoded');
      notifyListeners();
      _setupSync();
      Future.delayed(const Duration(milliseconds: 500), () {
        _handler?.refreshPlaybackState();
      });
      final sleepTimer = SleepTimerService();
      sleepTimer.resetDismiss();
      sleepTimer.checkAutoSleep();
      SessionCache.save(
        itemId: itemId,
        episodeId: retryEpId,
        audioTracks: retryTracks,
        chapters: chapters,
        totalDuration: totalDuration,
      );
    } catch (e) {
      debugPrint('[Player] Transcode retry failed: $e');
    } finally {
      _transcodeRetryInFlight = false;
    }
  }

  /// Set _currentChapterStart/End for the chapter containing [posSeconds].
  /// Index of the chapter covering [posSeconds] in an arbitrary chapter list
  /// (used for the pre-buffered next book, whose chapters aren't in
  /// [_chapters] yet), the first one when none does, or -1 with no chapters.
  int _chapterIndexAt(List<dynamic> chapters, double posSeconds) {
    if (chapters.isEmpty) return -1;
    for (var i = 0; i < chapters.length; i++) {
      final m = chapters[i] as Map<String, dynamic>;
      final start = (m['start'] as num?)?.toDouble() ?? 0;
      final end = (m['end'] as num?)?.toDouble() ?? double.infinity;
      if (posSeconds >= start && posSeconds < end) return i;
    }
    return 0;
  }

  /// Returns the chapter title (or null) so _pushMediaItem can show it.
  String? _initChapterInfo(double posSeconds) {
    if (_chapters.isEmpty) return null;
    for (int i = 0; i < _chapters.length; i++) {
      final ch = _chapters[i] as Map<String, dynamic>;
      final start = (ch['start'] as num?)?.toDouble() ?? 0;
      final end = (ch['end'] as num?)?.toDouble() ?? _totalDuration;
      if (posSeconds >= start && posSeconds < end) {
        _currentChapterStart = start;
        _currentChapterEnd = end;
        _lastNotifiedChapterIndex = i;
        return ch['title'] as String?;
      }
    }
    // Slightly past the last chapter still counts as the last chapter.
    // Grossly past it means the chapters don't cover the timeline (e.g.
    // duplicate audio files doubling the duration, GH #345) - report no
    // chapter rather than pinning the last one.
    final graceIdx =
        ChapterLookup.indexAtWithGrace(_chapters, posSeconds, _totalDuration);
    if (graceIdx != null) {
      final ch = _chapters[graceIdx] as Map<String, dynamic>;
      _currentChapterStart = (ch['start'] as num?)?.toDouble() ?? 0;
      _currentChapterEnd = (ch['end'] as num?)?.toDouble() ?? _totalDuration;
      _lastNotifiedChapterIndex = graceIdx;
      return ch['title'] as String?;
    }
    _currentChapterStart = 0;
    _currentChapterEnd = _totalDuration;
    _lastNotifiedChapterIndex = -1;
    return null;
  }

  /// Content provider authority. Follows the installed package, as the
  /// manifest's `${applicationId}.covers` does, so the dev flavor reaches its
  /// own provider.
  static String get _coverAuthority => '${ApiService.packageName}.covers';

  void _pushMediaItem(
    String itemId,
    String title,
    String author,
    String? coverUrl,
    double totalDuration, {
    String? chapter,
    int? coverCacheBust,
    double? positionSec,
  }) {
    // Alpha [PodDur]: trace every push-site. We want to see which callers
    // pass only the parent itemId (missing -episodeId suffix) and/or a zero
    // duration, so we can pinpoint what to fix for the AA podcast progress
    // bar. Includes the current _totalDuration so "stale 0" paths are visible.
    debugPrint(
      '[PodDur] _pushMediaItem: itemId=$itemId ep=$_currentEpisodeId argDur=${totalDuration.toStringAsFixed(1)}s _totalDuration=${_totalDuration.toStringAsFixed(1)}s',
    );
    // Android: Always use content:// URI for Now Playing artwork - some OEMs
    // (e.g. Vivo) don't load HTTP URLs in MediaSession. The CoverContentProvider
    // handles both downloaded and streamed covers.
    // iOS: prefer the local cover file for downloaded books so the lock
    // screen shows artwork even when the user is offline. Fall back to the
    // remote HTTP URL when there's no local cover (streaming).
    String? effectiveCoverUrl;
    if (AppPlatform.lacksPhonePlugins) {
      effectiveCoverUrl = coverUrl;
    } else if (AppPlatform.isIOS) {
      final localCover = DownloadService().getInfo(itemId).localCoverPath;
      if (localCover != null && localCover.isNotEmpty) {
        effectiveCoverUrl = Uri.file(localCover).toString();
      } else {
        effectiveCoverUrl = coverUrl;
      }
    } else if (AppPlatform.isAndroid) {
      final localCover = DownloadService().getInfo(itemId).localCoverPath;
      final streamed = localCover == null || localCover.isEmpty;
      // Some re-pushes (foreground, speed, settings) pass the episode's
      // item-episode key. A downloaded episode keeps its cover under that
      // key, but the server only has covers under the item id, so a streamed
      // episode asked for that key got the placeholder note (GH #401).
      final coverId = streamed &&
              _currentEpisodeId != null &&
              itemId == '$_currentItemId-$_currentEpisodeId'
          ? _currentItemId!
          : itemId;
      effectiveCoverUrl = 'content://$_coverAuthority/cover/$coverId';
      if (coverCacheBust != null) effectiveCoverUrl += '?cb=$coverCacheBust';
      // Streamed cover (no local file) won't be cached on first play - schedule
      // one cache-busted re-push so the art shows up the first time too.
      if (streamed && coverCacheBust == null && _coverRepushItem != coverId) {
        _coverRepushItem = coverId;
        _scheduleStreamedCoverRepush(itemId);
      }
    } else {
      effectiveCoverUrl = coverUrl;
    }
    _updateNotificationMediaItem(
      itemId,
      title,
      author,
      effectiveCoverUrl,
      totalDuration,
      chapter: chapter,
      positionSec: positionSec,
    );
  }

  /// Push the media item again for the chapter already showing, e.g. when a
  /// setting or the book percentage changes.
  void _repushNotifiedMediaItem({double? positionSec}) {
    _pushMediaItem(
      _mediaItemKey,
      _currentTitle ?? '',
      _currentAuthor ?? '',
      _currentCoverUrl,
      _totalDuration,
      chapter: _lastNotifiedChapterIndex >= 0 &&
              _lastNotifiedChapterIndex < _chapters.length
          ? (_chapters[_lastNotifiedChapterIndex]
                    as Map<String, dynamic>)['title']
                as String?
          : null,
      positionSec: positionSec,
    );
  }

  static int _bookPercent(double posSec, double totalDuration) =>
      totalDuration > 0
          ? (posSec / totalDuration * 100).floor().clamp(0, 100)
          : -1;

  double _secondsLeft(double posSec, double totalDuration) {
    final left = math.max(0.0, totalDuration - posSec);
    final speed = _player?.speed ?? 1.0;
    return _speedAdjustedTime && speed > 0 ? left / speed : left;
  }

  /// The moving parts of the media controls text at [posSec], so the
  /// position tick only re-sends it when what it shows would change.
  String _nowPlayingTicker(double posSec, double totalDuration) {
    final layout = _nowPlayingLayout;
    final percent = layout.uses(NowPlayingPiece.percent)
        ? _bookPercent(posSec, totalDuration)
        : -1;
    final minutes = layout.uses(NowPlayingPiece.timeLeft) && totalDuration > 0
        ? (_secondsLeft(posSec, totalDuration) / 60).floor()
        : -1;
    return '$percent|$minutes';
  }

  static AppLocalizations? _l10n() {
    final ctx = rootNavigatorKey.currentContext;
    return ctx != null ? AppLocalizations.of(ctx) : null;
  }

  /// Both lines of the media controls for an item, in the layout the user
  /// picked (Settings > Media Controls > Now playing text).
  ({String title, String subtitle}) _nowPlayingLines({
    required String title,
    required String author,
    required String? chapter,
    required int chapterIndex,
    required int chapterCount,
    required double posSec,
    required double totalDuration,
    String? narrator,
    String? series,
    NowPlayingLayout? layout,
  }) {
    final l = _l10n();
    final percent = _bookPercent(posSec, totalDuration);
    final left = totalDuration > 0
        ? formatHm(_secondsLeft(posSec, totalDuration))
        : null;
    final hasChapter = chapterIndex >= 0 && chapterCount > 0;
    return (layout ?? _nowPlayingLayout).build(NowPlayingValues(
      title: title,
      author: author,
      chapter: chapter,
      narrator: narrator,
      series: series,
      percent: percent >= 0 ? '$percent%' : null,
      chapterNumber: hasChapter
          ? (l?.nowPlayingChapterNumber(chapterIndex + 1, chapterCount) ??
              'Ch. ${chapterIndex + 1}/$chapterCount')
          : null,
      timeLeft: left == null
          ? null
          : (l?.nowPlayingTimeLeft(left) ?? '$left left'),
    ));
  }

  /// What the media controls would show for the playing item with [layout],
  /// for the settings preview; null with nothing loaded.
  ({String title, String subtitle})? previewNowPlayingLines(
    NowPlayingLayout layout,
  ) {
    if (_currentItemId == null) return null;
    final chapterIndex = _lastNotifiedChapterIndex >= 0 &&
            _lastNotifiedChapterIndex < _chapters.length
        ? _lastNotifiedChapterIndex
        : -1;
    return _nowPlayingLines(
      title: _currentTitle ?? '',
      author: _currentAuthor ?? '',
      chapter: chapterIndex >= 0
          ? (_chapters[chapterIndex] as Map<String, dynamic>)['title'] as String?
          : null,
      chapterIndex: chapterIndex,
      chapterCount: _chapters.length,
      posSec: position.inMilliseconds / 1000.0,
      totalDuration: _totalDuration,
      narrator: _currentNarrator,
      series: _currentSeries,
      layout: layout,
    );
  }

  /// Narrator and series for the media controls, from a playback session's
  /// book details. Re-sends the text when they arrive after it went out.
  void _captureNowPlayingCredits(Map<String, dynamic>? session) {
    final meta = session?['mediaMetadata'];
    if (meta is! Map) return;
    String? joined(Object? names) {
      if (names is! List) return null;
      final parts = names
          .map((n) => (n is Map ? n['name'] : n)?.toString().trim() ?? '')
          .where((n) => n.isNotEmpty);
      return parts.isEmpty ? null : parts.join(', ');
    }
    final narrator = joined(meta['narrators']) ??
        (meta['narratorName'] is String ? meta['narratorName'] as String : null);
    String? series;
    final seriesList = meta['series'];
    if (seriesList is List && seriesList.isNotEmpty && seriesList.first is Map) {
      final first = seriesList.first as Map;
      final name = first['name']?.toString().trim() ?? '';
      final sequence = first['sequence']?.toString().trim() ?? '';
      if (name.isNotEmpty) {
        series = sequence.isEmpty ? name : '$name #$sequence';
      }
    } else if (meta['seriesName'] is String) {
      series = meta['seriesName'] as String;
    }
    if (narrator == _currentNarrator && series == _currentSeries) return;
    _currentNarrator = narrator;
    _currentSeries = series;
    if (_currentItemId != null &&
        (_nowPlayingLayout.uses(NowPlayingPiece.narrator) ||
            _nowPlayingLayout.uses(NowPlayingPiece.series))) {
      _repushNotifiedMediaItem();
    }
  }

  void _scheduleStreamedCoverRepush(String itemId) {
    _coverRepushTimer?.cancel();
    _coverRepushTimer = Timer(const Duration(seconds: 3), () {
      // Only re-push if we're still on the same item.
      if (_currentItemId == null) return;
      if (_currentItemId != itemId && _mediaItemKey != itemId) return;
      final chapterTitle =
          _lastNotifiedChapterIndex >= 0 && _chapters.isNotEmpty
          ? (_chapters[_lastNotifiedChapterIndex]
                    as Map<String, dynamic>)['title']
                as String?
          : null;
      _pushMediaItem(
        itemId,
        _currentTitle ?? '',
        _currentAuthor ?? '',
        _currentCoverUrl,
        _totalDuration,
        chapter: chapterTitle,
        coverCacheBust: DateTime.now().millisecondsSinceEpoch,
      );
    });
  }

  void _updateNotificationMediaItem(
    String itemId,
    String title,
    String author,
    String? coverUrl,
    double totalDuration, {
    String? chapter,
    double? positionSec,
  }) {
    final posSec = positionSec ?? position.inMilliseconds / 1000.0;
    final labels = _nowPlayingLines(
      title: title,
      author: author,
      chapter: chapter,
      chapterIndex: chapter == null ? -1 : _lastNotifiedChapterIndex,
      chapterCount: _chapters.length,
      posSec: posSec,
      totalDuration: totalDuration,
      narrator: _currentNarrator,
      series: _currentSeries,
    );
    _lastNowPlayingTicker = _nowPlayingTicker(posSec, totalDuration);
    // In chapter progress mode, show chapter duration instead of full book
    final rawDuration = notifChapterMode
        ? (_currentChapterEnd - _currentChapterStart)
        : totalDuration;
    // Divide by playback speed so Android Auto / WearOS / notification
    // show "real time remaining" instead of raw content duration.
    final speed = _player?.speed ?? 1.0;
    final displayDuration = speed > 0 && speed != 1.0
        ? rawDuration / speed
        : rawDuration;
    // Alpha: confirms MediaItem metadata flowing to MediaSession for GH #172
    // (BT car display stuck on prior chapter). If this fires with fresh
    // artist/chapter text but the car still shows old, the issue is downstream
    // of audio_service's MediaSession push.
    debugPrint(
      '[Handler] mediaItem.add: item=$itemId title="${labels.title}" artist="${labels.subtitle}" dur=${displayDuration.round()}s chapter=$chapter hasHandler=${_handler != null} art=${coverUrl == null ? 'none' : coverUrl.startsWith('content:') ? 'content' : coverUrl.startsWith('file:') ? 'file' : coverUrl.startsWith('http') ? 'http' : 'other'}',
    );
    _handler!.mediaItem.add(
      MediaItem(
        id: itemId,
        title: labels.title,
        artist: labels.subtitle,
        album: title,
        duration: Duration(seconds: displayDuration.round()),
        artUri: coverUrl != null ? Uri.tryParse(coverUrl) : null,
      ),
    );
  }

  void _clearState() {
    _currentItemId = null;
    _currentEpisodeId = null;
    _currentLibraryId = null;
    _currentEpisodeTitle = null;
    _currentTitle = null;
    _currentAuthor = null;
    _currentNarrator = null;
    _currentSeries = null;
    _currentCoverUrl = null;
    _coverRepushTimer?.cancel();
    _coverRepushItem = null;
    _playbackSessionId = null;
    _isOfflineMode = false;
    _localSessionMode = false;
    _trackStartOffsets = [];
    _currentTrackIndex = 0;
    _lastNotifiedChapterIndex = -1;
    _lastSeekTargetSeconds = null;
    _lastSeekTime = null;
    _lastIndexAdvanceTime = null;
    _iosLastTrackRecoveryAttempts = 0;
    _indexSub?.cancel();
    _indexSub = null;
    _syncSub?.cancel();
    _syncSub = null;
    _completionSub?.cancel();
    _completionSub = null;
    _nativeAutoAdvanceSub?.cancel();
    _nativeAutoAdvanceSub = null;
    _lastKnownPositionSec = 0;

    _bgSaveTimer?.cancel();
    _bgSaveTimer = null;
    _eqSessionSub?.cancel();
    _eqSessionSub = null;
    _streamRetryCount = 0;
    _retryInProgress = false;

    _stuckCheckTimer?.cancel();
    _stuckCheckTimer = null;
    _playVerifyTimer?.cancel();
    _playVerifyTimer = null;
    _resetStuckDetection();
    _noisyPause = false;
    notifyListeners();
  }

  // How long a cached play waits for the real session before falling back to
  // the instant cached start. Long enough for LAN/WiFi round trips, short
  // enough that a slow reverse proxy doesn't make press-play feel laggy.
  static const _sessionRaceWindow = Duration(milliseconds: 700);

  // A fresh session whose tokenless URLs the playing source should adopt at
  // the next pause or seek - the two moments a source rebuild is inaudible.
  // Set whenever a session is (re)created behind an already-playing source:
  // cached fast-starts, sync-tick recreations, resume recreations. One-shot.
  Map<String, dynamic>? _pendingSessionUpgrade;
  int _pendingUpgradeGeneration = -1;

  void _stashSessionUpgrade(Map<String, dynamic> sessionData) {
    final tracks = sessionData['audioTracks'] as List<dynamic>?;
    if (tracks == null || tracks.isEmpty) return;
    _pendingSessionUpgrade = sessionData;
    _pendingUpgradeGeneration = _playbackGeneration;
    debugPrint(
      '[StreamUpgrade] Holding session ${sessionData['id']} for a swap at the next pause/seek',
    );
  }

  /// Swap the playing source onto [_pendingSessionUpgrade]'s tokenless session
  /// URLs. Called only from moments where playback is already interrupted
  /// (paused, or mid-seek), so the rebuild rides inside that interruption.
  /// Returns true when the swap happened and already landed at
  /// [seekToSeconds] (or the current position); the caller must then skip its
  /// own seek. Any failure keeps the old, still-working source.
  Future<bool> _applyPendingSessionUpgrade({
    double? seekToSeconds,
    bool resumeAfter = false,
  }) async {
    final session = _pendingSessionUpgrade;
    if (session == null || _player == null || _api == null) return false;
    if (_pendingUpgradeGeneration != _playbackGeneration ||
        _isOfflineMode ||
        _localSessionMode) {
      _pendingSessionUpgrade = null;
      return false;
    }
    // While casting, the local player isn't the real output - keep the
    // pending session for when local playback matters again.
    if (ChromecastService().isCasting) return false;
    final sessionId = session['id'] as String?;
    final tracks = session['audioTracks'] as List<dynamic>?;
    final playMethod = (session['playMethod'] as num?)?.toInt();
    if (sessionId == null ||
        sessionId != _playbackSessionId ||
        tracks == null ||
        tracks.isEmpty) {
      // Session got replaced or closed since it was stashed - a swap onto its
      // URLs would point at a dead session.
      _pendingSessionUpgrade = null;
      return false;
    }
    _pendingSessionUpgrade = null; // one-shot, success or not
    var sourceReplaced = false;
    try {
      final api = _api!;
      final target = (seekToSeconds ?? position.inMilliseconds / 1000.0)
          .clamp(0.0, double.infinity)
          .toDouble();
      final audioHeaders = api.playbackSessionHeaders;
      final trackSources = <AudioSource>[];
      var tokenless = true;
      for (final t in tracks) {
        final track = t as Map<String, dynamic>;
        final contentUrl = track['contentUrl'] as String? ?? '';
        final fullUrl = api.buildTrackUrl(
          contentUrl,
          sessionId: sessionId,
          trackIndex: (track['index'] as num?)?.toInt(),
          playMethod: playMethod,
        );
        if (fullUrl.contains('token=')) tokenless = false;
        trackSources.add(
          AudioSource.uri(
            Uri.parse(fullUrl),
            headers: audioHeaders,
            options: mp3ExtractorOptions(),
          ),
        );
      }
      if (!tokenless) {
        // Old server or transcode session - the swap would just re-bake a
        // token, which is what the current source already has.
        debugPrint('[StreamUpgrade] Session URLs still carry a token - skipping');
        return false;
      }
      // Map the absolute target onto (track, local position) for the new source.
      _buildTrackOffsets(tracks);
      var idx = 0;
      for (int i = 0; i < _trackStartOffsets.length - 1; i++) {
        if (target < _trackStartOffsets[i + 1] ||
            i == _trackStartOffsets.length - 2) {
          idx = i;
          break;
        }
      }
      final localPos = Duration(
        milliseconds: ((target - _trackStartOffsets[idx]) * 1000).round(),
      );
      // Stamp the seek target so position readers (UI, progress save) hold at
      // the target while the new source loads instead of flashing 0.
      _lastSeekTargetSeconds = target;
      _lastSeekTime = DateTime.now();
      _captureStreamUrls(
        tracks,
        api,
        sessionId: sessionId,
        playMethod: playMethod,
      );
      final source = ConcatenatingAudioSource(children: trackSources);
      _resetPreBufferState();
      // Update index BEFORE loading so positionStream events use the right offset
      _currentTrackIndex = idx;
      sourceReplaced = true;
      // A server that refuses connections left this loading for 82s with
      // Play stuck behind it (GH #344).
      await _player!
          .setAudioSource(
            source,
            initialIndex: idx,
            initialPosition: localPos,
            itemId: _currentItemId,
          )
          .timeout(_swapLoadTimeout);
      _activeConcatSource = source;
      _currentBookTrackCount = trackSources.length;
      _subscribeTrackIndex();
      if (resumeAfter) _player!.play();
      debugPrint(
        '[StreamUpgrade] Swapped to tokenless session URLs at ${target.toStringAsFixed(1)}s '
        '(track $idx, resume=$resumeAfter)',
      );
      return true;
    } catch (e) {
      if (!sourceReplaced) {
        debugPrint('[StreamUpgrade] Swap failed - keeping current source: $e');
        return false;
      }
      // The old source is already gone, so there's nothing to keep. Leave the
      // player idle: the next play() sees that and starts the item over
      // instead of pressing play on a half-loaded source.
      debugPrint('[StreamUpgrade] Swap failed after replacing the source - resetting the player: $e');
      try {
        await _player?.stop();
      } catch (_) {}
      if (resumeAfter) unawaited(_attemptStreamRetry(e));
      return false;
    }
  }

  static const _swapLoadTimeout = Duration(seconds: 15);

  /// Attempt to recover from a stream error by restarting playback from the
  /// last known position.  Tries up to [_maxStreamRetries] times with
  /// exponential back-off (1s, 2s, 4s).  If the item has been downloaded in
  /// the meantime, falls back to local files automatically.
  Future<void> _attemptStreamRetry(Object error) async {
    if (_retryInProgress) return;
    if (_currentItemId == null || _api == null) return;
    if (_streamRetryCount >= _maxStreamRetries) {
      debugPrint(
        '[Player] Max retries reached ($_maxStreamRetries) — giving up',
      );
      return;
    }

    _retryInProgress = true;
    _streamRetryCount++;
    final delay = Duration(seconds: 1 << (_streamRetryCount - 1)); // 1s, 2s, 4s
    debugPrint(
      '[Player] Stream error — retry $_streamRetryCount/$_maxStreamRetries in ${delay.inSeconds}s',
    );

    await Future<void>.delayed(delay);

    // Snapshot state before retry — playItem will overwrite these
    final itemId = _currentItemId;
    final title = _currentTitle ?? '';
    final author = _currentAuthor ?? '';
    final coverUrl = _currentCoverUrl;
    final totalDuration = _totalDuration;
    final chapters = List<dynamic>.from(_chapters);
    final episodeId = _currentEpisodeId;
    final episodeTitle = _currentEpisodeTitle;
    final libraryId = _currentLibraryId;
    final api = _api!;
    final retryPos = _lastKnownPositionSec > 0
        ? _lastKnownPositionSec
        : (_lastSeekTargetSec ?? 0);

    if (itemId == null) {
      _retryInProgress = false;
      return;
    }

    // A stream error usually means the cached-session URLs went bad (expired
    // baked token, dead public session). Drop the cache entry so the rebuild
    // takes the fresh-session path - tokenless public URLs with a
    // known-good credential - instead of re-baking whatever just failed.
    await SessionCache.clear(itemId: itemId, episodeId: episodeId);
    // The server turned the byte range down: the file changed size since its
    // bytes were cached, and the cache keeps asking up to the old length.
    if ('$error'.contains('Response code: 416')) {
      debugPrint('[Player] Server refused the byte range (416) - clearing the streaming cache');
      try {
        await AudioPlayer.clearStreamingCache();
      } catch (e) {
        debugPrint('[Player] Streaming cache clear failed: $e');
      }
    }

    debugPrint('[Player] Retrying playback at ${retryPos.toStringAsFixed(1)}s');
    final ok = await playItem(
      api: api,
      itemId: itemId,
      title: title,
      author: author,
      coverUrl: coverUrl,
      totalDuration: totalDuration,
      chapters: chapters,
      startTime: retryPos,
      forceStartTime: true,
      episodeId: episodeId,
      episodeTitle: episodeTitle,
      libraryId: libraryId,
    );

    _retryInProgress = false;
    if (ok == null) {
      debugPrint('[Player] Retry succeeded');
    } else {
      debugPrint('[Player] Retry failed: $ok');
    }
  }

  int _lastSyncSecond = -1;
  int _lastBgProcessedSec = -1;

  StreamSubscription? _eqSessionSub;

  void _attachEqualizer() {
    _eqSessionSub?.cancel();
    _eqSessionSub = null;
    if (_player == null) return;

    // Try immediately — works if audio source is already set
    final sessionId = _player!.androidAudioSessionId;
    if (sessionId != null && sessionId > 0) {
      EqualizerService().attachToSession(sessionId);
      return;
    }

    // Not available yet — poll briefly after playback starts
    // (safer than androidAudioSessionIdStream which may not exist in all versions)
    Future.delayed(const Duration(milliseconds: 500), () {
      if (_player == null) return;
      final id = _player!.androidAudioSessionId;
      if (id != null && id > 0) {
        debugPrint('[Player] Got audio session ID (delayed): $id');
        EqualizerService().attachToSession(id);
      } else {
        // Try once more after another second
        Future.delayed(const Duration(seconds: 1), () {
          if (_player == null) return;
          final id2 = _player!.androidAudioSessionId;
          if (id2 != null && id2 > 0) {
            debugPrint('[Player] Got audio session ID (retry): $id2');
            EqualizerService().attachToSession(id2);
          }
        });
      }
    });
  }

  void _setupSync() {
    _syncSub?.cancel();
    _completionSub?.cancel();
    _nativeAutoAdvanceSub?.cancel();
    _bgSaveTimer?.cancel();
    _lastSyncSecond = -1;
    _lastBgProcessedSec = -1;
    _lastChapterCheckSec = -1;
    _lastKnownPositionSec = 0;
    _lastServerSync = DateTime.now();
    _lastAccrual = DateTime.now();
    _lastAccrualPos = null;
    _positionSyncInProgress = false;
    _positionSyncFailures = 0;
    _noSessionSyncRetryAt = null;
    // Cache prefs in background - not needed synchronously here
    if (_prefs == null) {
      SharedPreferences.getInstance().then((p) => _prefs = p);
    }

    // Safety-net timer for position persistence when Android throttles the
    // Dart position stream in the background. The primary positionStream
    // listener saves every 5s; this only matters when that stream goes silent.

    _bgSaveTimer = Timer.periodic(const Duration(seconds: 300), (_) async {
      if (_currentItemId == null || _player == null || !_player!.playing)
        return;
      final pos = position;
      final posSec = pos.inMilliseconds / 1000.0;
      if (posSec <= 0) return;
      await _saveProgressLocal(pos);
      // Backstop: if the position stream is frozen (Doze), this still banks
      // listening. Shares _lastAccrual so it can't double-count live ticks.
      await _accrueListening(pos);
    });

    // Attach equalizer to current audio session
    _attachEqualizer();

    // Native iOS engine fires bookAutoAdvancedStream when it has swapped to
    // the pre-buffered next book. Empty stream on Android / iOS-flag-off, so
    // this is a no-op everywhere else.
    _nativeAutoAdvanceSub?.cancel();
    _nativeAutoAdvanceSub = _player?.bookAutoAdvancedStream.listen((_) {
      if (_preloadedNextBook != null) {
        debugPrint(
          '[NativeEngine] bookAutoAdvanced received — firing auto-queue advance',
        );
        _onAutoQueueAdvanced();
      }
    });

    // ─── Primary completion detection via processingState ───
    // This fires reliably when ExoPlayer reaches STATE_ENDED, before any
    // position-reset can confuse the position-based detection.
    _completionSub = _player?.processingStateStream.listen(
      (state) {
        if (state == ProcessingState.completed && _currentItemId != null) {
          if (_preloadedNextBook != null) {
            debugPrint(
              '[PreBuffer] processingState=completed with pre-buffer loaded — firing auto-queue advance',
            );
            _onAutoQueueAdvanced();
          } else {
            _onPlaybackComplete();
          }
        }
        // Notify UI when buffering/loading state changes so spinners update.
        // Skip when backgrounded - no visible UI to rebuild; flushed on foreground.
        if (!_isBackgrounded &&
            (state == ProcessingState.ready ||
                state == ProcessingState.loading ||
                state == ProcessingState.buffering)) {
          notifyListeners();
        }
      },
      onError: (Object e, StackTrace st) {
        debugPrint('[Player] processingState stream error: $e');
        _attemptStreamRetry(e);
      },
    );
    _syncSub = _player?.positionStream.listen(
      (trackRelativePos) async {
        // Reset retry counter on successful position updates
        _streamRetryCount = 0;
        // Convert track-relative position to absolute book position
        final absolutePos = position; // uses the getter which adds track offset
        final sec = absolutePos.inSeconds;
        final posSec = absolutePos.inMilliseconds / 1000.0;

        // After a track advance, push once now that the new position has landed
        // so the background lock screen isn't left stale until foreground.
        if (_pendingTrackAdvanceRefresh) {
          _pendingTrackAdvanceRefresh = false;
          _handler?.refreshPlaybackState();
        }

        // ─── Position-reset guard ────────────────────────────
        // ExoPlayer can seek to 0 on STATE_ENDED. If we were near the end
        // and suddenly jump to near 0 without a user seek, treat it as
        // completion rather than restarting playback.
        if (_lastKnownPositionSec > 0 && _totalDuration > 0) {
          final wasNearEnd = _lastKnownPositionSec >= _totalDuration - 5.0;
          final nowNearStart = posSec < 2.0;
          if (wasNearEnd && nowNearStart) {
            if (_preloadedNextBook != null) {
              debugPrint(
                '[PreBuffer] Position jump near-end → 0 with pre-buffer loaded — firing auto-queue advance',
              );
              _onAutoQueueAdvanced();
              return;
            }
            debugPrint(
              '[Player] Position jumped from ${_lastKnownPositionSec.toStringAsFixed(1)}s to ${posSec.toStringAsFixed(1)}s — treating as completion',
            );
            _onPlaybackComplete();
            return;
          }
        }
        if (posSec > 0) _lastKnownPositionSec = posSec;

        _maybePreloadNextBook();

        // On iOS in background, fire the cross-book transition just before the
        // current item ends. The native handover swaps the player item in one
        // step, keeping the AVPlayer rate continuous so iOS doesn't drop the
        // background route. Foreground still uses the regular auto-advance path.
        if (AppPlatform.isIOS &&
            _isBackgrounded &&
            _preloadedNextBook != null &&
            !_autoQueueAdvancing &&
            _totalDuration > 0 &&
            (_player?.playing ?? false)) {
          final remaining = _totalDuration - posSec;
          if (remaining > 0 && remaining <= 0.5) {
            debugPrint(
              '[PreBuffer] Proactive iOS transition at remaining=${remaining.toStringAsFixed(2)}s',
            );
            _onAutoQueueAdvanced();
            return;
          }
        }

        if (sec <= 0) return;

        // In background, only process once per second to save CPU.
        if (_isBackgrounded) {
          if (sec == _lastBgProcessedSec) return;
          _lastBgProcessedSec = sec;
        }

        // ─── Chapter change detection ──────────────────────────
        // Update notification subtitle when the chapter changes.
        // Throttled to once per second — chapters can't change faster than that.
        if (_chapters.isNotEmpty &&
            _currentItemId != null &&
            sec != _lastChapterCheckSec) {
          _lastChapterCheckSec = sec;
          int chapterIdx = -1;
          String? chapterTitle;
          double chapterStart = 0;
          double chapterEnd = _totalDuration;

          // Fast path: check if still in the cached chapter
          if (_lastNotifiedChapterIndex >= 0 &&
              _lastNotifiedChapterIndex < _chapters.length) {
            final ch =
                _chapters[_lastNotifiedChapterIndex] as Map<String, dynamic>;
            final s = (ch['start'] as num?)?.toDouble() ?? 0;
            final e = (ch['end'] as num?)?.toDouble() ?? _totalDuration;
            if (posSec >= s && posSec < e) {
              chapterIdx = _lastNotifiedChapterIndex;
              chapterTitle = ch['title'] as String?;
              chapterStart = s;
              chapterEnd = e;
            }
          }

          // Slow path: linear scan only if cached chapter didn't match
          if (chapterIdx < 0) {
            for (int i = 0; i < _chapters.length; i++) {
              final ch = _chapters[i] as Map<String, dynamic>;
              final start = (ch['start'] as num?)?.toDouble() ?? 0;
              final end = (ch['end'] as num?)?.toDouble() ?? _totalDuration;
              if (posSec >= start && posSec < end) {
                chapterIdx = i;
                chapterTitle = ch['title'] as String?;
                chapterStart = start;
                chapterEnd = end;
                break;
              }
            }
          }

          // Within the grace window past the last chapter, keep the last one
          if (chapterIdx < 0) {
            final g = ChapterLookup.indexAtWithGrace(_chapters, posSec, _totalDuration);
            if (g != null) {
              final ch = _chapters[g] as Map<String, dynamic>;
              chapterIdx = g;
              chapterTitle = ch['title'] as String?;
              chapterStart = (ch['start'] as num?)?.toDouble() ?? 0;
              chapterEnd = (ch['end'] as num?)?.toDouble() ?? _totalDuration;
            }
          }

          if (chapterIdx < 0 && _lastNotifiedChapterIndex >= 0) {
            // Position left the chapter span entirely - clear the stale
            // chapter so the notification stops claiming the last one
            debugPrint(
              '[Battery] Chapter cleared: ${posSec.toStringAsFixed(1)}s is outside the chapter span',
            );
            _lastNotifiedChapterIndex = -1;
            _currentChapterStart = 0;
            _currentChapterEnd = _totalDuration;
            _pushMediaItem(
              _currentItemId!,
              _currentTitle ?? '',
              _currentAuthor ?? '',
              _currentCoverUrl,
              _totalDuration,
            );
          }

          if (chapterIdx >= 0 && chapterIdx != _lastNotifiedChapterIndex) {
            debugPrint(
              '[Battery] Chapter change: idx=$chapterIdx "$chapterTitle" at ${posSec.toStringAsFixed(1)}s',
            );
            _lastNotifiedChapterIndex = chapterIdx;
            _currentChapterStart = chapterStart;
            _currentChapterEnd = chapterEnd;
            _pushMediaItem(
              _currentItemId!,
              _currentTitle ?? '',
              _currentAuthor ?? '',
              _currentCoverUrl,
              _totalDuration,
              chapter: chapterTitle,
              positionSec: posSec,
            );
            // Force PlaybackState refresh so the notification position resets
            // to 0 immediately instead of waiting for the next stream event.
            if (_notifChapterMode) _handler?.refreshPlaybackState();
          }
        }

        if (_currentItemId != null &&
            _nowPlayingTicker(posSec, _totalDuration) !=
                _lastNowPlayingTicker) {
          _repushNotifiedMediaItem(positionSec: posSec);
        }

        // ─── Completion detection (fallback) ───────────────────
        // processingStateStream is the primary signal; this is a safety net.
        // Files that run longer than the server indexed them (changed on
        // disk after a scan) play on: ending the book at the indexed length
        // tore the player down mid-audio and left it stuck (GH #428).
        if (_totalDuration > 0 && posSec >= _totalDuration - 1.0 && !_engineAtEnd()) {
          if (_overrunLoggedFor != _currentItemId) {
            _overrunLoggedFor = _currentItemId;
            debugPrint('[Player] Audio runs past the indexed length '
                '(${_totalDuration.toStringAsFixed(0)}s) - playing on until the files end');
          }
        } else if (_totalDuration > 0 && posSec >= _totalDuration - 1.0) {
          if (_preloadedNextBook != null &&
              _isBackgrounded &&
              AppPlatform.isIOS) {
            debugPrint(
              '[PreBuffer] Position-fallback near end with pre-buffer loaded — firing auto-queue advance',
            );
            _onAutoQueueAdvanced();
            return;
          }
          _onPlaybackComplete();
          return;
        }

        // Save locally every 5 seconds (always works, even offline)
        if (sec % 5 == 0 && sec != _lastSyncSecond && _currentItemId != null) {
          _lastSyncSecond = sec;
          _saveProgressLocal(absolutePos);
          // Seeks emit position events while paused too (auto-rewind on
          // resume, scrubbing), and such a tick must not accrue or sync -
          // the clocks are stale from the pause, so it would credit the
          // paused span as listening. The pause handler already banked the
          // playing tail.
          if (_player?.playing != true) return;
          // Bank listening to durable storage every tick, decoupled from the
          // server push below, so an abrupt kill loses at most one tick.
          await _accrueListening(absolutePos);
          if (_isCachedStartReconcilePending) return;

          // Push to server every 20s on Wi-Fi regardless of foreground state,
          // in line with the other ABS clients (official 15s, web 10s), and
          // every 60s on cellular, where each push keeps the modem up for
          // 10-20s after and a 20s cadence never lets it sleep. Accuracy
          // rides on the accrual above, not this cadence - this is just
          // server freshness.
          final syncInterval = _onUnmeteredNetwork ? 20 : 60;
          final sinceLastSync = DateTime.now()
              .difference(_lastServerSync)
              .inSeconds;
          if (sinceLastSync >= syncInterval && !_positionSyncInProgress) {
            _positionSyncInProgress = true;
            try {
              final manualOffline =
                  (_prefs ?? await SharedPreferences.getInstance()).getBool(
                    'manual_offline_mode',
                  ) ??
                  false;

              // If we're online but lost the playback session (e.g. pause-
              // timeout closed it and _resumeServerSync silently failed when
              // playback resumed), recreate it before the accumulator branch.
              // Without this the offline accumulator fills for hours and gets
              // dumped later as one phantom session with startTime==lastTime.
              // Skipped for local-session plays — they never open a /play session.
              if (!_localSessionMode &&
                  !manualOffline &&
                  !_isOfflineMode &&
                  _playbackSessionId == null &&
                  _api != null &&
                  _currentItemId != null &&
                  !_recreatingSession) {
                _recreatingSession = true;
                try {
                  final sessionData = _currentEpisodeId != null
                      ? await _api!.startEpisodePlaybackSession(
                          _currentItemId!,
                          _currentEpisodeId!,
                        )
                      : await _api!.startPlaybackSession(_currentItemId!);
                  if (sessionData != null) {
                    _playbackSessionId = sessionData['id'] as String?;
                    if (_playbackSessionId != null) {
                      debugPrint(
                        '[Player] Recreated session in sync tick: '
                        '$_playbackSessionId',
                      );
                      // The playing source still points at the OLD session's
                      // URLs. Adopt this one at the next pause/seek, unless
                      // that old session is already gone: then the stream
                      // dies with the cache, so move it now.
                      _stashSessionUpgrade(sessionData);
                      if (_sourceSessionDead) {
                        final playing = _player?.playing ?? false;
                        if (!await _applyPendingLocalSwap(resumeAfter: playing)) {
                          await _applyPendingSessionUpgrade(resumeAfter: playing);
                        }
                      }
                    }
                  }
                } catch (e) {
                  debugPrint(
                    '[Player] Session recreate in sync tick failed: $e',
                  );
                } finally {
                  _recreatingSession = false;
                }
              }

              // Listening itself is banked every tick by _accrueListening. These
              // branches only handle the interval-rate bookkeeping (time-saved,
              // widget tick) and, for downloaded plays, pushing the local session.
              final secs = sinceLastSync.clamp(0, 300);
              if (_localSessionMode) {
                final online =
                    !manualOffline && !_isOfflineMode && _api != null;
                unawaited(
                  _progressSync.addTimeSaved(secs, _player?.speed ?? 1.0),
                );
                if (!AppPlatform.lacksPhonePlugins) {
                  unawaited(HomeWidgetService().addLocalListeningSeconds(secs));
                }
                if (online) await LocalSessionService().pushActive(api: _api!);
                _lastServerSync = DateTime.now();
              } else if (manualOffline ||
                  _isOfflineMode ||
                  _playbackSessionId == null) {
                unawaited(
                  _progressSync.addTimeSaved(secs, _player?.speed ?? 1.0),
                );
                // Widget ticks forward even when the server is unreachable.
                if (!AppPlatform.lacksPhonePlugins) {
                  unawaited(HomeWidgetService().addLocalListeningSeconds(secs));
                }
                _lastServerSync = DateTime.now();
              }

              // Back off when the server is unreachable to avoid hammering
              // every sync interval with requests that will just timeout.
              // The pause is timed and grows with each failure, so a bad
              // minute during a WiFi-to-cellular handover doesn't leave the
              // server stale for the rest of the listen.
              if (_positionSyncFailures >= 3 &&
                  _noSessionSyncRetryAt != null &&
                  DateTime.now().isBefore(_noSessionSyncRetryAt!)) {
                _lastServerSync = DateTime.now();
              } else if (manualOffline) {
                // Manual offline - local save only, no server sync
              } else if (!_isOfflineMode && _playbackSessionId != null) {
                // Streaming/local with session: sync via session
                _syncToServer(absolutePos);
              } else if (!_isOfflineMode &&
                  _api != null &&
                  _currentItemId != null) {
                // No session but online - sync via progress update endpoint
                try {
                  final syncKey = _currentEpisodeId != null
                      ? '$_currentItemId-$_currentEpisodeId'
                      : _currentItemId!;
                  final ok = await _progressSync.syncToServer(
                    api: _api!,
                    itemId: syncKey,
                  );
                  if (ok) {
                    debugPrint('[Player] No-session sync succeeded');
                    _positionSyncFailures = 0;
                    _noSessionSyncRetryAt = null;
                  } else {
                    _noteNoSessionSyncFailure('returned false');
                  }
                } catch (e) {
                  _noteNoSessionSyncFailure('error: $e');
                }
              }
            } finally {
              _positionSyncInProgress = false;
            }
          }
        }
      },
      onError: (Object e, StackTrace st) {
        debugPrint('[Player] Position stream error: $e');
        _attemptStreamRetry(e);
      },
    );

    // Start stuck position detection (xHE-AAC/USAC iOS seek failures)
    _startStuckDetection();
  }

  /// Reset stuck detection state - call on manual seek or when position advances.
  void _resetStuckDetection() {
    _stuckConsecutiveCount = 0;
    _stuckReseekAttempts = 0;
    _stuckCheckLastPosition = -1;
  }

  /// Verify that playback actually started after calling play().
  /// iOS USAC/xHE-AAC decoder can silently fail after a seek, leaving the
  /// player in a non-playing state with no error events. If after 3 seconds
  /// the player isn't playing and isn't loading, re-seek and retry.
  void _schedulePlayVerify() {
    _playVerifyTimer?.cancel();
    if (!AppPlatform.isIOS) return; // only needed on iOS
    final posAtPlay = _lastKnownPositionSec;
    _playVerifyTimer = Timer(const Duration(seconds: 3), () async {
      if (_player == null || _currentItemId == null) return;
      // If playing or actively loading/buffering, all is well
      if (_player!.playing) return;
      final state = _player!.processingState;
      if (state == ProcessingState.loading ||
          state == ProcessingState.buffering)
        return;
      // Player is idle/ready but not playing — silent failure
      final currentPos = position.inMilliseconds / 1000.0;
      debugPrint(
        '[Player] Play verify failed: not playing after 3s '
        '(state=${state.name}, pos=${currentPos.toStringAsFixed(1)}s, '
        'posAtPlay=${posAtPlay.toStringAsFixed(1)}s)',
      );
      // Re-seek to current position to kick the decoder, then retry play.
      // Activate the session first: a resume right after an interruption can
      // fail with "cannot interrupt others" while the interrupter still holds
      // the audio, and a bare play() on a never-activated session stays
      // silent even once it has let go.
      await _seekAbsolute(currentPos > 0 ? currentPos : posAtPlay);
      try {
        await (await AudioSession.instance).setActive(true);
      } catch (e) {
        debugPrint('[Player] Play verify: session activate failed: $e');
      }
      _player?.play();
      notifyListeners();
    });
  }

  /// Start a periodic timer that checks if playback position is advancing.
  /// If position is stuck for ~20 seconds while playing (2 consecutive checks),
  /// force a re-seek to the same position to kick the iOS decoder.
  void _startStuckDetection() {
    _stuckCheckTimer?.cancel();
    _resetStuckDetection();

    // Stuck detection is only needed on iOS (xHE-AAC/USAC decoder freeze).
    // Skip on Android to reduce background CPU wakeups.
    if (!AppPlatform.isIOS) return;

    _stuckCheckTimer = Timer.periodic(const Duration(seconds: 10), (_) async {
      // Only check while actively playing
      if (_player == null || !_player!.playing) {
        _stuckCheckLastPosition = -1;
        _stuckConsecutiveCount = 0;
        return;
      }

      // Don't check during loading/buffering
      final state = _player!.processingState;
      if (state == ProcessingState.loading ||
          state == ProcessingState.buffering) {
        return;
      }

      // Give up after max re-seek attempts to avoid infinite loops
      if (_stuckReseekAttempts >= _maxStuckReseekAttempts) return;

      final currentPos = position.inMilliseconds / 1000.0;
      if (currentPos <= 0) return;

      if (_stuckCheckLastPosition >= 0) {
        // Check if position has advanced (allow small tolerance for rounding)
        final advanced = (currentPos - _stuckCheckLastPosition).abs() > 0.1;
        if (advanced) {
          // Position is moving - reset counters
          _stuckConsecutiveCount = 0;
          _stuckReseekAttempts = 0;
        } else {
          // Position hasn't moved
          _stuckConsecutiveCount++;
          if (_stuckConsecutiveCount >= 2) {
            // Stuck for ~20 seconds - force re-seek
            _stuckReseekAttempts++;
            _stuckConsecutiveCount = 0;
            debugPrint(
              '[Player] Stuck position detected - re-seeking '
              '(attempt $_stuckReseekAttempts/$_maxStuckReseekAttempts '
              'at ${currentPos.toStringAsFixed(1)}s)',
            );
            await _seekAbsolute(currentPos);
          }
        }
      }

      _stuckCheckLastPosition = currentPos;
    });
  }

  bool _isCompletingBook = false;

  String? _overrunLoggedFor;

  /// Whether the player itself is at the end of the last file, rather than
  /// only past the length the server indexed.
  bool _engineAtEnd() {
    final p = _player;
    if (p == null) return true;
    if (_trackStartOffsets.length > 1 && _currentTrackIndex < _trackStartOffsets.length - 2) return false;
    final d = p.duration;
    if (d == null || d <= Duration.zero) return true;
    return p.position >= d - const Duration(seconds: 2);
  }

  Future<void> _onPlaybackComplete({bool userRequested = false}) async {
    // Alpha: captures completion path choice for GH #186 (book restart bug).
    // Re-entry attempts are logged too so we can see if completion fires
    // multiple times from different signals (processingState, position-jump,
    // fallback) and races with auto-advance.
    debugPrint(
      '[Complete] entry: pos=${_lastKnownPositionSec.toStringAsFixed(1)}s totalDur=${_totalDuration.toStringAsFixed(1)}s item=$_currentItemId ep=$_currentEpisodeId reentry=$_isCompletingBook',
    );
    if (_isCompletingBook) return; // prevent re-entry
    _isCompletingBook = true;

    // ── iOS premature last-track completion guard (GH #219) ──
    // iOS ConcatenatingAudioSource sometimes fires ProcessingState.completed
    // when advancing to the final item without actually rendering its audio.
    // Symptoms: _currentTrackIndex just flipped to the last track, completion
    // fires within seconds (impossible to have played through a multi-minute
    // last track that fast). Spurious-completion check below can't catch this
    // because the position-getter math (trackRel + offset[last]) lands at
    // total duration. Recovery: seek a hair into the last track and resume,
    // which forces AVPlayer to reload that single item correctly.
    if (!userRequested && AppPlatform.isIOS && _trackStartOffsets.length > 2) {
      final lastIdx = _trackStartOffsets.length - 2;
      final lastTrackStart = _trackStartOffsets[lastIdx];
      final lastTrackDur = _trackStartOffsets[lastIdx + 1] - lastTrackStart;
      final advanceTime = _lastIndexAdvanceTime;
      final msSinceAdvance = advanceTime == null
          ? -1
          : DateTime.now().difference(advanceTime).inMilliseconds;
      if (_currentTrackIndex == lastIdx &&
          lastTrackDur > 5.0 &&
          msSinceAdvance >= 0 &&
          msSinceAdvance < 3000 &&
          _iosLastTrackRecoveryAttempts < _maxIosLastTrackRecoveries) {
        _iosLastTrackRecoveryAttempts++;
        final recoveryTarget = lastTrackStart + 0.5;
        debugPrint(
          '[Player] iOS premature last-track completion detected '
          '(idx=$_currentTrackIndex/$lastIdx, lastTrackDur=${lastTrackDur.toStringAsFixed(1)}s, '
          'advance=${msSinceAdvance}ms ago) — recovery attempt $_iosLastTrackRecoveryAttempts: '
          'seeking to ${recoveryTarget.toStringAsFixed(1)}s',
        );
        _logEvent(
          PlaybackEventType.pause,
          detail: 'iOS premature completion blocked',
        );
        _isCompletingBook = false;
        try {
          await _seekAbsolute(recoveryTarget);
          await _player?.play();
        } catch (e) {
          debugPrint('[Player] iOS last-track recovery failed: $e');
        }
        return;
      }
    }

    // Sanity check: if we're not near the end of the book, this is a spurious
    // completion signal (iOS AVPlayer can fire completed on audio interruptions,
    // buffer errors, etc.). Save current position and stop - don't mark finished
    // or advance the queue.
    if (!userRequested &&
        _totalDuration > 0 &&
        _lastKnownPositionSec > 0 &&
        _lastKnownPositionSec < _totalDuration * 0.9 &&
        _lastKnownPositionSec < _totalDuration - 30) {
      debugPrint(
        '[Player] Spurious completion at ${_lastKnownPositionSec.toStringAsFixed(1)}s / ${_totalDuration.toStringAsFixed(1)}s — saving position instead of marking finished',
      );
      _logEvent(PlaybackEventType.pause, detail: 'Spurious completion blocked');
      _syncSub?.cancel();
      _syncSub = null;
      _completionSub?.cancel();
      _completionSub = null;
      _bgSaveTimer?.cancel();
      _bgSaveTimer = null;
      await _player?.stop();
      await _saveProgressLocal(
        Duration(milliseconds: (_lastKnownPositionSec * 1000).round()),
      );
      _isCompletingBook = false;
      notifyListeners();
      return;
    }

    debugPrint('[Player] Book complete: $_currentTitle');
    _logEvent(PlaybackEventType.bookFinished);
    if (_currentEpisodeId == null) {
      unawaited(ReviewService.onBookFinished(isForeground: !_isBackgrounded));
    }

    // Cancel subscriptions first so we don't process stale events.
    _syncSub?.cancel();
    _syncSub = null;
    _completionSub?.cancel();
    _completionSub = null;
    _nativeAutoAdvanceSub?.cancel();
    _nativeAutoAdvanceSub = null;
    _bgSaveTimer?.cancel();
    _bgSaveTimer = null;
    // Android: stop() prevents ExoPlayer's phantom seek-to-0 on completion,
    // which would fire position-stream events that look like a restart.
    // iOS: stop() calls _setPlatformActive(false) which tears down the
    // AVPlayer entirely. The rebuilt AVPlayer for the next item is not
    // granted audio session privileges in background, so audio plays
    // silently and lock screen controls vanish. pause() preserves the
    // platform player + session — paired with darwinLoadControl's
    // automaticallyWaitsToMinimizeStalling=false this gives gapless
    // background auto-advance. GH #244.
    if (AppPlatform.isAndroid) {
      await _player?.stop().timeout(const Duration(seconds: 5), onTimeout: () {
        debugPrint('[Complete] player stop took over 5s - carrying on');
      });
    } else {
      await _player?.pause();
    }

    // Mark as finished on the server (fire-and-forget to avoid blocking
    // auto-advance — the local save below is the source of truth).
    final itemId = _currentItemId;
    final episodeId = _currentEpisodeId;
    if (itemId != null && _api != null) {
      final api = _api!;
      final dur = _totalDuration;
      unawaited(() async {
        try {
          if (episodeId != null) {
            await api.updateEpisodeProgress(
              itemId,
              episodeId,
              currentTime: dur,
              duration: dur,
              isFinished: true,
            );
          } else {
            await api.markFinished(itemId, dur);
          }
          debugPrint('[Player] Marked as finished on server');
        } catch (e) {
          debugPrint('[Player] Failed to mark finished: $e');
        }
      }());
    }

    // Save locally as finished (fast, ensures offline correctness)
    if (itemId != null) {
      final progressKey = episodeId != null ? '$itemId-$episodeId' : itemId;
      await _progressSync.saveLocal(
        itemId: progressKey,
        currentTime: _totalDuration,
        duration: _totalDuration,
        speed: speed,
        isFinished: true,
      );
    }

    // Close the playback session (fire-and-forget)
    if (_playbackSessionId != null && _api != null) {
      final api = _api!;
      final sessionId = _playbackSessionId!;
      _logEvent(PlaybackEventType.sessionEnd, detail: 'book finished');
      unawaited(() async {
        try {
          debugPrint('[Player] Closing session (book finished)');
          await api.closePlaybackSession(sessionId);
        } catch (_) {}
      }());
    }

    // Local-session play: push the final accrued listening and finalize before
    // any auto-advance begins a new session (awaited to avoid racing it).
    if (_localSessionMode) {
      _logEvent(PlaybackEventType.sessionEnd, detail: 'local book finished');
      // Capped: a dozing phone on a slow tunnel left the book half finished
      // with the controls gone (GH #428).
      bool pushed = false;
      if (_api != null) {
        pushed = await LocalSessionService()
            .pushActive(api: _api!)
            .timeout(const Duration(seconds: 8), onTimeout: () => false);
      }
      await LocalSessionService()
          .finalizeActive(pushed: pushed)
          .timeout(const Duration(seconds: 8), onTimeout: () {});
    }

    // Notify LibraryProvider before clearing state so it can update isFinished locally.
    if (itemId != null) {
      final key = episodeId != null ? '$itemId-$episodeId' : itemId;
      if (_onBookFinishedCallback != null) {
        _onBookFinishedCallback!(key);
      } else {
        _pendingBookFinishedKey = key;
        debugPrint(
          '[Player] Book-finished callback not registered, buffering key=$key',
        );
      }
    }

    // Clear state (player already stopped at top of method)
    _clearState();
    _chapters = [];
    _handler?.updateChaptersQueue(const []);
    _isCompletingBook = false;
    notifyListeners();
  }

  Future<void> _saveProgressLocal(Duration pos) async {
    if (_currentItemId == null) return;
    if (_isCachedStartReconcilePending) return;
    final ct = pos.inMilliseconds / 1000.0;
    // Use compound key for podcast episodes
    final progressKey = _currentEpisodeId != null
        ? '$_currentItemId-$_currentEpisodeId'
        : _currentItemId!;
    // Incomplete download: the player pins beyond-file positions to the file's
    // end. Don't let that clamped value clobber a further-along saved position
    // (the user's real progress, recoverable once the full file streams or
    // re-downloads). GH #278. Only refuses a backward jump at the clamp point.
    if (_shortLocalDurationSec != null && ct >= _shortLocalDurationSec! - 2.0) {
      final saved = await _progressSync.getSavedPosition(progressKey);
      if (saved > ct + 1.0) {
        debugPrint(
          '[Player] Skipping save ${ct.toStringAsFixed(1)}s — would '
          'clobber further saved ${saved.toStringAsFixed(1)}s from incomplete '
          'download (GH #278)',
        );
        return;
      }
    }
    await _progressSync.saveLocal(
      itemId: progressKey,
      currentTime: ct,
      duration: _totalDuration,
      speed: speed,
    );
    // _logEvent(PlaybackEventType.syncLocal); // too noisy for history
  }

  DateTime _lastServerSync = DateTime.now();
  // Separate from the server-sync clock: drives the every-5s durable accrual so
  // a kill loses at most one tick of listening, independent of how often we POST.
  DateTime _lastAccrual = DateTime.now();
  double? _lastAccrualPos;
  bool _syncRecoveryInProgress = false;
  bool _positionSyncInProgress = false;
  int _positionSyncFailures = 0;
  DateTime? _noSessionSyncRetryAt;
  bool _recreatingSession = false;

  void _noteNoSessionSyncFailure(String what) {
    _positionSyncFailures++;
    if (_positionSyncFailures >= 3) {
      final waitSec = (60 << (_positionSyncFailures - 3)).clamp(60, 300);
      _noSessionSyncRetryAt = DateTime.now().add(Duration(seconds: waitSec));
      debugPrint(
        '[Player] No-session sync $what (failures=$_positionSyncFailures), '
        'backing off ${waitSec}s',
      );
    } else {
      debugPrint(
        '[Player] No-session sync $what (failures=$_positionSyncFailures)',
      );
    }
  }

  /// The active server address changed under a loaded book (local to remote
  /// or back). Sync, session pushes and the offline flush all go through
  /// [_api], which until now stayed on the address play started with - so
  /// after leaving WiFi every push went to a LAN address for as long as the
  /// book kept playing.
  void useApi(ApiService api) {
    final current = _api;
    if (current == null || identical(current, api)) return;
    if (current.cleanBaseUrl == api.cleanBaseUrl) return;
    debugPrint('[Player] Sync now goes to ${api.cleanBaseUrl}');
    _api = api;
  }

  /// Forget any sync backoff so the next tick pushes progress right away.
  /// Called when the network comes back or the active server changes.
  void resetServerSyncBackoff() {
    if (_positionSyncFailures == 0 && _noSessionSyncRetryAt == null) return;
    debugPrint('[Player] Sync backoff cleared (failures=$_positionSyncFailures)');
    _positionSyncFailures = 0;
    _noSessionSyncRetryAt = null;
  }
  int _playbackGeneration = 0;
  int? _cachedStartReconcileGeneration;

  /// True once a newer start has taken over from the one that was handed
  /// [generation]. Every start shares the current item, session and track
  /// state, so a start that lost has to back out without touching any of it:
  /// clearing it left the winner playing with no item (GH #391).
  bool _startSuperseded(int generation) => generation != _playbackGeneration;

  /// Backs a superseded start out: closes the server session it opened so
  /// the server is not left with a stray one, and reports nothing - the user
  /// is already listening to what they picked instead.
  String? _abandonStart(ApiService? api, String? ownSessionId, String where) {
    debugPrint('[Player] Start superseded ($where) - backing out');
    if (api != null && ownSessionId != null) {
      if (_playbackSessionId == ownSessionId) _playbackSessionId = null;
      unawaited(api.closePlaybackSession(ownSessionId));
    }
    return null;
  }

  bool get _isCachedStartReconcilePending =>
      _cachedStartReconcileGeneration == _playbackGeneration;

  /// Bank listening time to the durable store for the active play mode. Called
  /// every ~5s while playing (decoupled from the server POST) so the recorded
  /// total survives a kill. Uses wall-clock elapsed since the last accrual, so
  /// it stays correct at any speed and excludes paused spans (no ticks fire
  /// while paused; [play] restarts the clock).
  Future<void> _accrueListening(Duration absolutePos) async {
    if (_currentItemId == null) return;
    final now = DateTime.now();
    final delta = now.difference(_lastAccrual).inSeconds;
    if (delta <= 0) return;
    final ct = absolutePos.inMilliseconds / 1000.0;
    // A player can report playing while its position sits still - a stalled
    // stream, a dead web audio element. Wall clock alone would bank that span
    // as listening, and the 300s backstop timer keeps doing it for as long as
    // the app is open, so hours of standing still later ship as one phantom
    // session. Only credit a span the position actually moved through, and
    // drop the frozen span rather than carrying it into the next tick.
    final prevPos = _lastAccrualPos;
    _lastAccrualPos = ct;
    if (prevPos != null && (ct - prevPos).abs() < 0.5) {
      _lastAccrual = now;
      debugPrint(
        '[Player] Position frozen at ${ct.toStringAsFixed(1)}s - '
        'not banking ${delta}s as listening',
      );
      return;
    }
    final secs = delta > 300 ? 300 : delta;
    _lastAccrual = now;
    final key = _currentEpisodeId != null
        ? '$_currentItemId-$_currentEpisodeId'
        : _currentItemId!;
    final manualOffline = (_prefs?.getBool('manual_offline_mode')) ?? false;
    if (_localSessionMode) {
      await LocalSessionService().accrue(
        progressKey: key,
        seconds: secs,
        currentTime: ct,
        api: null,
      );
    } else if (manualOffline || _isOfflineMode || _playbackSessionId == null) {
      await _progressSync.addOfflineListeningTime(key, secs);
    } else {
      await _progressSync.addStreamingPendingTime(key, secs);
    }
  }

  Future<void> _syncToServer(Duration pos, {int? timeListenedOverride}) async {
    if (_api == null || _playbackSessionId == null) return;
    if (_isCachedStartReconcilePending) return;
    final ct = pos.inMilliseconds / 1000.0;
    // Incomplete download: stuck at the truncated file's end. Don't push that
    // clamped position to the server (it would move real progress backward) or
    // report the stuck time as listened. GH #278.
    if (_shortLocalDurationSec != null && ct >= _shortLocalDurationSec! - 2.0) {
      return;
    }
    final now = DateTime.now();
    final elapsed =
        timeListenedOverride ??
        now.difference(_lastServerSync).inSeconds.clamp(0, 300);
    _lastServerSync = now;
    // The streaming safety buffer mirrors this same span; read it before the
    // POST so we only clear what the server is about to confirm. A real
    // timeListened (not an override) is what the buffer is shadowing.
    final streamKey = (timeListenedOverride == null && _currentItemId != null)
        ? (_currentEpisodeId != null
              ? '$_currentItemId-$_currentEpisodeId'
              : _currentItemId!)
        : null;
    final pendingBefore = streamKey != null
        ? await _progressSync.getStreamingPendingTime(streamKey)
        : 0;
    if (elapsed > 0) {
      unawaited(
        _progressSync.addTimeSaved(elapsed.toInt(), _player?.speed ?? 1.0),
      );
    }
    // Alpha: volume/sessionId piggybacked for GH #179 (volume falls off).
    // We sample these on each sync tick so drift over time is visible.
    final vol = _player?.volume;
    final eqSid = _player?.androidAudioSessionId;
    debugPrint(
      '[Player] Sync session ${_playbackSessionId!.substring(0, 8)}... | currentTime=${ct.toStringAsFixed(1)}s, timeListened=${elapsed}s, volume=$vol, eqSession=$eqSid',
    );
    final status = await _api!.syncPlaybackSessionStatus(
      _playbackSessionId!,
      currentTime: ct,
      duration: _totalDuration,
      timeListened: elapsed,
    );
    final ok = status == 200;
    if (ok && elapsed > 0) {
      // Tick the StatsWidget forward locally so "today" stays fresh between
      // 15-min authoritative refreshes (which Android Doze throttles).
      if (!AppPlatform.lacksPhonePlugins) {
        unawaited(HomeWidgetService().addLocalListeningSeconds(elapsed));
      }
    }
    if (ok && streamKey != null && pendingBefore > 0) {
      unawaited(
        _progressSync.reduceStreamingPendingTime(streamKey, pendingBefore),
      );
    }
    if (ok) {
      _logEvent(PlaybackEventType.syncServer, detail: '+${elapsed}s');
    }
    if (!ok && !_syncRecoveryInProgress) {
      // Starting a new session makes the server close this one, and the
      // live source may stream through it. A failure that isn't "session
      // gone" is network trouble: keep the session, push progress through
      // the progress endpoint, and try the session again next tick.
      final sessionGone = status == 404;
      if (!sessionGone && _sourceSessionId == _playbackSessionId) {
        debugPrint(
          '[Player] Session sync failed (status=$status) - keeping the session the stream runs on, syncing progress directly',
        );
        await _syncProgressWithoutSession(pos);
        return;
      }
      debugPrint('[Player] Session sync failed - attempting recovery');
      _syncRecoveryInProgress = true;
      try {
        await _recoverSession(ct, elapsed);
        // A gone session was the one the stream ran on: the source is dead
        // already, and moving it now costs a short gap instead of the five
        // seconds of silence when the cache runs out and the retry kicks in.
        if (_sourceSessionDead) {
          final playing = _player?.playing ?? false;
          if (!await _applyPendingLocalSwap(resumeAfter: playing)) {
            await _applyPendingSessionUpgrade(resumeAfter: playing);
          }
        }
      } finally {
        _syncRecoveryInProgress = false;
      }
    }
  }

  /// Try to start a new server session when the current one becomes invalid.
  Future<void> _recoverSession(double currentTime, int lostTimeListened) async {
    if (_api == null || _currentItemId == null) return;
    try {
      final sessionData = _currentEpisodeId != null
          ? await _api!.startEpisodePlaybackSession(
              _currentItemId!,
              _currentEpisodeId!,
            )
          : await _api!.startPlaybackSession(_currentItemId!);
      if (sessionData != null) {
        _playbackSessionId = sessionData['id'] as String?;
        debugPrint('[Player] Recovered session: $_playbackSessionId');
        _logEvent(PlaybackEventType.sessionStart, detail: 'recovery');
        _stashSessionUpgrade(sessionData);
        // Re-sync the lost time to the new session
        if (_playbackSessionId != null && lostTimeListened > 0) {
          await _api!.syncPlaybackSession(
            _playbackSessionId!,
            currentTime: currentTime,
            duration: _totalDuration,
            timeListened: lostTimeListened,
          );
        }
      } else {
        debugPrint('[Player] Session recovery failed - no session returned');
        _playbackSessionId = null;
      }
    } catch (e) {
      debugPrint('[Player] Session recovery error: $e');
    }
  }

  DateTime? _lastPauseTime;
  bool _seekedWhilePaused = false;
  // Origin of the playItem in flight, read by the play paths to decide
  // whether to wait on the server's saved position. See playItem().
  bool _playFromUi = false;
  bool _wasPlayingBeforeInterrupt = false;
  bool _pauseRequested = false;
  bool get isPauseRequested => _pauseRequested;

  void _markPauseRequested() {
    _pauseRequested = true;
  }

  // Storm guard for the idle-on-resume re-init path. A book the player can't
  // start (e.g. a thousands-of-files book the engine never leaves `idle` on)
  // would otherwise re-init in a tight loop, opening a new server play session
  // each pass. Cap re-inits within a short window.
  int _idleReinitCount = 0;
  DateTime? _lastIdleReinit;
  static const _idleReinitWindow = Duration(seconds: 10);
  static const _idleReinitMaxAttempts = 3;

  /// Auto-rewind calculation using linear scaling.
  /// Scales linearly from minRewind at activationDelay to maxRewind at 1 hour.
  /// activationDelay = minimum pause before rewind kicks in (0 = always).
  static double calculateAutoRewind(
    Duration pauseDuration,
    double minRewind,
    double maxRewind, {
    double activationDelay = 0,
  }) {
    final pauseSeconds = pauseDuration.inSeconds.toDouble();

    // Don't rewind if pause is shorter than activation delay
    if (pauseSeconds < activationDelay) return 0;

    // Linear from min to max over 1 hour of pause time
    const maxPause = 3600.0; // 1 hour = full rewind
    final effectivePause = (pauseSeconds - activationDelay).clamp(
      0.0,
      maxPause,
    );
    final t = effectivePause / maxPause;
    final rewind = minRewind + (maxRewind - minRewind) * t;
    return rewind.clamp(minRewind, maxRewind);
  }

  /// [fromUi] marks a play started from the app's own screen. Only those
  /// look at the server for a position another device may have advanced,
  /// and only before audio starts. Headphones, notification, widget, lock
  /// screen and Android Auto plays resume where the phone left off, right
  /// away - if you switched devices you'll open the app, and a jump a few
  /// seconds into playback is worse than starting where you paused.
  Future<void> play({String? logDetail, bool fromUi = false}) async {
    _pauseRequested = false;
    // A second Play while the first is still moving the source onto a live
    // session raced it: it pressed play on a half-loaded player and ExoPlayer
    // failed with "Unexpected runtime error" (GH #344). The first one plays
    // when it's ready, so let it.
    final since = _playInFlightSince;
    if (since != null && DateTime.now().difference(since) < _playInFlightCap) {
      debugPrint(
        '[Service] play() ignored - the play from '
        '${DateTime.now().difference(since).inMilliseconds}ms ago is still getting ready',
      );
      return;
    }
    _playInFlightSince = DateTime.now();
    try {
      await _playNow(logDetail: logDetail, fromUi: fromUi);
    } finally {
      _playInFlightSince = null;
    }
  }

  DateTime? _playInFlightSince;
  static const _playInFlightCap = Duration(seconds: 30);

  Future<void> _playNow({String? logDetail, bool fromUi = false}) async {
    debugPrint(
      '[Service] play() called — lastPause=${_lastPauseTime != null} fromUi=$fromUi',
    );

    // Cold-start play guard. If the OS killed absorb during a long pause
    // and the user tapped play via headphones / lock screen / Android Auto,
    // the handler routes play() into this service before any UI code has
    // had a chance to restore the last-played item. _currentItemId is null
    // here, so falling through to _player.play() fires on an empty player
    // and nothing happens. Route through the cold-start callback instead.
    final prefs = _prefs ?? await SharedPreferences.getInstance();
    _prefs ??= prefs;
    final decision = ColdStartPlayPolicy.decide(
      currentItemId: _currentItemId,
      lastPlayedItemId: prefs.getString('widget_item_id'),
    );
    if (decision == ColdStartPlayDecision.restoreLastPlayed) {
      debugPrint(
        '[Service] play() on cold-started service - routing to cold-start restore',
      );
      // Android can start the process from the media resume card and send
      // play while the app is still starting up, before main() has wired the
      // restore handler. Wait for it rather than dropping the press.
      var restore = AudioPlayerService.onColdStartPlayRequested;
      for (var i = 0; restore == null && i < 50; i++) {
        await Future.delayed(const Duration(milliseconds: 200));
        restore = AudioPlayerService.onColdStartPlayRequested;
      }
      if (restore != null) {
        unawaited(restore());
      } else {
        debugPrint(
          '[Service] No cold-start restore handler registered after 10s - ignoring play',
        );
      }
      return;
    }
    if (decision == ColdStartPlayDecision.nothing) {
      debugPrint(
        '[Service] play() called with no current item and no history - ignoring',
      );
      return;
    }

    _pauseStopTimer?.cancel();
    _pauseStopTimer = null;
    // Playing again settles any interruption still waiting to resume; a stale
    // flag would bring the book back after some later, unrelated focus gain.
    _wasPlayingBeforeInterrupt = false;
    _noisyPause =
        false; // User explicitly resumed — allow interrupt-resume again
    _handler?._noisyPauseAt = null; // Clear noisy suppression window
    // A loadOnly playItem left the item paused with no session; this first
    // real play is where listening actually starts, so the session does too.
    final pendingSession = _pendingLoadOnlySession;
    if (pendingSession != null) {
      _pendingLoadOnlySession = null;
      if (_currentItemId == pendingSession.itemId) {
        await LocalSessionService().beginSession(
          progressKey: pendingSession.progressKey,
          libraryItemId: pendingSession.itemId,
          episodeId: pendingSession.episodeId,
          mediaType: pendingSession.episodeId != null ? 'podcast' : 'book',
          duration: pendingSession.duration,
          startTime: position.inMilliseconds / 1000.0,
          displayTitle: pendingSession.title,
          displayAuthor: pendingSession.author,
          streamed: pendingSession.streamed,
        );
        // The loadOnly playItem returned before _setupSync, so this session
        // has no completion listener, no position sync, no EQ attach and no
        // stats accrual yet. Without it a hot-loaded book that plays to the
        // end just sits there: completed arrives, nobody reacts, the card
        // stays until a manual stop and the book is never marked finished.
        _setupSync();
      }
    }
    // BookOrbit audio streams through the in-app proxy, which a long
    // suspension can take down; a lock screen play doesn't foreground the app.
    if (_api?.isBookOrbit == true) await _api!.ensureMediaReady();
    // A source streaming through a session the server no longer has (closed
    // by the pause timeout, or replaced since) would play from the cache
    // until that runs out, then die with a 404 and a five-second retry.
    // Nothing is audible yet, so this is the moment to move it.
    if (_sourceSessionDead) {
      await _rebuildSourceOnDeadSession(resumeAfter: false);
      if (_pauseRequested) {
        debugPrint('[Service] Paused while the source was being rebuilt - not starting');
        return;
      }
    }
    // Android: a player left paused past the pause timeout comes back with
    // the position moving and nothing audible, and only a rebuilt player
    // sounds again. One whose decoder failed while paused is rebuilt too.
    // Decided before any seek: seeking a player that is about to be replaced
    // is wasted, and on a failed decoder the seek can wait forever.
    final pausedFor = _lastPauseTime == null
        ? null
        : DateTime.now().difference(_lastPauseTime!);
    final longPause = pausedFor != null && pausedFor >= _pauseStopTimeout;
    bool canRebuild() =>
        _player?.processingState != ProcessingState.idle &&
        _currentItemId != null &&
        _api != null;
    String? rebuildWhy = _playerBroken
        ? 'Player failed while paused'
        : AppPlatform.isAndroid && longPause
            ? 'Long pause (${pausedFor.inSeconds}s)'
            : null;
    var rebuild = rebuildWhy != null && canRebuild();
    // Where the resume lands: the live player follows it when it is kept,
    // the rebuild starts there otherwise.
    var resumeAt = position.inMilliseconds / 1000.0;
    Future<void> moveTo(double s, [Future<void> Function()? seek]) async {
      resumeAt = s;
      if (rebuild) return;
      if (!await _resumeSeekFinished(seek ?? () => _seekAbsolute(s), s)) {
        rebuildWhy = 'Seek on resume never finished';
        rebuild = canRebuild();
      }
    }

    // A seek while paused (user, or the socket adopting another device's
    // position) is the position the user expects to hear next - don't let
    // the server check below override it.
    final seekedWhilePaused = _seekedWhilePaused;
    _seekedWhilePaused = false;
    final serverPos = fromUi && !seekedWhilePaused
        ? await _serverPositionBeforeResume()
        : null;
    final adoptedServerPos = serverPos != null;
    if (serverPos != null) {
      await moveTo(serverPos);
      _logEvent(
        PlaybackEventType.seek,
        detail: 'adopted server position ${serverPos.toStringAsFixed(1)}s before resume',
      );
    }
    // Coming back within a few minutes of the sleep timer firing means you were
    // awake for it, so put back what its rewind took. Done before the ordinary
    // auto-rewind below so that still applies from the restored position.
    // Moot when we just jumped to another device's position; consume the undo
    // anyway so it can't fire on a later resume.
    if (_player != null) {
      final undoTo = SleepTimerService().takeSleepRewindUndo(
          _currentItemId, Duration(milliseconds: (resumeAt * 1000).round()));
      if (undoTo != null && !adoptedServerPos) {
        await moveTo(undoTo.inMilliseconds / 1000.0,
            () => seekTo(undoTo, logDetail: 'sleep rewind undone'));
        // seekTo flags a paused seek; this one is ours, not the user's, and
        // the server check has already run, so don't carry it to next resume.
        _seekedWhilePaused = false;
      }
    }
    // Auto-rewind on resume if enabled
    if (_lastPauseTime != null && _player != null) {
      final settings = await AutoRewindSettings.load();
      if (settings.enabled) {
        final pauseDuration = DateTime.now().difference(_lastPauseTime!);
        final rewindSeconds = calculateAutoRewind(
          pauseDuration,
          settings.minRewind,
          settings.maxRewind,
          activationDelay: settings.activationDelay,
        );
        // A player sitting at zero has lost its place (an error reset it);
        // rewinding from there would only seek to the start on top of
        // whatever the server check just restored.
        if (rewindSeconds > 0.5 && resumeAt > 0) {
          final currentAbsolutePos = resumeAt;
          final currentSpeed = _player!.speed;
          var newPosSeconds =
              currentAbsolutePos - (rewindSeconds * currentSpeed);
          if (newPosSeconds < 0) newPosSeconds = 0;
          // Chapter barrier: don't rewind past the current chapter start
          if (settings.chapterBarrier && _chapters.isNotEmpty) {
            for (final ch in _chapters) {
              final start = (ch['start'] as num?)?.toDouble() ?? 0;
              final end = (ch['end'] as num?)?.toDouble() ?? 0;
              if (currentAbsolutePos >= start && currentAbsolutePos < end) {
                if (newPosSeconds < start) newPosSeconds = start;
                break;
              }
            }
          }
          await moveTo(newPosSeconds);
          // Log the actual book-time delta: at speed>1.0 it's larger than
          // rewindSeconds, and the chapter barrier may cap it smaller.
          final actualDelta = currentAbsolutePos - newPosSeconds;
          final rewindDetail = currentSpeed == 1.0
              ? '${rewindSeconds.toStringAsFixed(1)}s'
              : '${rewindSeconds.toStringAsFixed(1)}s (${actualDelta.toStringAsFixed(1)}s at ${currentSpeed.toStringAsFixed(2)}x)';
          _logEvent(PlaybackEventType.autoRewind, detail: rewindDetail);
          debugPrint(
            '[Player] Auto-rewind ${rewindSeconds.toStringAsFixed(1)}s '
            '(paused ${pauseDuration.inSeconds}s)',
          );
        }
      }
    }
    _lastPauseTime = null;
    // Reset server sync clock so the first sync after resume doesn't
    // include pause duration as timeListened
    _lastServerSync = DateTime.now();
    _lastAccrual = DateTime.now();
    _lastAccrualPos = null;
    // Re-activate audio session in case a prior stop released it. The answer
    // is the audio focus request: a refusal here on a resume from the
    // background is a lead when the book then plays without sound.
    try {
      final activated = await _setAudioSessionActive(true);
      debugPrint('[Player] Resume setActive(true)=$activated '
          '(paused ${pausedFor?.inSeconds ?? '?'}s)');
    } catch (e) {
      debugPrint('[Player] Resume setActive(true) failed: $e');
    }
    // Rebuild at the position the resume settled on, which already includes
    // the auto rewind, so nothing seeks once audio starts.
    if ((rebuild || _playerBroken) && canRebuild()) {
      final why = rebuildWhy ?? 'Player failed while paused';
      _playerBroken = false;
      // A position of zero means the player lost its place; the start then
      // comes from the saved progress instead of being forced to the top.
      final startS = resumeAt;
      debugPrint(
        '[Player] $why - rebuilding the player '
        '${startS > 0 ? "at ${startS.toStringAsFixed(1)}s" : "from the saved position"} '
        'instead of resuming it',
      );
      _logEvent(PlaybackEventType.play, detail: '$logDetail (rebuilt: $why)');
      unawaited(playItem(
        api: _api!,
        itemId: _currentItemId!,
        title: _currentTitle ?? '',
        author: _currentAuthor ?? '',
        coverUrl: _currentCoverUrl,
        totalDuration: _totalDuration,
        chapters: _chapters,
        startTime: startS,
        forceStartTime: startS > 0,
        episodeId: _currentEpisodeId,
        episodeTitle: _currentEpisodeTitle,
        libraryId: _currentLibraryId,
        fromUi: fromUi,
      ));
      return;
    }
    // If the player is idle (source was disposed), we need to fully re-initialize
    // playback instead of just calling play() on an empty player.
    if (_player?.processingState == ProcessingState.idle &&
        _currentItemId != null &&
        _api != null) {
      // Cap re-inits within a window so a book the engine can't start doesn't
      // spin here forever, hammering the server with fresh play sessions.
      final now = DateTime.now();
      if (_lastIdleReinit != null &&
          now.difference(_lastIdleReinit!) < _idleReinitWindow) {
        _idleReinitCount++;
      } else {
        _idleReinitCount = 1;
      }
      _lastIdleReinit = now;
      if (_idleReinitCount > _idleReinitMaxAttempts) {
        debugPrint(
          '[Player] Idle-on-resume re-init capped after $_idleReinitCount attempts — giving up to avoid a retry storm',
        );
        return;
      }
      debugPrint(
        '[Player] Player is idle on resume - re-initializing playback for $_currentItemId (attempt $_idleReinitCount)',
      );
      playItem(
        api: _api!,
        itemId: _currentItemId!,
        title: _currentTitle ?? '',
        author: _currentAuthor ?? '',
        coverUrl: _currentCoverUrl,
        totalDuration: _totalDuration,
        chapters: _chapters,
        episodeId: _currentEpisodeId,
        episodeTitle: _currentEpisodeTitle,
        libraryId: _currentLibraryId,
        fromUi: fromUi,
      );
      return;
    }
    // Restart the listening-time clock so the paused span isn't counted as
    // listening on the first sync tick after resume (a long/overnight pause
    // would otherwise be credited as up to 300s of phantom listening).
    _lastServerSync = DateTime.now();
    _lastAccrual = DateTime.now();
    _lastAccrualPos = null;
    // Start playback immediately — don't wait for server calls
    _player?.play();
    // Any paused seek up to this instant belonged to this resume (a socket
    // adoption can land between the check above and here); the flag is for
    // seeks during the NEXT pause.
    _seekedWhilePaused = false;
    _scheduleAudioDiagnostics('resume');
    _logEvent(PlaybackEventType.play, detail: logDetail);
    _onPlaybackStateChangedCallback?.call(true);
    final resumed = _currentItemId;
    if (fromUi && resumed != null && _currentEpisodeId == null) onAppPlay?.call(resumed);
    // Re-create server session and check progress in the background
    // so resume is instant instead of waiting for network round-trips
    _resumeServerSync();

    // Restart safety-net save timer (stopped on pause to avoid background wakes)
    if (_bgSaveTimer == null || !_bgSaveTimer!.isActive) {
      _bgSaveTimer?.cancel();
      _bgSaveTimer = Timer.periodic(const Duration(seconds: 300), (_) async {
        if (_currentItemId == null || _player == null || !_player!.playing)
          return;
        final pos = position;
        final posSec = pos.inMilliseconds / 1000.0;
        if (posSec <= 0) return;
        await _saveProgressLocal(pos);
        // Backstop accrual for a frozen position stream (Doze); shares
        // _lastAccrual so it never double-counts live ticks.
        await _accrueListening(pos);
      });
    }
    // Restart stuck detection (stopped on pause to avoid background wakes)
    if (_stuckCheckTimer == null || !_stuckCheckTimer!.isActive) {
      _startStuckDetection();
    }
    // Verify playback actually started — iOS USAC decoder can silently fail
    // after a seek, leaving the player in a non-playing state with no errors.
    _schedulePlayVerify();
    // Check auto sleep on every resume — catches window entry between pauses
    SleepTimerService().checkAutoSleep();
    notifyListeners();
  }

  /// Pause long enough that another device could plausibly have listened
  /// meanwhile. Shorter pauses resume instantly with no server round trip.
  static const _serverPositionCheckMinPause = Duration(minutes: 2);

  /// Longest an app-screen resume waits on the server before starting where
  /// the phone left off. A late answer is dropped, never seeked to.
  static const _serverPositionCheckCap = Duration(seconds: 2);

  /// Resume seeks on a player whose decoder died while paused can wait
  /// forever, which held play() - and every tap after it - for the whole
  /// in-flight cap. On Android, a plain seek that hasn't finished within
  /// [_resumeSeekCap] marks the player broken and the resume rebuilds it.
  /// A pending source swap is left to finish, however long it takes.
  static const _resumeSeekCap = Duration(seconds: 3);

  Future<bool> _resumeSeekFinished(Future<void> Function() seek, double target) async {
    if (!AppPlatform.isAndroid ||
        _pendingLocalSwapKey != null ||
        _pendingSessionUpgrade != null) {
      await seek();
      return true;
    }
    try {
      await seek().timeout(_resumeSeekCap);
      return true;
    } on TimeoutException {
      debugPrint(
        '[Player] Seek to ${target.toStringAsFixed(1)}s on resume did not finish '
        'within ${_resumeSeekCap.inSeconds}s - treating the player as broken',
      );
      _playerBroken = true;
      return false;
    }
  }

  /// Before an app-screen resume, look at the server's saved progress and,
  /// if another device genuinely moved it ahead, return that position for
  /// the resume to start at; null keeps the phone's. Runs only before audio,
  /// capped, and only after a pause long enough to matter; anything slower
  /// starts local.
  Future<double?> _serverPositionBeforeResume() async {
    if (_api == null || _currentItemId == null || _player == null) return null;
    // An idle player is about to be re-initialised through playItem, which
    // reconciles the start position itself.
    if (_player!.processingState == ProcessingState.idle) return null;
    if (_knownOffline || _isOfflineMode) return null;
    if (ChromecastService().isCasting) return null;
    final lastPause = _lastPauseTime;
    // BookOrbit has no live progress push to cover a short pause, so check
    // after any pause long enough for someone to have listened elsewhere.
    final minPause = _api!.isBookOrbit
        ? const Duration(seconds: 10)
        : _serverPositionCheckMinPause;
    if (lastPause == null || DateTime.now().difference(lastPause) < minPause) {
      return null;
    }
    final manualOffline =
        (_prefs ?? await SharedPreferences.getInstance()).getBool(
          'manual_offline_mode',
        ) ??
        false;
    if (manualOffline) return null;
    final pKey = _currentEpisodeId != null
        ? '$_currentItemId-$_currentEpisodeId'
        : _currentItemId!;
    try {
      final localTs = await _progressSync.getSavedTimestamp(pKey);
      final serverProgress = await _api!
          .getItemProgress(pKey)
          .timeout(_serverPositionCheckCap, onTimeout: () => null);
      if (serverProgress == null) {
        debugPrint(
          '[Player] Resume server-check (pre-start): no answer within ${_serverPositionCheckCap.inMilliseconds}ms - starting local',
        );
        return null;
      }
      final serverPos = (serverProgress['currentTime'] as num?)?.toDouble() ?? 0;
      final serverTs = (serverProgress['lastUpdate'] as num?)?.toInt() ?? 0;
      final localPos = position.inMilliseconds / 1000.0;
      // Timestamp gate, like the sync path: our own pre-rewind position still
      // sits on the server after a resume, so position alone would call every
      // auto-rewind "server ahead".
      final ahead = serverTs > localTs && serverPos > localPos + 5.0;
      debugPrint(
        '[Player] Resume server-check (pre-start): server=${serverPos}s(ts=$serverTs) vs local=${localPos}s(ts=$localTs) -> ${ahead ? "SEEKING" : "keep local"}',
      );
      return ahead ? serverPos : null;
    } catch (e) {
      debugPrint('[Player] Resume server-check (pre-start) failed: $e');
      return null;
    }
  }

  /// The server session the playing source streams through, read off its
  /// URLs. Null for tokened item URLs and local files.
  String? get _sourceSessionId {
    if (_activeStreamUrls.isEmpty) return null;
    final m = RegExp(r'/public/session/([^/]+)/')
        .firstMatch(_activeStreamUrls.first);
    return m?.group(1);
  }

  /// A session URL stops working the moment the server closes the session:
  /// its public track route serves open sessions only, and Audiobookshelf
  /// closes any other open session from the same device when a new one
  /// starts. So a source is dead once its session is no longer the one we
  /// hold - closed by the pause timeout, or replaced. Playback carries on
  /// from the cache until that runs out, then a 404 and a five-second retry.
  bool get _sourceSessionDead {
    if (_localSessionMode) return false;
    final sid = _sourceSessionId;
    return sid != null && sid != _playbackSessionId;
  }

  /// Move a source that streams through a dead session onto a live one.
  /// Starts a session when we hold none; a held one is adopted through the
  /// pending upgrade. Returns whether the source was rebuilt.
  Future<bool> _rebuildSourceOnDeadSession({required bool resumeAfter}) async {
    if (_api == null || _currentItemId == null || _localSessionMode) {
      return false;
    }
    // A finished download takes the rebuild: no new session, no network.
    if (await _applyPendingLocalSwap(resumeAfter: resumeAfter)) return true;
    if (_isOfflineMode || _knownOffline || ChromecastService().isCasting) {
      return false;
    }
    final manualOffline =
        (_prefs ?? await SharedPreferences.getInstance()).getBool(
          'manual_offline_mode',
        ) ??
        false;
    if (manualOffline) return false;
    final pending = _pendingSessionUpgrade;
    if (pending == null || pending['id'] != _playbackSessionId) {
      if (_recreatingSession) return false;
      _recreatingSession = true;
      try {
        final sessionData = _currentEpisodeId != null
            ? await _api!.startEpisodePlaybackSession(
                _currentItemId!,
                _currentEpisodeId!,
              )
            : await _api!.startPlaybackSession(_currentItemId!);
        if (sessionData == null) return false;
        _playbackSessionId = sessionData['id'] as String?;
        _logEvent(PlaybackEventType.sessionStart, detail: 'dead source');
        _stashSessionUpgrade(sessionData);
      } catch (e) {
        debugPrint('[Player] Session start for a dead source failed: $e');
        return false;
      } finally {
        _recreatingSession = false;
      }
    }
    final swapped = await _applyPendingSessionUpgrade(resumeAfter: resumeAfter);
    debugPrint(
      '[Player] Source was on a closed session - '
      '${swapped ? 'rebuilt on ${_playbackSessionId?.substring(0, 8)}' : 'rebuild failed, keeping it'}',
    );
    return swapped;
  }

  /// Progress-endpoint sync for a tick whose session sync could not be used.
  Future<void> _syncProgressWithoutSession(Duration pos) async {
    if (_api == null || _currentItemId == null) return;
    final key = _currentEpisodeId != null
        ? '$_currentItemId-$_currentEpisodeId'
        : _currentItemId!;
    try {
      await _saveProgressLocal(pos);
      final ok = await _progressSync.syncToServer(api: _api!, itemId: key);
      debugPrint(
        '[Player] Direct progress sync ${ok ? 'succeeded' : 'returned false'}',
      );
    } catch (e) {
      debugPrint('[Player] Direct progress sync error: $e');
    }
  }

  /// Re-create the server session after a pause long enough to have closed
  /// it. Runs in the background so play() returns instantly. Position is not
  /// touched here: once audio is running we never seek it out from under the
  /// listener (see play()).
  void _resumeServerSync() async {
    if (_api == null || _currentItemId == null) return;
    if (_recreatingSession) return;
    if (_playbackSessionId != null) return;
    final manualOffline =
        (_prefs ?? await SharedPreferences.getInstance()).getBool(
          'manual_offline_mode',
        ) ??
        false;
    if (manualOffline || _isOfflineMode || _localSessionMode) {
      debugPrint(
        '[Player] Skipping session re-create on resume (manualOffline=$manualOffline, isOffline=$_isOfflineMode, localSession=$_localSessionMode)',
      );
      return;
    }
    _recreatingSession = true;
    try {
      final sessionData = _currentEpisodeId != null
          ? await _api!.startEpisodePlaybackSession(
              _currentItemId!,
              _currentEpisodeId!,
            )
          : await _api!.startPlaybackSession(_currentItemId!);
      if (sessionData != null) {
        _playbackSessionId = sessionData['id'] as String?;
        debugPrint(
          '[Player] Re-created session on resume: $_playbackSessionId',
        );
        _stashSessionUpgrade(sessionData);
      }
    } catch (e) {
      debugPrint('[Player] Failed to re-create session on resume: $e');
    } finally {
      _recreatingSession = false;
    }
  }

  Future<void> pause() async {
    _markPauseRequested();
    debugPrint('[Service] pause() called');
    _playVerifyTimer?.cancel();
    _wasPlayingBeforeInterrupt = false;
    _lastPauseTime = DateTime.now();
    // Stamp BT-route observation for AA-disconnect phantom-click detection.
    // Fire-and-forget: pause shouldn't block on a native call.
    unawaited(
      _isBluetoothAudioConnected().then((bt) {
        if (bt) _lastPlayedOnBtAt = DateTime.now();
      }),
    );
    // Stop timers to avoid background wakes while paused
    if (_bgSaveTimer != null) {
      _bgSaveTimer!.cancel();
      _bgSaveTimer = null;
    }
    if (_stuckCheckTimer != null) {
      _stuckCheckTimer!.cancel();
      _stuckCheckTimer = null;
    }
    await _player?.pause();
    _logEvent(PlaybackEventType.pause);
    _onPlaybackStateChangedCallback?.call(false);

    notifyListeners();
    final pos = position;
    debugPrint(
      '[Player] Saving on pause: ${(pos.inMilliseconds / 1000.0).toStringAsFixed(1)}s',
    );
    await _saveProgressLocal(pos);

    // Check manual offline before syncing
    final manualOffline =
        (_prefs ?? await SharedPreferences.getInstance()).getBool(
          'manual_offline_mode',
        ) ??
        false;

    // Credit listening right up to the pause for whatever mode is active — we
    // were playing until now — then let the push below ship it. resume (play())
    // restarts both clocks so the paused span is never counted. Runs even under
    // manual offline since accrual works offline.
    await _accrueListening(pos);
    if (_localSessionMode) {
      final online = !manualOffline && !_isOfflineMode && _api != null;
      if (online) unawaited(LocalSessionService().pushActive(api: _api!));
      _lastServerSync = DateTime.now();
      _lastAccrual = DateTime.now();
    }

    if (manualOffline) return;

    if (!_isOfflineMode && _playbackSessionId != null) {
      await _syncToServer(pos);
    } else if (!_isOfflineMode && _currentItemId != null && _api != null) {
      final syncKey = _currentEpisodeId != null
          ? '$_currentItemId-$_currentEpisodeId'
          : _currentItemId!;
      _progressSync.syncToServer(api: _api!, itemId: syncKey);
    }

    // Paused audio is the other free moment to adopt a waiting session's
    // tokenless URLs - the rebuild is inaudible and playback resumes on a
    // source that can't hit token expiry.
    // A finished download goes first - once on the files the session's URLs
    // no longer matter.
    if (_pendingLocalSwapKey != null) {
      final swap = _pauseSwap = _applyPendingLocalSwap(resumeAfter: false);
      unawaited(swap);
    } else if (_pendingSessionUpgrade != null) {
      final swap = _pauseSwap = _applyPendingSessionUpgrade(resumeAfter: false);
      unawaited(swap);
    }

    // After 10 min paused, close the server session so we don't inflate
    // listening stats with paused time. We deliberately keep the AudioSession
    // active and the player paused (not stopped) so the foreground service
    // stays in foreground state and the MediaSession stays alive - this is
    // what keeps notification / lock screen / Bluetooth / WearOS controls
    // responsive after a long pause. Same pattern as Spotify and Pocket Casts.
    _pauseStopTimer?.cancel();
    _pauseStopTimer = Timer(_pauseStopTimeout, () async {
      debugPrint('[Player] Pause timeout - releasing server session');
      // Close server playback session. timeListened=0 because the user has
      // been paused for the whole pause-timeout window - the wall-clock diff
      // would otherwise inflate server listening stats by up to 300s.
      if (_playbackSessionId != null && _api != null) {
        _logEvent(PlaybackEventType.sessionEnd, detail: 'pause timeout');
        try {
          await _syncToServer(position, timeListenedOverride: 0);
          debugPrint('[Player] Closing session (pause timeout)');
          await _api!.closePlaybackSession(_playbackSessionId!);
        } catch (_) {}
        _playbackSessionId = null;
      }
      // Cancel sleep timer
      if (SleepTimerService().isActive) {
        SleepTimerService().cancel();
      }
    });
  }

  Future<void> togglePlayPause({bool fromUi = false}) async {
    debugPrint('[Service] togglePlayPause() — isPlaying=$isPlaying');
    if (isPlaying) {
      await pause();
    } else {
      await play(fromUi: fromUi);
    }
  }

  Future<void> seekTo(
    Duration pos, {
    PlaybackEventType logAs = PlaybackEventType.seek,
    String? logDetail,
  }) async {
    // While this item is casting, the Chromecast is the real player - route
    // the seek there too or bookmark/chapter jumps only move the stopped
    // local player (GH #273).
    final cast = ChromecastService();
    if (cast.isCasting &&
        _currentItemId != null &&
        cast.castingItemId == _currentItemId &&
        cast.castingEpisodeId == _currentEpisodeId) {
      await cast.seekTo(pos);
    }
    _resetStuckDetection();
    if (_player != null && !_player!.playing) _seekedWhilePaused = true;
    final from = position;
    await _seekAbsolute(pos.inMilliseconds / 1000.0);
    _logEvent(
      logAs,
      detail: logDetail ?? '${_formatPos(from)} → ${_formatPos(pos)}',
      overridePosition: from.inMilliseconds / 1000.0,
    );
    notifyListeners();
  }

  /// Rewind triggered by the sleep timer firing. Same mechanics as a manual
  /// seek-back, but logged as an auto-rewind so the playback history reads
  /// "Auto-rewound 15m (sleep timer)" instead of a raw seek (GH #232).
  Future<void> sleepTimerRewind(int seconds) async {
    if (seconds <= 0) return;
    var target = position - Duration(seconds: seconds);
    if (target < Duration.zero) target = Duration.zero;
    final amount = seconds % 60 == 0 ? '${seconds ~/ 60}m' : '${seconds}s';
    await seekTo(
      target,
      logAs: PlaybackEventType.autoRewind,
      logDetail: '$amount (sleep timer)',
    );
    // Pausing for sleep already saved and sent the spot from before the
    // rewind, so a restart or another device went back there (GH #433).
    debugPrint('[SleepTimer] Saving the rewound spot: ${(target.inMilliseconds / 1000.0).toStringAsFixed(1)}s');
    await _saveProgressLocal(target);
    final manualOffline =
        (_prefs ?? await SharedPreferences.getInstance()).getBool('manual_offline_mode') ?? false;
    if (manualOffline || _isOfflineMode) return;
    if (_playbackSessionId != null) {
      await _syncToServer(target, timeListenedOverride: 0);
    } else if (_currentItemId != null && _api != null) {
      final syncKey = _currentEpisodeId != null ? '$_currentItemId-$_currentEpisodeId' : _currentItemId!;
      _progressSync.syncToServer(api: _api!, itemId: syncKey);
    }
  }

  Future<void> skipForward([int seconds = 30]) async {
    if (_player == null) return;
    _resetStuckDetection();
    if (!_player!.playing) _seekedWhilePaused = true;
    // Multiply by speed so the skip feels like the configured amount of real time
    final adjusted = (seconds * speed).round();
    debugPrint(
      '[Service] skipForward(${seconds}s × ${speed}x = ${adjusted}s) — playing=${_player!.playing}',
    );
    final newPos = position + Duration(seconds: adjusted);
    await _seekAbsolute(newPos.inMilliseconds / 1000.0);
    _logEvent(
      PlaybackEventType.skipForward,
      detail: '+${seconds}s (${adjusted}s @ ${speed}x)',
    );
    debugPrint('[Service] skipForward done — playing=${_player!.playing}');
  }

  DateTime? _lastRewindChapterSnap;

  Future<void> skipBackward([int seconds = 10]) async {
    if (_player == null) return;
    _resetStuckDetection();
    if (!_player!.playing) _seekedWhilePaused = true;
    // Multiply by speed so the skip feels like the configured amount of real time
    final adjusted = (seconds * speed).round();
    final posS = position.inMilliseconds / 1000.0;
    final targetS = posS - adjusted;

    // Find current chapter start (gated by setting)
    final chapterBarrier = await PlayerSettings.getSkipChapterBarrier();
    if (chapterBarrier && _chapters.isNotEmpty) {
      double chapterStart = 0;
      for (int i = _chapters.length - 1; i >= 0; i--) {
        final s = (_chapters[i]['start'] as num?)?.toDouble() ?? 0;
        if (s <= posS + 0.5) {
          chapterStart = s;
          break;
        }
      }

      final intoChapter = posS - chapterStart;
      // If the rewind would cross the chapter boundary
      if (targetS < chapterStart && intoChapter > 0.5) {
        final now = DateTime.now();
        final recentSnap =
            _lastRewindChapterSnap != null &&
            now.difference(_lastRewindChapterSnap!).inMilliseconds < 2000;
        if (!recentSnap) {
          // Snap to chapter start instead of crossing
          _lastRewindChapterSnap = now;
          await _seekAbsolute(chapterStart);
          _logEvent(
            PlaybackEventType.skipBackward,
            detail: 'snap to chapter start',
          );
          return;
        }
        // Double-tap within 2s - break through the barrier
        _lastRewindChapterSnap = null;
      }
    }

    var n = targetS < 0 ? 0.0 : targetS;
    await _seekAbsolute(n);
    _logEvent(
      PlaybackEventType.skipBackward,
      detail: '-${seconds}s (${adjusted}s @ ${speed}x)',
    );
  }

  Future<void> skipToNextChapter() async {
    if (_player == null || _chapters.isEmpty) return;
    _resetStuckDetection();
    if (!_player!.playing) _seekedWhilePaused = true;
    final posS = position.inMilliseconds / 1000.0;
    final target = ChapterLookup.nextSkipTarget(
      _chapters,
      posS,
      _totalDuration,
    );
    if (target == null) return;
    if (target.finishesItem) {
      debugPrint('[Service] skipToNextChapter → end at ${target.seconds}s');
      _lastKnownPositionSec = target.seconds;
      _logEvent(PlaybackEventType.seek, detail: 'next chapter to end');
      await _onPlaybackComplete(userRequested: true);
      return;
    }
    debugPrint('[Service] skipToNextChapter → ${target.seconds}s');
    await _seekAbsolute(target.seconds);
    _logEvent(PlaybackEventType.seek, detail: 'next chapter');
    notifyListeners();
  }

  Future<void> skipToPreviousChapter() async {
    if (_player == null || _chapters.isEmpty) return;
    _resetStuckDetection();
    if (!_player!.playing) _seekedWhilePaused = true;
    final posS = position.inMilliseconds / 1000.0;
    // If more than 3s into current chapter, go to start of current chapter
    // Otherwise go to previous chapter
    for (int i = _chapters.length - 1; i >= 0; i--) {
      final start = (_chapters[i]['start'] as num?)?.toDouble() ?? 0;
      if (start < posS - 3.0) {
        debugPrint('[Service] skipToPreviousChapter → chapter $i at ${start}s');
        await _seekAbsolute(start);
        _logEvent(PlaybackEventType.seek, detail: 'prev chapter');
        notifyListeners();
        return;
      }
    }
    // If at the very start, seek to 0
    await _seekAbsolute(0);
    notifyListeners();
  }

  Future<void> setSpeed(double s) async {
    if (_player == null) return;
    debugPrint('[Service] setSpeed(${s}x) — before: ${_player!.speed}x');
    await _player!.setSpeed(s);
    debugPrint('[Service] setSpeed done — after: ${_player!.speed}x');
    _logEvent(
      PlaybackEventType.speedChange,
      detail: '${s.toStringAsFixed(2)}x',
    );
    if (_currentItemId != null) {
      PlayerSettings.setBookSpeed(_currentItemId!, s);
      // Re-push MediaItem so the notification/AA duration updates for the
      // new speed (duration is divided by speed for speed-adjusted time).
      if (_handler != null) {
        final chTitle = currentChapter?['title'] as String?;
        _pushMediaItem(
          _mediaItemKey,
          _currentTitle ?? '',
          _currentAuthor ?? '',
          _currentCoverUrl,
          _totalDuration,
          chapter: chTitle,
        );
      }
    }
    // Refresh the PlaybackState so Android Auto's speed badge tracks the rate.
    _handler?.refreshPlaybackState();
    notifyListeners();
  }

  Map<String, dynamic>? get currentChapter {
    if (_chapters.isEmpty || _player == null) return null;
    final pos = position.inMilliseconds / 1000.0; // absolute book position
    for (final ch in _chapters) {
      final start = (ch['start'] as num?)?.toDouble() ?? 0;
      final end = (ch['end'] as num?)?.toDouble() ?? _totalDuration;
      if (pos >= start && pos < end) return ch as Map<String, dynamic>;
    }
    return null;
  }

  Future<void> stop({bool keepSleepTimer = false}) async {
    _pauseStopTimer?.cancel();
    _pauseStopTimer = null;
    _endAdvanceBuffering();
    final wasPlaying = _player?.playing ?? false;
    // Save final position locally
    if (_currentItemId != null) {
      final pos = position;
      debugPrint(
        '[Player] Saving on stop: ${(pos.inMilliseconds / 1000.0).toStringAsFixed(1)}s',
      );
      await _saveProgressLocal(pos);
      // Credit the final playing tail before the push/close below. Skipped when
      // stopped from a paused state so the idle span isn't counted.
      if (wasPlaying) await _accrueListening(pos);
    }

    // Check manual offline before syncing
    final manualOffline =
        (_prefs ?? await SharedPreferences.getInstance()).getBool(
          'manual_offline_mode',
        ) ??
        false;

    if (!manualOffline) {
      // Try server sync. If stop() was called while already paused, we were
      // not playing in the interval since the last sync - pass timeListened=0
      // so the wall-clock diff doesn't inflate server listening stats.
      if (_playbackSessionId != null && _api != null) {
        _logEvent(PlaybackEventType.sessionEnd, detail: 'stop');
        await _syncToServer(
          position,
          timeListenedOverride: wasPlaying ? null : 0,
        );
        try {
          debugPrint('[Player] Closing session (stop)');
          await _api!.closePlaybackSession(_playbackSessionId!);
        } catch (_) {}
      } else if (_currentItemId != null && _api != null) {
        await _progressSync.syncToServer(api: _api!, itemId: _currentItemId!);
      }
    }

    // Local-session play: push the final accrued listening, then finalize.
    // Runs even under manual offline so the session is queued for replay.
    if (_localSessionMode) {
      bool pushed = false;
      if (!manualOffline && _api != null) {
        pushed = await LocalSessionService().pushActive(api: _api!);
      }
      await LocalSessionService().finalizeActive(pushed: pushed);
    }

    await _player?.stop();
    _onPlaybackStateChangedCallback?.call(false);

    _clearState();
    _chapters = [];
    _handler?.updateChaptersQueue(const []);
    // Cancel sleep timer when playback is stopped - unless the caller is
    // handing off to Chromecast, where an armed timer should keep running
    // against the cast session rather than vanish (GH #338).
    if (!keepSleepTimer && SleepTimerService().isActive) {
      SleepTimerService().cancel();
    }
    // Release audio focus so other apps can use it - but not during casting,
    // because deactivating the session can interfere with cast playback.
    if (!ChromecastService().isCasting) {
      debugPrint('[Battery] AudioSession DEACTIVATED (stop)');
      try {
        await _setAudioSessionActive(false);
      } catch (_) {}
    }
  }

  /// Stop playback without saving progress — used by reset progress.
  Future<void> stopWithoutSaving() async {
    _endAdvanceBuffering();
    // Close server session without syncing position
    if (_playbackSessionId != null && _api != null) {
      try {
        debugPrint('[Player] Closing session (reset progress)');
        await _api!.closePlaybackSession(_playbackSessionId!);
      } catch (_) {}
    }
    // Local-session play: queue the accrued listening for replay (the user did
    // listen; resetting position shouldn't erase that).
    if (_localSessionMode) {
      await LocalSessionService().finalizeActive();
    }
    await _player?.stop();
    _clearState();
    _chapters = [];
    _handler?.updateChaptersQueue(const []);
  }

  @override
  void dispose() {
    _endAdvanceBuffering();
    _syncSub?.cancel();
    _bgSaveTimer?.cancel();
    _pauseStopTimer?.cancel();
    _stuckCheckTimer?.cancel();
    _playVerifyTimer?.cancel();
    _indexSub?.cancel();
    _audioServiceErrorSub?.cancel();
    _player?.dispose();
    super.dispose();
  }
}