A cross platform Audiobookshelf client for Android and iOS
Dart
import AVFoundation
import Foundation
import UIKit
/// Single AVQueuePlayer that owns audio playback for the entire app lifetime.
/// The next files of a multi-file book wait in its queue, so the player moves
/// straight on at the end of a file. Loads, seeks into another file and
/// cross-book swaps rebuild the queue on the same player. The player is never
/// destroyed, so iOS keeps granting background audio output across transitions.
final class AbsorbAudioEngine: NSObject {
static let shared = AbsorbAudioEngine()
static var logSink: ((String) -> Void)?
weak var delegate: AbsorbAudioEngineDelegate?
private let queue = DispatchQueue(label: "com.barnabas.absorb.audioengine")
private let player: AVQueuePlayer = {
let p = AVQueuePlayer()
p.automaticallyWaitsToMinimizeStalling = false
p.allowsExternalPlayback = false
return p
}()
// Items in the player's queue, the playing one first. Opening the next file
// only after the last one stopped left an audible gap between files.
private static let tracksQueuedAhead = 2
private var queuedTracks: [(item: AVPlayerItem, index: Int, tapped: Bool)] = []
private var lastQueuedIndex = -1
// Bumped whenever the queue is rebuilt, so a file still being prepared for
// the old queue is dropped.
private var aheadGeneration: UInt = 0
private var aheadInFlight = false
private var currentItemObservation: NSKeyValueObservation?
// Track list of the currently-loaded book.
private var trackUrls: [URL] = []
private var trackHeaders: [String: String] = [:]
private var trackOffsets: [Double] = [0]
private var trackIndex: Int = 0
private var totalDurationS: Double = 0
private var currentItem: AVPlayerItem?
private var currentEpoch: UInt = 0
// Book id of whatever is currently loaded. Set by load() so the
// Flutter-suspended controller (AbsorbPlayerCore) can tell whether the engine
// already holds the book it was asked to resume - if so it just resumes the
// live engine rather than reloading. Read off the engine queue.
private var _currentItemId: String?
// Pre-prepared next book waiting for the cross-book swap.
private var nextTrackUrls: [URL] = []
private var nextTrackHeaders: [String: String] = [:]
private var nextTrackOffsets: [Double] = [0]
private var nextTotalDurationS: Double = 0
private var nextItem: AVPlayerItem?
private var nextStartS: Double = 0
private var nextItemId: String?
// Configured player state.
private var speed: Float = 1.0
private var volume: Float = 1.0
private var eqEnabled: Bool = false
// Whether the current item physically has the processing tap installed.
// Lets us avoid rebuilding the item to re-apply effects when a tap is
// already present (it reads the live DSP params on its own).
private var tapAttached: Bool = false
private var processingState: EngineProcessingState = .idle
// Observers.
private var timeObserver: Any?
private var itemEndObserver: NSObjectProtocol?
private var statusObservation: NSKeyValueObservation?
private var tcsObservation: NSKeyValueObservation?
private var bufferedObservation: NSKeyValueObservation?
private var playbackBufferEmptyObs: NSKeyValueObservation?
// Position emit throttling. Set up a 5 Hz observer; sampling rate to delegate
// is 5 Hz foreground, 1 Hz background.
private var lastEmittedSecondInt: Int = -1
private var isBackgrounded: Bool = false
// Where the last seek or load asked to be, reported as the position until
// the player is confirmed there. A dropped seek used to read back as 0 (GH #414).
private let positionLock = NSLock()
private var pendingSeekS: Double?
private var lastGoodPositionS: Double = 0
private var seekSerial: UInt = 0
private var seekAttempts = 0
private var lastEmitSerial: UInt = 0
private var lastEmittedPosS: Double = 0
private var timeUnreadable = false
private static let seekLandedToleranceS = 2.0
private override init() {
super.init()
addPeriodicTimeObserver()
observeAppLifecycle()
currentItemObservation = player.observe(\.currentItem, options: [.new]) { [weak self] _, _ in
self?.queue.async { self?.handleQueueAdvance() }
}
}
// MARK: - Public API
func load(tracks: [(url: URL, headers: [String: String])],
trackOffsets: [Double],
startPositionS: Double,
totalDurationS: Double,
speed: Float,
volume: Float,
eqEnabled: Bool,
itemId: String? = nil,
startTrackIndex: Int? = nil,
completion: @escaping (Double?) -> Void) {
queue.async { [weak self] in
guard let self = self else { completion(nil); return }
// No session activation here: loading is silent, and play() activates
// before any audio starts. Activating on load stole the audio from
// whatever was playing (Spotify stopped the moment Absorb opened) when
// the launch hot-load began loading the last book paused - exactly the
// case the NowPlayingPrimer's other-audio guard exists to avoid.
if let itemId = itemId { self._currentItemId = itemId }
self.trackUrls = tracks.map { $0.url }
self.trackHeaders = tracks.first?.headers ?? [:]
self.trackOffsets = Self.normalizeOffsets(trackOffsets, trackCount: tracks.count, totalDurationS: totalDurationS)
self.totalDurationS = totalDurationS
self.speed = speed
self.volume = volume
self.eqEnabled = eqEnabled
self.player.volume = volume
// Flutter loads with an explicit track and a track-local start, the
// same shape as seek(), because it hands over no offsets: deriving the
// track from a "global" start here put every mid-book load on track 0
// and clamped the position to that track's end. The widget core still
// loads by global position with the offsets it stashed.
let targetIndex: Int
let localStart: Double
if let explicit = startTrackIndex, explicit >= 0, explicit < tracks.count {
targetIndex = explicit
localStart = max(0, startPositionS)
} else {
targetIndex = self.trackIndexFor(globalSeconds: startPositionS)
localStart = max(0, startPositionS - self.trackOffsets[targetIndex])
}
self.trackIndex = targetIndex
self.loadTrack(atIndex: targetIndex, localStart: localStart, autoPlay: false, completion: completion)
}
}
func play() {
queue.async { [weak self] in
guard let self = self else { return }
self.activateSession()
self.player.play()
self.player.rate = self.speed
self.emitState()
}
}
func pause() {
queue.async { [weak self] in
guard let self = self else { return }
self.player.pause()
self.emitState()
}
}
func stop() {
queue.async { [weak self] in
guard let self = self else { return }
self.currentItem = nil
self._currentItemId = nil
self.resetQueuedTracks()
self.processingState = .idle
self.emitState()
DispatchQueue.main.async {
self.player.pause()
self.player.removeAllItems()
self.queue.async { _ = self.beginSeek(nil, fallback: 0) }
}
}
}
/// Seek to `localS` within track `trackIndex` (nil = current track).
func seek(toLocalS localS: Double, trackIndex: Int?, completion: @escaping (Bool) -> Void) {
queue.async { [weak self] in
guard let self = self else { completion(false); return }
guard !self.trackUrls.isEmpty else { completion(false); return }
let requested = trackIndex ?? self.trackIndex
let target = max(0, min(requested, self.trackUrls.count - 1))
let localTarget = localS.isFinite ? max(0, localS) : 0
if target == self.trackIndex, self.currentItem != nil {
let serial = self.beginSeek(localTarget, fallback: localTarget)
self.applySeek(localTarget, serial: serial, completion: completion)
} else {
let wasPlaying = self.player.rate > 0
self.trackIndex = target
self.loadTrack(atIndex: target, localStart: localTarget, autoPlay: wasPlaying) { _ in
completion(true)
}
self.delegate?.engineDidChangeTrack(trackIndex: target, totalTracks: self.trackUrls.count)
}
}
}
func setSpeed(_ newSpeed: Float) {
queue.async { [weak self] in
guard let self = self else { return }
self.speed = newSpeed
if self.player.rate > 0 {
self.player.rate = newSpeed
}
}
}
func setVolume(_ newVolume: Float) {
queue.async { [weak self] in
guard let self = self else { return }
self.volume = newVolume
self.player.volume = newVolume
}
}
func setNextSource(tracks: [(url: URL, headers: [String: String])],
trackOffsets: [Double],
startPositionS: Double,
totalDurationS: Double,
itemId: String? = nil,
completion: @escaping (Bool) -> Void) {
queue.async { [weak self] in
guard let self = self else { completion(false); return }
self.nextTrackUrls = tracks.map { $0.url }
self.nextTrackHeaders = tracks.first?.headers ?? [:]
self.nextTrackOffsets = Self.normalizeOffsets(trackOffsets, trackCount: tracks.count, totalDurationS: totalDurationS)
self.nextTotalDurationS = totalDurationS
self.nextStartS = startPositionS
self.nextItemId = itemId
guard let firstUrl = tracks.first?.url else {
self.nextItem = nil
completion(false)
return
}
let item = self.makePlayerItem(url: firstUrl, headers: tracks.first?.headers ?? [:])
let asset = item.asset
asset.loadValuesAsynchronously(forKeys: ["tracks", "duration"]) { [weak self] in
guard let self = self else { return }
var err: NSError?
let status = asset.statusOfValue(forKey: "tracks", error: &err)
if status != .loaded {
self.emit("[AudioEngine] setNextSource: tracks not loaded status=\(status.rawValue) err=\(err?.localizedDescription ?? "nil")")
self.queue.async {
self.nextItem = nil
completion(false)
}
return
}
self.queue.async {
self.nextItem = item
self.emit("[AudioEngine] setNextSource prepared: \(firstUrl.lastPathComponent)")
completion(true)
}
}
}
}
func clearNextSource() {
queue.async { [weak self] in
self?.nextTrackUrls = []
self?.nextTrackHeaders = [:]
self?.nextTrackOffsets = [0]
self?.nextTotalDurationS = 0
self?.nextStartS = 0
self?.nextItem = nil
self?.nextItemId = nil
}
}
/// Ensure the processing tap is live so EQ/effects apply. A tap can't be
/// added to an already-playing item, so if one isn't attached we rebuild the
/// current track in place (brief reload). If a tap is already present it
/// reads the live DSP params itself - nothing to do.
func attachEqualizerTap() {
queue.async { [weak self] in
guard let self = self else { return }
self.eqEnabled = true
if self.tapAttached { return }
guard let item = self.currentItem else { return }
if self.player.rate > 0 {
self.loadTrack(atIndex: self.trackIndex,
localStart: self.getPositionS(),
autoPlay: true) { _ in }
} else {
AbsorbAudioEQProcessor.shared.attachTapSync(to: item)
self.tapAttached = true
if !self.queuedTracks.isEmpty { self.queuedTracks[0].tapped = true }
// Queued files were built without the tap.
self.requeueAhead()
}
}
}
/// Stop applying effects. Lazy: the DSP params are already zeroed by the
/// caller, so the tap (if attached) just passes through. We leave it in place
/// to avoid a reload blip; it won't reattach on the next track load.
func detachEqualizerTap() {
queue.async { [weak self] in
guard let self = self else { return }
self.eqEnabled = false
}
}
/// Track-local position; Dart adds the track offset (just_audio contract).
func getPositionS() -> Double {
let raw = player.currentItem?.currentTime().seconds ?? .nan
positionLock.lock()
defer { positionLock.unlock() }
if let pending = pendingSeekS { return pending }
if raw.isFinite { lastGoodPositionS = max(0, raw) }
return lastGoodPositionS
}
func getBufferedPositionS() -> Double {
guard let item = player.currentItem else { return 0 }
guard let last = item.loadedTimeRanges.last as? NSValue else { return 0 }
let range = last.timeRangeValue
let bufferedLocal = CMTimeGetSeconds(range.start + range.duration)
return bufferedLocal.isFinite ? max(0, bufferedLocal) : 0
}
// MARK: - Adoption helpers (for the Flutter-suspended controller)
//
// AbsorbPlayerCore drives this same shared engine when Flutter is suspended.
// These let it decide whether to reload, and read/save position in the
// global coordinate space (the engine works in track-local space internally,
// but the app group and server store global seconds).
/// Book id of the currently-loaded book, or nil if nothing is loaded.
var currentItemId: String? {
queue.sync { _currentItemId }
}
/// True once a source has been loaded (and not stopped).
var isLoaded: Bool {
queue.sync { !trackUrls.isEmpty && currentItem != nil }
}
/// True while the player is actively playing (rate > 0).
var isPlaying: Bool {
player.rate > 0 || player.timeControlStatus == .playing
}
/// Current track index within the loaded book.
var currentTrackIndex: Int {
queue.sync { trackIndex }
}
/// Global position = track-local position + the current track's offset.
func globalPositionS() -> Double {
queue.sync {
let safeLocal = getPositionS()
let base = trackOffsets.indices.contains(trackIndex) ? trackOffsets[trackIndex] : 0
let baseSafe = base.isFinite ? base : 0
return baseSafe + safeLocal
}
}
/// Convert a global position to (localS, trackIndex) and seek there. Used by
/// the controller's skip / scrub handlers, which think in global seconds.
func seekToGlobal(_ globalSeconds: Double, completion: @escaping (Bool) -> Void) {
queue.async { [weak self] in
guard let self = self else { completion(false); return }
let target = self.trackIndexFor(globalSeconds: globalSeconds)
let base = self.trackOffsets.indices.contains(target) ? self.trackOffsets[target] : 0
let local = max(0, globalSeconds - (base.isFinite ? base : 0))
self.seek(toLocalS: local, trackIndex: target, completion: completion)
}
}
// MARK: - Seek bookkeeping
/// Starts a new seek generation. With a target, getPositionS reports that
/// target until the player is confirmed there.
private func beginSeek(_ targetS: Double?, fallback: Double) -> UInt {
seekSerial &+= 1
seekAttempts = 0
positionLock.lock()
pendingSeekS = targetS
lastGoodPositionS = max(0, fallback)
positionLock.unlock()
return seekSerial
}
private func pendingSeekTarget() -> Double? {
positionLock.lock()
defer { positionLock.unlock() }
return pendingSeekS
}
private func clearPendingSeek() {
positionLock.lock()
pendingSeekS = nil
positionLock.unlock()
}
private func applySeek(_ localS: Double, serial: UInt, completion: ((Bool) -> Void)?) {
let wasPlaying = player.rate > 0
player.seek(
to: CMTime(seconds: localS, preferredTimescale: 1000),
toleranceBefore: .zero, toleranceAfter: .zero
) { [weak self] finished in
guard let self = self else { completion?(finished); return }
self.queue.async {
if wasPlaying { self.player.rate = self.speed }
self.settlePendingSeek(serial: serial)
self.emitPositionImmediate()
completion?(finished)
}
}
}
/// A seek reported back: seek again if the player is not really there.
private func settlePendingSeek(serial: UInt) {
guard serial == seekSerial, let target = pendingSeekTarget() else { return }
// Not ready yet: the status observer picks it up from here.
guard let item = player.currentItem, item.status == .readyToPlay else { return }
let raw = item.currentTime().seconds
let duration = item.duration.seconds
let landed = raw.isFinite && abs(raw - target) <= Self.seekLandedToleranceS
let pastEnd = duration.isFinite && target >= duration - 1
if landed || pastEnd {
clearPendingSeek()
return
}
if seekAttempts >= 2 {
emit("[AudioEngine] seek to \(target)s did not land (at \(raw)s), giving up")
clearPendingSeek()
return
}
seekAttempts += 1
emit("[AudioEngine] seek to \(target)s did not land (at \(raw)s), trying again")
applySeek(target, serial: serial, completion: nil)
}
/// AVPlayer drops a seek made before the item is ready, so check on ready.
private func seekPendingOnReady() {
guard let target = pendingSeekTarget() else { return }
let raw = player.currentItem?.currentTime().seconds ?? .nan
if raw.isFinite && abs(raw - target) <= Self.seekLandedToleranceS {
clearPendingSeek()
return
}
emit("[AudioEngine] item ready at \(raw)s, seeking to the pending \(target)s")
applySeek(target, serial: seekSerial, completion: nil)
}
// MARK: - Track loading
private func loadTrack(atIndex index: Int,
localStart: Double,
autoPlay: Bool,
completion: @escaping (Double?) -> Void) {
guard index < trackUrls.count else { completion(nil); return }
let url = trackUrls[index]
let headers = trackHeaders
let eqEnabled = self.eqEnabled
let item = makePlayerItem(url: url, headers: headers)
currentEpoch &+= 1
let myEpoch = currentEpoch
let startSerial = beginSeek(localStart > 0 ? localStart : nil, fallback: localStart)
resetQueuedTracks()
lastQueuedIndex = index
let itemEndAction = endAction(forTrack: index)
processingState = .loading
emitState()
// Preload tracks so the EQ tap can attach synchronously before playback
// (attachTapSync), and so load failures surface early.
let asset = item.asset
asset.loadValuesAsynchronously(forKeys: ["tracks", "duration"]) { [weak self] in
guard let self = self else { completion(nil); return }
var err: NSError?
let status = asset.statusOfValue(forKey: "tracks", error: &err)
let decodedDurationS = asset.duration.seconds
if status != .loaded {
self.emit("[AudioEngine] loadTrack idx=\(index) tracks-load failed status=\(status.rawValue) err=\(err?.localizedDescription ?? "nil")")
}
DispatchQueue.main.async { [weak self] in
guard let self = self else { completion(nil); return }
guard self.currentEpoch == myEpoch else {
self.queue.async {
self.emit("[AudioEngine] loadTrack idx=\(index) skipped (stale epoch)")
completion(nil)
}
return
}
// Detach the outgoing item before promoting the new one, so its EQ
// detach can't wipe the attach below.
self.detachCurrentItem()
self.currentItem = item
self.observeNewCurrentItem(item)
if eqEnabled {
// audioMix must be set before playback starts or the tap is ignored.
AbsorbAudioEQProcessor.shared.attachTapSync(to: item)
self.tapAttached = true
} else {
self.tapAttached = false
}
self.player.actionAtItemEnd = itemEndAction
self.player.removeAllItems()
self.player.insert(item, after: nil)
let finish: (Bool) -> Void = { _ in
if autoPlay {
self.player.play()
self.player.rate = self.speed
}
self.queue.async {
self.settlePendingSeek(serial: startSerial)
self.emit("[AudioEngine] loadTrack idx=\(index) localStart=\(localStart) autoPlay=\(autoPlay)")
if self.currentEpoch == myEpoch {
self.queuedTracks = [(item: item, index: index, tapped: eqEnabled)]
self.enqueueAhead()
}
completion(decodedDurationS.isFinite && decodedDurationS > 0 ? decodedDurationS : nil)
}
}
if localStart > 0 {
item.seek(to: CMTime(seconds: localStart, preferredTimescale: 1000),
toleranceBefore: .zero, toleranceAfter: .zero, completionHandler: finish)
} else {
finish(true)
}
}
}
}
private func makePlayerItem(url: URL, headers: [String: String]) -> AVPlayerItem {
var options: [String: Any] = [:]
if !headers.isEmpty {
options["AVURLAssetHTTPHeaderFieldsKey"] = headers
}
let asset = AVURLAsset(url: url, options: options)
let item = AVPlayerItem(asset: asset)
item.audioTimePitchAlgorithm = .timeDomain
return item
}
private func detachCurrentItem() {
if let item = currentItem, eqEnabled {
AbsorbAudioEQProcessor.shared.detach(from: item)
}
if let prev = itemEndObserver {
NotificationCenter.default.removeObserver(prev)
itemEndObserver = nil
}
statusObservation?.invalidate()
statusObservation = nil
tcsObservation?.invalidate()
tcsObservation = nil
bufferedObservation?.invalidate()
bufferedObservation = nil
playbackBufferEmptyObs?.invalidate()
playbackBufferEmptyObs = nil
}
private func observeNewCurrentItem(_ item: AVPlayerItem) {
itemEndObserver = NotificationCenter.default.addObserver(
forName: .AVPlayerItemDidPlayToEndTime,
object: item,
queue: nil
) { [weak self, weak item] _ in
self?.queue.async { self?.handleItemEnd(item) }
}
// Initial too: a queued file is usually ready before it starts playing,
// and its duration and ready state still have to be reported.
statusObservation = item.observe(\.status, options: [.initial, .new]) { [weak self] item, _ in
self?.queue.async {
switch item.status {
case .readyToPlay:
self?.processingState = .ready
self?.emitState()
self?.seekPendingOnReady()
let d = item.asset.duration.seconds
if d.isFinite { self?.delegate?.engineDidLoadDuration(d) }
case .failed:
self?.processingState = .idle
self?.emit("[AudioEngine] item failed: \(item.error?.localizedDescription ?? "unknown")")
self?.delegate?.engineDidError(message: item.error?.localizedDescription ?? "item failed", code: nil)
default:
break
}
}
}
tcsObservation = player.observe(\.timeControlStatus, options: [.new]) { [weak self] _, _ in
self?.queue.async {
guard let self = self else { return }
switch self.player.timeControlStatus {
case .paused:
if self.processingState == .buffering { self.processingState = .ready }
case .waitingToPlayAtSpecifiedRate:
self.processingState = .buffering
case .playing:
self.processingState = .ready
@unknown default:
break
}
self.emitState()
}
}
playbackBufferEmptyObs = item.observe(\.isPlaybackBufferEmpty, options: [.new]) { [weak self] item, _ in
self?.queue.async {
if item.isPlaybackBufferEmpty {
self?.processingState = .buffering
self?.emitState()
}
}
}
}
private func handleItemEnd(_ endedItem: AVPlayerItem?) {
// The queue already moved on to the next file.
guard let endedItem = endedItem, endedItem === currentItem else { return }
let nextTrack = trackIndex + 1
if nextTrack < trackUrls.count {
if queuedTracks.contains(where: { $0.index == nextTrack }) {
// The queue moves on by itself. If it hasn't shortly (the file was
// still being added when this one ended), load it the old way.
queue.asyncAfter(deadline: .now() + 1) { [weak self] in
guard let self = self, self.currentItem === endedItem else { return }
self.emit("[AudioEngine] queue did not move on to idx=\(nextTrack), loading it")
self.loadNextTrackAfterEnd(nextTrack)
}
return
}
loadNextTrackAfterEnd(nextTrack)
return
}
if nextItem != nil {
swapToNextBook()
return
}
processingState = .completed
emitState()
delegate?.engineDidCompleteBook()
}
private func loadNextTrackAfterEnd(_ nextTrack: Int) {
trackIndex = nextTrack
// Player is paused now that the item ended; reading player.rate would
// wrongly report autoPlay=false. Intra-book advance should keep playing.
loadTrack(atIndex: nextTrack, localStart: 0, autoPlay: true) { _ in }
delegate?.engineDidChangeTrack(trackIndex: nextTrack, totalTracks: trackUrls.count)
}
// MARK: - Track queue
/// The player moved on to a queued file at the end of the last one.
private func handleQueueAdvance() {
guard let item = player.currentItem, item !== currentItem,
let position = queuedTracks.firstIndex(where: { $0.item === item }) else { return }
let entry = queuedTracks[position]
if position > 1 {
emit("[AudioEngine] queue skipped \(position - 1) file(s) before idx=\(entry.index)")
}
queuedTracks.removeFirst(position)
detachCurrentItem()
currentItem = item
trackIndex = entry.index
tapAttached = entry.tapped
_ = beginSeek(nil, fallback: 0)
observeNewCurrentItem(item)
let itemEndAction = endAction(forTrack: entry.index)
DispatchQueue.main.async { self.player.actionAtItemEnd = itemEndAction }
emit("[AudioEngine] queue moved on to idx=\(entry.index)")
delegate?.engineDidChangeTrack(trackIndex: entry.index, totalTracks: trackUrls.count)
enqueueAhead()
}
/// Advance through the book's files, but stop on the last one so the end of
/// the book still leaves it loaded (completion, next-book swap, replay).
private func endAction(forTrack index: Int) -> AVPlayer.ActionAtItemEnd {
index + 1 < trackUrls.count ? .advance : .pause
}
private func resetQueuedTracks() {
queuedTracks = []
aheadGeneration &+= 1
aheadInFlight = false
}
/// Prepare the next file and add it behind the queued ones, one at a time so
/// they stay in order, until enough are waiting.
private func enqueueAhead() {
guard !aheadInFlight, let playing = queuedTracks.first, playing.item === currentItem else { return }
let index = lastQueuedIndex + 1
guard index < trackUrls.count, index <= playing.index + Self.tracksQueuedAhead else { return }
aheadInFlight = true
let generation = aheadGeneration
let tap = eqEnabled
let item = makePlayerItem(url: trackUrls[index], headers: trackHeaders)
let asset = item.asset
asset.loadValuesAsynchronously(forKeys: ["tracks", "duration"]) { [weak self] in
guard let self = self else { return }
var err: NSError?
let loaded = asset.statusOfValue(forKey: "tracks", error: &err) == .loaded
self.queue.async {
guard generation == self.aheadGeneration else { return }
guard loaded, let after = self.queuedTracks.last?.item else {
self.aheadInFlight = false
self.emit("[AudioEngine] could not queue idx=\(index) err=\(err?.localizedDescription ?? "nil")")
return
}
// Listed before it is inserted, so an advance onto it is recognised.
self.queuedTracks.append((item: item, index: index, tapped: tap))
self.lastQueuedIndex = index
DispatchQueue.main.async {
// The file it goes after may have finished already.
let inserted = self.player.items().contains { $0 === after }
&& self.player.canInsert(item, after: after)
if inserted {
// audioMix must be set before playback starts or the tap is ignored.
if tap { AbsorbAudioEQProcessor.shared.attachTapSync(to: item) }
self.player.insert(item, after: after)
}
self.queue.async {
guard generation == self.aheadGeneration else { return }
self.aheadInFlight = false
if inserted {
self.enqueueAhead()
} else {
self.queuedTracks.removeAll { $0.item === item }
self.lastQueuedIndex = index - 1
}
}
}
}
}
}
/// Rebuild the files queued behind the playing one.
private func requeueAhead() {
guard let playing = queuedTracks.first else { return }
let stale = queuedTracks.dropFirst().map { $0.item }
resetQueuedTracks()
queuedTracks = [playing]
lastQueuedIndex = playing.index
DispatchQueue.main.async {
for item in stale { self.player.remove(item) }
self.queue.async { self.enqueueAhead() }
}
}
private func swapToNextBook() {
guard let item = nextItem else { return }
detachCurrentItem()
trackUrls = nextTrackUrls
trackHeaders = nextTrackHeaders
trackOffsets = nextTrackOffsets
totalDurationS = nextTotalDurationS
trackIndex = 0
// Promote the next book's id so the widget controller recognises the book
// the engine is now actually playing (otherwise a widget tap after an
// auto-advance would reload and restart the new book's stream).
if let nextId = nextItemId { _currentItemId = nextId }
currentItem = item
currentEpoch &+= 1
resetQueuedTracks()
queuedTracks = [(item: item, index: 0, tapped: eqEnabled)]
lastQueuedIndex = 0
let itemEndAction = endAction(forTrack: 0)
observeNewCurrentItem(item)
let startS = nextStartS
let startSerial = beginSeek(startS > 0 ? startS : nil, fallback: startS)
// Inline clear so the next swap can be armed before our async block runs.
nextTrackUrls = []
nextTrackHeaders = [:]
nextTrackOffsets = [0]
nextTotalDurationS = 0
nextStartS = 0
nextItem = nil
nextItemId = nil
DispatchQueue.main.async { [weak self] in
guard let self = self else { return }
if self.eqEnabled {
// audioMix must be set before playback starts or the tap is ignored.
AbsorbAudioEQProcessor.shared.attachTapSync(to: item)
self.tapAttached = true
} else {
self.tapAttached = false
}
self.player.actionAtItemEnd = itemEndAction
self.player.removeAllItems()
self.player.insert(item, after: nil)
self.queue.async { self.enqueueAhead() }
if startS > 0 {
item.seek(to: CMTime(seconds: startS, preferredTimescale: 1000),
toleranceBefore: .zero, toleranceAfter: .zero) { _ in
self.queue.async {
self.player.play()
self.player.rate = self.speed
self.settlePendingSeek(serial: startSerial)
self.emit("[AudioEngine] swapToNextBook done at startS=\(startS) rate=\(self.player.rate)")
self.delegate?.engineDidAutoAdvance()
self.delegate?.engineDidLoadDuration(self.totalDurationS > 0 ? self.totalDurationS : nil)
}
}
} else {
self.player.play()
self.player.rate = self.speed
self.queue.async {
self.emit("[AudioEngine] swapToNextBook done at startS=0 rate=\(self.player.rate)")
self.delegate?.engineDidAutoAdvance()
self.delegate?.engineDidLoadDuration(self.totalDurationS > 0 ? self.totalDurationS : nil)
}
}
}
}
// MARK: - Audio session
private func activateSession() {
let session = AVAudioSession.sharedInstance()
do {
if session.category != .playback {
try session.setCategory(.playback, mode: .spokenAudio, policy: .longFormAudio)
}
try session.setActive(true)
} catch {
emit("[AudioEngine] session activate failed: \(error.localizedDescription)")
}
}
// MARK: - Position emit + lifecycle
private func addPeriodicTimeObserver() {
let interval = CMTime(seconds: 0.2, preferredTimescale: 1000)
timeObserver = player.addPeriodicTimeObserver(
forInterval: interval, queue: .main
) { [weak self] _ in
self?.queue.async { self?.maybeEmitPosition() }
}
}
private func maybeEmitPosition() {
let pos = getPositionS()
guard pos.isFinite else { return }
let raw = player.currentItem?.currentTime().seconds ?? .nan
if raw.isFinite {
timeUnreadable = false
} else if !timeUnreadable, pendingSeekTarget() == nil {
timeUnreadable = true
emit("[AudioEngine] player time unreadable, holding \(pos)s")
}
if seekSerial == lastEmitSerial, pos < lastEmittedPosS - 30 {
emit("[AudioEngine] position fell \(lastEmittedPosS)s -> \(pos)s with no seek")
}
lastEmitSerial = seekSerial
lastEmittedPosS = pos
let posInt = Int(pos)
let stride = isBackgrounded ? 1 : 0
if isBackgrounded {
if posInt == lastEmittedSecondInt { return }
lastEmittedSecondInt = posInt
} else {
// Foreground: emit every observer tick (~5 Hz).
_ = stride
}
delegate?.engineDidEmitPosition(pos)
}
private func emitPositionImmediate() {
let pos = getPositionS()
guard pos.isFinite else { return }
lastEmittedSecondInt = Int(pos)
delegate?.engineDidEmitPosition(pos)
}
private func emitState() {
let snap = EngineStateSnapshot(
playing: player.rate > 0 || player.timeControlStatus == .playing,
processingState: processingState,
timeControlStatus: player.timeControlStatus.rawValue,
reasonForWaitingToPlay: player.reasonForWaitingToPlay?.rawValue
)
delegate?.engineDidChangeState(snap)
}
private func observeAppLifecycle() {
NotificationCenter.default.addObserver(
forName: UIApplication.didEnterBackgroundNotification,
object: nil, queue: .main
) { [weak self] _ in self?.queue.async { self?.isBackgrounded = true } }
NotificationCenter.default.addObserver(
forName: UIApplication.willEnterForegroundNotification,
object: nil, queue: .main
) { [weak self] _ in self?.queue.async { self?.isBackgrounded = false } }
}
// MARK: - Helpers
private func trackIndexFor(globalSeconds: Double) -> Int {
if globalSeconds <= 0 { return 0 }
let trackCount = max(1, trackOffsets.count - 1)
for i in 0..<trackCount {
let nextOffset = i + 1 < trackOffsets.count ? trackOffsets[i + 1] : .greatestFiniteMagnitude
if globalSeconds < nextOffset { return i }
}
return trackCount - 1
}
private static func normalizeOffsets(_ offsets: [Double],
trackCount: Int,
totalDurationS: Double) -> [Double] {
// Expect length = trackCount + 1, cumulative starting at 0. Fall back to
// single-track if the caller passed nothing usable.
if offsets.count == trackCount + 1, offsets.first == 0 {
return offsets
}
if trackCount <= 1 || totalDurationS <= 0 {
return [0, totalDurationS > 0 ? totalDurationS : .greatestFiniteMagnitude]
}
var out: [Double] = [0]
let perTrack = totalDurationS / Double(trackCount)
for i in 1...trackCount { out.append(perTrack * Double(i)) }
return out
}
private func emit(_ line: String) {
NSLog("%@", line)
Self.logSink?(line)
}
}