A cross platform Audiobookshelf client for Android and iOS
Dart
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();
}
}