Skip to content

A cross platform Audiobookshelf client for Android and iOS

Dart

Fix iOS background queue, attempt 11 - native replaceCurrentItem handover

Barnabas766c6e73f226
diff --git a/ios/Runner/IOSQueueAdvancer.swift b/ios/Runner/IOSQueueAdvancer.swift
index 7397c0c1..c8e75b58 100644
--- a/ios/Runner/IOSQueueAdvancer.swift
+++ b/ios/Runner/IOSQueueAdvancer.swift
@@ -4,14 +4,11 @@ import Foundation
import MediaPlayer
import UIKit
-/// Handles the cross-book audio transition when queue mode advances on iOS.
-///
-/// AVQueuePlayer auto-advance can leave the player rate at >0 with currentTime
-/// advancing but no audio reaching the output route when the screen is locked.
-/// This class forces the engine to restart on its own AVQueuePlayer (the one
-/// just_audio created) by pausing and re-applying the rate, and updates the
-/// lock screen Now Playing info from native code in the same moment so iOS
-/// keeps showing controls during the swap.
+/// Drives the cross-book audio transition in queue mode. Builds a fresh
+/// AVPlayerItem for the next book and swaps it into the AVQueuePlayer that
+/// just_audio owns via replaceCurrentItem + explicit play + rate. Updates
+/// MPNowPlayingInfoCenter from Swift so the lock screen never blanks out
+/// during the swap.
final class IOSQueueAdvancer: NSObject {
static let shared = IOSQueueAdvancer()
@@ -22,10 +19,14 @@ final class IOSQueueAdvancer: NSObject {
private weak var _justAudioPlayer: AVQueuePlayer?
private var _justAudioPlayerId: String?
- private var _nextTitle: String = ""
- private var _nextArtist: String = ""
- private var _nextDurationS: Double = 0
- private var _nextCoverPath: String?
+ private var _preparedItem: AVPlayerItem?
+ private var _preparedTitle: String = ""
+ private var _preparedArtist: String = ""
+ private var _preparedDurationS: Double = 0
+ private var _preparedCoverPath: String?
+ private var _preparedStartS: Double = 0
+
+ private var _flutterChannel: FlutterMethodChannel?
private override init() {
super.init()
@@ -66,6 +67,7 @@ final class IOSQueueAdvancer: NSObject {
channel.setMethodCallHandler { [weak self] call, result in
self?.handle(call, result: result)
}
+ _flutterChannel = channel
emit("[QueueAdvancer] channel registered")
}
@@ -73,70 +75,158 @@ final class IOSQueueAdvancer: NSObject {
let args = call.arguments as? [String: Any]
switch call.method {
case "prepareNext":
+ let url = (args?["url"] as? String) ?? ""
+ let isLocal = (args?["isLocal"] as? Bool) ?? false
+ let headers = (args?["headers"] as? [String: String]) ?? [:]
let title = (args?["title"] as? String) ?? ""
let artist = (args?["artist"] as? String) ?? ""
let duration = (args?["durationS"] as? Double) ?? 0
let coverPath = args?["coverPath"] as? String
- queue.async { [weak self] in
- self?._nextTitle = title
- self?._nextArtist = artist
- self?._nextDurationS = duration
- self?._nextCoverPath = coverPath
- self?.emit("[QueueAdvancer] prepared metadata for \(title)")
- }
- result(true)
+ let startS = (args?["startS"] as? Double) ?? 0
+ prepareNext(
+ urlStr: url,
+ isLocal: isLocal,
+ headers: headers,
+ title: title,
+ artist: artist,
+ durationS: duration,
+ coverPath: coverPath,
+ startS: startS,
+ completion: { ok in result(ok) }
+ )
case "commitAdvance":
let speed = (args?["speed"] as? Double) ?? 1.0
commitAdvance(speed: speed, completion: { ok in result(ok) })
case "clear":
- queue.async { [weak self] in
- self?._nextTitle = ""
- self?._nextArtist = ""
- self?._nextDurationS = 0
- self?._nextCoverPath = nil
- }
+ queue.async { [weak self] in self?.dropPrepared() }
result(true)
case "isReady":
result(_justAudioPlayer != nil)
+ case "isPrepared":
+ result(_preparedItem != nil)
+
default:
result(FlutterMethodNotImplemented)
}
}
+ private func prepareNext(
+ urlStr: String,
+ isLocal: Bool,
+ headers: [String: String],
+ title: String,
+ artist: String,
+ durationS: Double,
+ coverPath: String?,
+ startS: Double,
+ completion: @escaping (Bool) -> Void
+ ) {
+ queue.async { [weak self] in
+ guard let self = self else { completion(false); return }
+ guard !urlStr.isEmpty else {
+ self.emit("[QueueAdvancer] prepareNext: empty url")
+ completion(false)
+ return
+ }
+ let url: URL?
+ if isLocal {
+ let path = urlStr.hasPrefix("file://") ? String(urlStr.dropFirst(7)) : urlStr
+ url = URL(fileURLWithPath: path)
+ } else {
+ url = URL(string: urlStr)
+ }
+ guard let assetUrl = url else {
+ self.emit("[QueueAdvancer] prepareNext: bad url \(urlStr)")
+ completion(false)
+ return
+ }
+
+ var options: [String: Any] = [:]
+ if !headers.isEmpty {
+ options["AVURLAssetHTTPHeaderFieldsKey"] = headers
+ }
+ let asset = AVURLAsset(url: assetUrl, options: options)
+ asset.loadValuesAsynchronously(forKeys: ["tracks", "duration"]) { [weak self] in
+ guard let self = self else { return }
+ self.queue.async {
+ var trackErr: NSError?
+ let status = asset.statusOfValue(forKey: "tracks", error: &trackErr)
+ if status != .loaded {
+ self.emit("[QueueAdvancer] prepareNext: asset tracks not loaded status=\(status.rawValue) err=\(trackErr?.localizedDescription ?? "nil")")
+ completion(false)
+ return
+ }
+ let item = AVPlayerItem(asset: asset)
+ item.audioTimePitchAlgorithm = .timeDomain
+ self._preparedItem = item
+ self._preparedTitle = title
+ self._preparedArtist = artist
+ self._preparedDurationS = durationS
+ self._preparedCoverPath = coverPath
+ self._preparedStartS = startS
+ self.emit("[QueueAdvancer] prepared \(title) (\(assetUrl.lastPathComponent)) start=\(startS)")
+ completion(true)
+ }
+ }
+ }
+ }
+
private func commitAdvance(speed: Double, completion: @escaping (Bool) -> Void) {
queue.async { [weak self] in
guard let self = self else { completion(false); return }
- self.activateSession()
- self.publishNowPlaying(rate: speed)
guard let player = self._justAudioPlayer else {
self.emit("[QueueAdvancer] commitAdvance: no just_audio player ref")
completion(false)
return
}
+ guard let item = self._preparedItem else {
+ self.emit("[QueueAdvancer] commitAdvance: nothing prepared")
+ completion(false)
+ return
+ }
+
+ self.activateSession()
+ self.publishNowPlaying(rate: speed)
+
let target = Float(speed > 0 ? speed : 1.0)
+ let startS = self._preparedStartS
DispatchQueue.main.async {
- // Force the engine to re-emit audio: pause, then play and re-apply
- // the rate explicitly. This is what manual pause+play does for users.
- player.pause()
- DispatchQueue.main.asyncAfter(deadline: .now() + 0.04) {
+ // Clear other queued items so a stale auto-advance can't race us.
+ for queued in player.items() where queued !== item {
+ player.remove(queued)
+ }
+ player.replaceCurrentItem(with: item)
+ if startS > 0 {
+ item.seek(to: CMTime(seconds: startS, preferredTimescale: 1000), completionHandler: { _ in
+ player.play()
+ player.rate = target
+ })
+ } else {
player.play()
player.rate = target
- self.queue.async {
- self.emit("[QueueAdvancer] commitAdvance done rate=\(player.rate) for \(self._nextTitle)")
- // Re-publish Now Playing once the engine settles so the lock
- // screen shows the correct playing state and elapsed time.
- self.publishNowPlaying(rate: Double(target))
- completion(true)
- }
+ }
+ self.queue.async {
+ self.emit("[QueueAdvancer] commitAdvance done rate=\(player.rate) item=\(self._preparedTitle)")
+ self._preparedItem = nil
+ completion(true)
}
}
}
}
+ private func dropPrepared() {
+ _preparedItem = nil
+ _preparedTitle = ""
+ _preparedArtist = ""
+ _preparedDurationS = 0
+ _preparedCoverPath = nil
+ _preparedStartS = 0
+ }
+
private func activateSession() {
let session = AVAudioSession.sharedInstance()
do {
@@ -150,16 +240,17 @@ final class IOSQueueAdvancer: NSObject {
}
private func publishNowPlaying(rate: Double) {
- let title = _nextTitle
- let artist = _nextArtist
- let duration = _nextDurationS
- let coverPath = _nextCoverPath
+ let title = _preparedTitle
+ let artist = _preparedArtist
+ let duration = _preparedDurationS
+ let coverPath = _preparedCoverPath
+ let elapsed = _preparedStartS
guard !title.isEmpty else { return }
var info: [String: Any] = [
MPMediaItemPropertyTitle: title,
MPMediaItemPropertyArtist: artist,
MPNowPlayingInfoPropertyPlaybackRate: rate,
- MPNowPlayingInfoPropertyElapsedPlaybackTime: 0.0,
+ MPNowPlayingInfoPropertyElapsedPlaybackTime: elapsed,
MPNowPlayingInfoPropertyMediaType: MPNowPlayingInfoMediaType.audio.rawValue,
]
if duration > 0 {
diff --git a/lib/providers/_lp_absorbing.dart b/lib/providers/_lp_absorbing.dart
index 2933976d..1857eda5 100644
--- a/lib/providers/_lp_absorbing.dart
+++ b/lib/providers/_lp_absorbing.dart
@@ -1198,18 +1198,44 @@ mixin _AbsorbingMixin on ChangeNotifier, _StateMixin, _CoreMixin {
if (candidateLibId != null && candidateLibId != currentLibId) continue;
}
+ final itemIdRaw = candidateIsPodcast ? key.substring(0, 36) : key;
+ final episodeIdRaw = candidateIsPodcast ? key.substring(37) : null;
+
+ // Try downloaded first; fall back to cached session for streaming so
+ // the pre-buffer + native handover path works for non-downloaded books.
final localPaths = DownloadService().getLocalPaths(key);
+ List<Map<String, dynamic>>? audioTracks;
+ Map<String, String>? audioHeaders;
if (localPaths == null || localPaths.isEmpty) {
- debugPrint('[PreBuffer] Next item $key not downloaded, skip');
- return null;
- }
- if (localPaths.length != 1) {
+ final api = self._api;
+ if (api == null) {
+ debugPrint('[PreBuffer] Next item $key no api context, skip');
+ return null;
+ }
+ final cachedSession = await SessionCache.load(
+ itemId: itemIdRaw,
+ episodeId: episodeIdRaw,
+ );
+ final tracks = cachedSession?['audioTracks'] as List<dynamic>?;
+ if (tracks == null || tracks.isEmpty) {
+ debugPrint('[PreBuffer] Next item $key not downloaded and no cached session, skip');
+ return null;
+ }
+ if (tracks.length != 1) {
+ debugPrint('[PreBuffer] Next item $key streaming multi-track, skip (MVP)');
+ return null;
+ }
+ audioTracks = tracks.map<Map<String, dynamic>>((t) {
+ final track = t as Map<String, dynamic>;
+ final contentUrl = track['contentUrl'] as String? ?? '';
+ return {'url': api.buildTrackUrl(contentUrl)};
+ }).toList();
+ audioHeaders = api.mediaHeaders;
+ } else if (localPaths.length != 1) {
debugPrint('[PreBuffer] Next item $key is multi-track, skip (MVP)');
return null;
}
- final itemIdRaw = candidateIsPodcast ? key.substring(0, 36) : key;
- final episodeIdRaw = candidateIsPodcast ? key.substring(37) : null;
final media = cached['media'] as Map<String, dynamic>? ?? {};
final metadata = media['metadata'] as Map<String, dynamic>? ?? {};
final title = candidateIsPodcast
@@ -1235,7 +1261,9 @@ mixin _AbsorbingMixin on ChangeNotifier, _StateMixin, _CoreMixin {
'coverUrl': getCoverUrl(itemIdRaw),
'duration': duration,
'chapters': chapters,
- 'localPaths': localPaths,
+ if (localPaths != null && localPaths.isNotEmpty) 'localPaths': localPaths,
+ if (audioTracks != null) 'audioTracks': audioTracks,
+ if (audioHeaders != null) 'audioHeaders': audioHeaders,
};
}
return null;
diff --git a/lib/services/audio_player_service.dart b/lib/services/audio_player_service.dart
index f10797c6..76470676 100644
--- a/lib/services/audio_player_service.dart
+++ b/lib/services/audio_player_service.dart
@@ -59,6 +59,25 @@ class AudioPlayerHandler extends BaseAudioHandler with SeekHandler {
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 Future<void> _logAbsorbDiag(String tag) async {
+ if (!Platform.isAndroid) return;
+ try {
+ final snap = await _absorbDiagChannel.invokeMapMethod<String, dynamic>('snapshot');
+ 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']}');
+ } catch (e) {
+ debugPrint('[AbsorbDiag] $tag: snapshot failed: $e');
+ }
+ }
+
/// Force-push current PlaybackState so the notification picks up
/// new chapter-relative position immediately (e.g. on chapter change).
void refreshPlaybackState() {
@@ -231,6 +250,7 @@ class AudioPlayerHandler extends BaseAudioHandler with SeekHandler {
@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)}');
@@ -258,6 +278,7 @@ class AudioPlayerHandler extends BaseAudioHandler with SeekHandler {
@override
Future<void> pause() async {
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();
@@ -463,6 +484,7 @@ class AudioPlayerHandler extends BaseAudioHandler with SeekHandler {
@override
Future<void> click([MediaButton button = MediaButton.media]) async {
debugPrint('[Handler] click(button=$button) count=${_clickCount + 1} playing=${_player.playing}');
+ await _logAbsorbDiag('click');
// 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();
@@ -1167,7 +1189,9 @@ class AudioPlayerService extends ChangeNotifier {
debugPrint('[PreBuffer] Pre-loaded next item: ${next['title']} ($nextItemId)');
if (Platform.isIOS) {
- unawaited(_primeNativeQueueAdvancer(next));
+ // Also prime the native handover so the background path can take over
+ // without going through just_audio's heavy reload.
+ unawaited(_primeNativeQueueAdvancer(next, localPaths, audioTracks, audioHeaders));
}
} catch (e, st) {
debugPrint('[PreBuffer] Failed: $e\n$st');
@@ -1176,23 +1200,56 @@ class AudioPlayerService extends ChangeNotifier {
// play session. Reset happens in _resetPreBufferState on the next playItem.
}
- Future<void> _primeNativeQueueAdvancer(Map<String, dynamic> next) async {
+ 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;
}
+
+ // Resume position for the next book.
+ double startS = 0;
+ if (itemId != null) {
+ final progressKey = next['episodeId'] != null
+ ? '$itemId-${next['episodeId']}'
+ : itemId;
+ final local = await _progressSync.getLocal(progressKey);
+ if (local != null && !(local['isFinished'] as bool? ?? false)) {
+ startS = (local['currentTime'] as num?)?.toDouble() ?? 0;
+ }
+ }
+
final ok = await _queueAdvancerChannel.invokeMethod<bool>('prepareNext', {
+ 'url': url,
+ 'isLocal': isLocal,
+ 'headers': audioHeaders ?? <String, String>{},
'title': next['title'] ?? '',
'artist': next['author'] ?? '',
'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;
}
}
@@ -3171,6 +3228,24 @@ class AudioPlayerService extends ChangeNotifier {
_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 (Platform.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.
diff --git a/packages/just_audio/darwin/just_audio/Sources/just_audio/AudioPlayer.m b/packages/just_audio/darwin/just_audio/Sources/just_audio/AudioPlayer.m
index 7649a82c..c08303d4 100644
--- a/packages/just_audio/darwin/just_audio/Sources/just_audio/AudioPlayer.m
+++ b/packages/just_audio/darwin/just_audio/Sources/just_audio/AudioPlayer.m
@@ -344,10 +344,17 @@
// TODO: Provide a similar case as _seekPos for _initialPos.
if (CMTIME_IS_VALID(_seekPos)) {
return (int)(1000 * CMTimeGetSeconds(_seekPos));
- } else if (_indexedAudioSources && _indexedAudioSources.count > 0) {
+ } else if (_index >= 0 && _indexedAudioSources && _index < _indexedAudioSources.count) {
int ms = (int)(1000 * CMTimeGetSeconds(_indexedAudioSources[_index].position));
if (ms < 0) ms = 0;
return ms;
+ } else if (_player && _player.currentItem) {
+ CMTime ct = _player.currentItem.currentTime;
+ if (CMTIME_IS_VALID(ct)) {
+ int ms = (int)(1000 * CMTimeGetSeconds(ct));
+ return ms < 0 ? 0 : ms;
+ }
+ return 0;
} else {
return 0;
}
@@ -356,7 +363,7 @@
- (int)getBufferedPosition {
if (_processingState == none || _processingState == loading) {
return 0;
- } else if (_indexedAudioSources && _indexedAudioSources.count > 0) {
+ } else if (_index >= 0 && _indexedAudioSources && _index < _indexedAudioSources.count) {
int ms = (int)(1000 * CMTimeGetSeconds(_indexedAudioSources[_index].bufferedPosition));
if (ms < 0) ms = 0;
return ms;
@@ -368,9 +375,16 @@
- (int)getDuration {
if (_processingState == none || _processingState == loading) {
return -1;
- } else if (_indexedAudioSources && _indexedAudioSources.count > 0) {
+ } else if (_index >= 0 && _indexedAudioSources && _index < _indexedAudioSources.count) {
int v = (int)(1000 * CMTimeGetSeconds(_indexedAudioSources[_index].duration));
return v;
+ } else if (_player && _player.currentItem) {
+ CMTime d = _player.currentItem.duration;
+ if (CMTIME_IS_VALID(d)) {
+ int ms = (int)(1000 * CMTimeGetSeconds(d));
+ return ms < 0 ? 0 : ms;
+ }
+ return 0;
} else {
return 0;
}
@@ -746,6 +760,11 @@
//NSLog(@"onComplete");
IndexedPlayerItem *endedPlayerItem = (IndexedPlayerItem *)notification.object;
+ if (![endedPlayerItem isKindOfClass:[IndexedPlayerItem class]] || _index < 0) {
+ // Foreign currentItem (host app drove the transition). Don't touch
+ // our own queue state.
+ return;
+ }
IndexedAudioSource *endedSource = endedPlayerItem.audioSource;
if (_loopMode == loopOne) {
@@ -895,8 +914,16 @@
} else if ([keyPath isEqualToString:@"currentItem"] && _player.currentItem) {
IndexedPlayerItem *playerItem = (IndexedPlayerItem *)change[NSKeyValueChangeNewKey];
//IndexedPlayerItem *oldPlayerItem = (IndexedPlayerItem *)change[NSKeyValueChangeOldKey];
+ if (![playerItem isKindOfClass:[IndexedPlayerItem class]]) {
+ // Host-app code replaced currentItem with a vanilla AVPlayerItem.
+ // Mark our internal index invalid and stop tracking until the host
+ // calls load again.
+ _index = -1;
+ [self broadcastPlaybackEvent];
+ return;
+ }
if (playerItem.status == AVPlayerItemStatusFailed) {
- if ([_orderInv[_index] intValue] + 1 < [_order count]) {
+ if (_index >= 0 && [_orderInv[_index] intValue] + 1 < [_order count]) {
// account for automatic move to next item
_index = [_order[[_orderInv[_index] intValue] + 1] intValue];
//NSLog(@"advance to next on error: index = %d", _index);
@@ -908,6 +935,11 @@
return;
} else {
int expectedIndex = [self indexForItem:playerItem];
+ if (expectedIndex < 0) {
+ _index = -1;
+ [self broadcastPlaybackEvent];
+ return;
+ }
if (_index != expectedIndex) {
// AVQueuePlayer will sometimes skip over error items without
// notifying this observer.
@@ -1155,6 +1187,7 @@
// - when the shuffle order changes. (TODO)
// - when the shuffle mode changes.
if (!_player) return;
+ if (_index < 0) return;
if (_audioSource && (_loopMode != loopOff || ([_order count] > 0 && [_orderInv[_index] intValue] + 1 < [_order count]))) {
_player.actionAtItemEnd = AVPlayerActionAtItemEndAdvance;
} else {
diff --git a/pubspec.yaml b/pubspec.yaml
index 1553da7c..4b633845 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
name: absorb
description: An Audiobookshelf Client
publish_to: 'none'
-version: 1.8.91+145
+version: 1.8.91+146
environment:
sdk: '>=3.1.0 <4.0.0'