@swiftbrowser/swift 0.1.0 → 0.2.0

package/Sources/AVFoundation/Player.swift

@@ -0,0 +1,749 @@
+// `AVPlayer`, `AVPlayerItem`, `AVQueuePlayer` and `AVPlayerLooper` over the
+// page's `video` element (docs/ops-protocol.md, "Video and audio").
+//
+// A player holds what it was told (item, rate, mute, volume, the last seek)
+// in an observed state object: the views that show the player read it in
+// their bodies, so a change draws them again with new props. What the page
+// reports comes back through `_event(_:from:)`: an item's metadata (`ready`),
+// the position (`time`, extrapolated between reports while playing), whether
+// it is really playing (`status`), the end, errors, and what the viewer did
+// with the native controls (`play`, `pause`, `volume`, `rate`).
+//
+// Of the views showing a player, the newest plays it; the others are paused
+// and muted, and the one that takes over seeks to where the player is. A
+// player shown nowhere plays nothing and keeps its position.
+
+import Foundation
+import FoundationBridge
+import Observation
+import SwiftUI
+import struct SwiftUI.CGSize
+import struct SwiftUI.CGRect
+
+/// What the views showing a player read; a change renders them again.
+@Observable
+final class _AVPlayerState {
+    var item: AVPlayerItem?
+    var rate: Float = 0
+    var isMuted = false
+    var volume: Float = 1
+    /// The last seek, in seconds; the page performs each serial once.
+    var seekTime: Double = 0
+    var seekSerial = 0
+    /// The views showing the player (`_AVPlayerVideo` surfaces), oldest first; the last plays.
+    var surfaces: [ObjectIdentifier] = []
+    /// An `AVPlayerLooper` loops the item (the element's `loop`).
+    var loops = false
+    /// The shortest periodic observer interval below the page's own pace, in seconds.
+    var reportInterval: Double?
+    var timeControlStatus: AVPlayer.TimeControlStatus = .paused
+}
+
+/// What the views showing an item's player read about the item.
+@Observable
+final class _AVItemState {
+    var status: AVPlayerItem.Status = .unknown
+    /// The URL the page loads (a file's blob URL once the page made it).
+    var pageURL: String?
+    /// Seconds; nil until known, and for a live stream.
+    var duration: Double?
+    var presentationSize: CGSize = .zero
+    @ObservationIgnored var error: (any Error)?
+}
+
+// MARK: - AVPlayerItem
+
+/// The state of one playback of an asset: its status, duration, size and position.
+open class AVPlayerItem: @unchecked Sendable {
+    public enum Status: Int, Sendable {
+        case unknown, readyToPlay, failed
+    }
+
+    public let asset: AVAsset
+    let _state = _AVItemState()
+    /// The item's position in seconds, as the page last reported it (or a seek set it).
+    var _time: Double = 0
+    /// The player whose current item this is.
+    weak var _player: AVPlayer?
+
+    open var forwardPlaybackEndTime: CMTime = .invalid
+    open var reversePlaybackEndTime: CMTime = .invalid
+    open var preferredForwardBufferDuration: TimeInterval = 0
+    open var preferredPeakBitRate: Double = 0
+    open var preferredMaximumResolution: CGSize = .zero
+    open var canUseNetworkResourcesForLiveStreamingWhilePaused = false
+    open var appliesPerFrameHDRDisplayMetadata = true
+    open var audioTimePitchAlgorithm: String?
+
+    public convenience init(url URL: URL) {
+        self.init(asset: AVURLAsset(url: URL))
+    }
+
+    public init(asset: AVAsset, automaticallyLoadedAssetKeys: [AVPartialAsyncProperty<AVAsset>] = []) {
+        self.asset = asset
+        resolvePageURL()
+    }
+
+    /// Remote, data and blob URLs load as they are; a file is handed to the page first.
+    private func resolvePageURL() {
+        guard let url = asset._url else {
+            _fail(AVError(.operationNotSupportedForAsset, message: "the asset has no URL"))
+            return
+        }
+        guard url.isFileURL else {
+            _state.pageURL = url.absoluteString
+            return
+        }
+        Task { @MainActor [weak self] in
+            do {
+                let pageURL = try await _AVMediaHost.pageURL(for: url)
+                self?._state.pageURL = pageURL
+            } catch {
+                self?._fail(error)
+            }
+        }
+    }
+
+    open var status: Status { _state.status }
+    open var error: (any Error)? { _state.error }
+    /// `.indefinite` until the page has read the metadata (and for a live stream).
+    open var duration: CMTime { CMTime(_seconds: _state.duration) }
+    /// The video's size in pixels, `.zero` until known (and for audio).
+    open var presentationSize: CGSize { _state.presentationSize }
+    open var isPlaybackLikelyToKeepUp: Bool { _state.status == .readyToPlay }
+    open var isPlaybackBufferEmpty: Bool { _state.status != .readyToPlay }
+    open var isPlaybackBufferFull: Bool { false }
+    open var canPlayFastForward: Bool { true }
+    open var canPlaySlowForward: Bool { true }
+    open var canPlayReverse: Bool { false }
+    open var seekableTimeRanges: [NSValue] { [] }
+    open var loadedTimeRanges: [NSValue] { [] }
+
+    open func currentTime() -> CMTime {
+        CMTime(seconds: _player?.currentItem === self ? _player!._currentSeconds() : _time, preferredTimescale: 600)
+    }
+
+    /// Seeks this item (its player's, when it is current).
+    open func seek(to time: CMTime, completionHandler: (@Sendable (Bool) -> Void)? = nil) {
+        if let player = _player, player.currentItem === self {
+            player._seek(to: time, completion: completionHandler)
+        } else {
+            _time = _clamp(time.seconds)
+            completionHandler?(true)
+        }
+    }
+
+    open func seek(to time: CMTime, toleranceBefore: CMTime, toleranceAfter: CMTime, completionHandler: (@Sendable (Bool) -> Void)? = nil) {
+        seek(to: time, completionHandler: completionHandler)
+    }
+
+    open func cancelPendingSeeks() {}
+
+    open func step(byCount stepCount: Int) {}
+
+    /// A position within the item: not negative, and not past the end once that is known.
+    func _clamp(_ seconds: Double) -> Double {
+        guard seconds.isFinite else { return seconds > 0 ? (_state.duration ?? 0) : 0 }
+        var value = max(0, seconds)
+        if let duration = _state.duration { value = min(value, duration) }
+        return value
+    }
+
+    /// The page read the metadata.
+    func _ready(_ info: _AVMediaInfo) {
+        asset._learn(info)
+        if _state.duration != info.duration { _state.duration = info.duration }
+        let size = CGSize(width: info.width, height: info.height)
+        if _state.presentationSize != size { _state.presentationSize = size }
+        if _state.status != .readyToPlay { _state.status = .readyToPlay }
+    }
+
+    func _fail(_ error: any Error) {
+        _state.error = error
+        _state.status = .failed
+    }
+
+    // Notifications (AVFoundation's names and raw values).
+    public static let didPlayToEndTimeNotification = Notification.Name("AVPlayerItemDidPlayToEndTimeNotification")
+    public static let failedToPlayToEndTimeNotification = Notification.Name("AVPlayerItemFailedToPlayToEndTimeNotification")
+    public static let playbackStalledNotification = Notification.Name("AVPlayerItemPlaybackStalledNotification")
+    public static let timeJumpedNotification = Notification.Name("AVPlayerItemTimeJumpedNotification")
+    public static let newAccessLogEntryNotification = Notification.Name("AVPlayerItemNewAccessLogEntry")
+    public static let newErrorLogEntryNotification = Notification.Name("AVPlayerItemNewErrorLogEntry")
+}
+
+extension Notification.Name {
+    public static let AVPlayerItemDidPlayToEndTime = AVPlayerItem.didPlayToEndTimeNotification
+    public static let AVPlayerItemFailedToPlayToEndTime = AVPlayerItem.failedToPlayToEndTimeNotification
+    public static let AVPlayerItemPlaybackStalled = AVPlayerItem.playbackStalledNotification
+    public static let AVPlayerItemTimeJumped = AVPlayerItem.timeJumpedNotification
+    public static let AVPlayerItemNewAccessLogEntry = AVPlayerItem.newAccessLogEntryNotification
+    public static let AVPlayerItemNewErrorLogEntry = AVPlayerItem.newErrorLogEntryNotification
+}
+
+/// The `userInfo` key of `failedToPlayToEndTimeNotification`: the error.
+public let AVPlayerItemFailedToPlayToEndTimeErrorKey = "AVPlayerItemFailedToPlayToEndTimeErrorKey"
+
+// MARK: - AVPlayer
+
+/// Whether a player in a hidden page pauses; kept (the browser decides).
+public enum AVPlayerAudiovisualBackgroundPlaybackPolicy: Int, Sendable {
+    case automatic = 1, pauses, continuesIfPossible
+}
+
+/// Plays one item at a time in the views that show it (see the top of the file).
+open class AVPlayer: @unchecked Sendable {
+    public enum Status: Int, Sendable {
+        case unknown, readyToPlay, failed
+    }
+
+    public enum TimeControlStatus: Int, Sendable {
+        case paused, waitingToPlayAtSpecifiedRate, playing
+    }
+
+    public enum ActionAtItemEnd: Int, Sendable {
+        case advance, pause, none
+    }
+
+    public struct WaitingReason: RawRepresentable, Hashable, Sendable {
+        public let rawValue: String
+        public init(rawValue: String) { self.rawValue = rawValue }
+        public static let toMinimizeStalls = WaitingReason(rawValue: "AVPlayerWaitingToMinimizeStallsReason")
+        public static let evaluatingBufferingRate = WaitingReason(rawValue: "AVPlayerWaitingWhileEvaluatingBufferingRateReason")
+        public static let noItemToPlay = WaitingReason(rawValue: "AVPlayerWaitingWithNoItemToPlayReason")
+        public static let interstitialEvent = WaitingReason(rawValue: "AVPlayerWaitingDuringInterstitialEventReason")
+    }
+
+    public static let rateDidChangeNotification = Notification.Name("AVPlayerRateDidChangeNotification")
+    public static let rateDidChangeReasonKey = "AVPlayerRateDidChangeReasonKey"
+
+    let _state = _AVPlayerState()
+    /// When the position was last reported (or frozen), on `_clock`; nil unless playing.
+    private var stamp: Double?
+    private var periodicObservers: [_PeriodicTimeObserver] = []
+    private var pendingSeeks: [Int: @Sendable (Bool) -> Void] = [:]
+    weak var _looper: AVPlayerLooper?
+
+    /// Seconds on a monotonic clock, for extrapolating the position; tests replace it.
+    nonisolated(unsafe) static var _clock: () -> Double = {
+        let (seconds, attoseconds) = (ContinuousClock.now - _clockOrigin).components
+        return Double(seconds) + Double(attoseconds) / 1e18
+    }
+    private static let _clockOrigin = ContinuousClock.now
+
+    open var defaultRate: Float = 1
+    open var actionAtItemEnd: ActionAtItemEnd = .pause
+    open var automaticallyWaitsToMinimizeStalling = true
+    open var audiovisualBackgroundPlaybackPolicy: AVPlayerAudiovisualBackgroundPlaybackPolicy = .automatic
+    /// Kept; the page does not hold a wake lock.
+    open var preventsDisplaySleepDuringVideoPlayback = true
+    open var preventsAutomaticBackgroundingDuringVideoPlayback = true
+    open var allowsExternalPlayback = true
+    open var isExternalPlaybackActive: Bool { false }
+    open var usesExternalPlaybackWhileExternalScreenIsActive = false
+    open var appliesMediaSelectionCriteriaAutomatically = true
+    open var isOutputObscuredDueToInsufficientExternalProtection: Bool { false }
+    public static var eligibleForHDRPlayback: Bool { false }
+
+    public init() {}
+
+    public convenience init(url URL: URL) {
+        self.init(playerItem: AVPlayerItem(url: URL))
+    }
+
+    public init(playerItem item: AVPlayerItem?) {
+        _setItem(item)
+    }
+
+    // MARK: Item
+
+    open var currentItem: AVPlayerItem? { _state.item }
+
+    open func replaceCurrentItem(with item: AVPlayerItem?) {
+        _setItem(item)
+    }
+
+    func _setItem(_ item: AVPlayerItem?) {
+        guard item !== _state.item else { return }
+        freezeTime()
+        _state.item?._player = nil
+        item?._player = self
+        _state.item = item
+        // The new item plays from its own position.
+        resync()
+        if _state.rate != 0 { _state.timeControlStatus = .waitingToPlayAtSpecifiedRate }
+    }
+
+    /// The item ended with `actionAtItemEnd == .advance`: a plain player has
+    /// no next item (`AVQueuePlayer` overrides this).
+    func _advance() {
+        _setItem(nil)
+    }
+
+    open var status: Status {
+        switch _state.item?._state.status {
+        case .readyToPlay?: .readyToPlay
+        case .failed?: .failed
+        default: .unknown
+        }
+    }
+
+    open var error: (any Error)? { _state.item?._state.error }
+
+    // MARK: Rate
+
+    open var rate: Float {
+        get { _state.rate }
+        set { _setRate(newValue) }
+    }
+
+    open func play() { _setRate(defaultRate) }
+    open func pause() { _setRate(0) }
+
+    open func playImmediately(atRate rate: Float) { _setRate(rate) }
+
+    open var timeControlStatus: TimeControlStatus { _state.timeControlStatus }
+
+    open var reasonForWaitingToPlay: WaitingReason? {
+        guard _state.timeControlStatus == .waitingToPlayAtSpecifiedRate else { return nil }
+        return _state.item == nil ? .noItemToPlay : .toMinimizeStalls
+    }
+
+    private func _setRate(_ value: Float) {
+        guard value != _state.rate else { return }
+        freezeTime()
+        let wasPlaying = _state.rate != 0
+        _state.rate = value
+        if value == 0 {
+            setControlStatus(.paused)
+        } else if !wasPlaying {
+            setControlStatus(.waitingToPlayAtSpecifiedRate)
+        }
+        FoundationBridge.NotificationCenter.default.post(name: AVPlayer.rateDidChangeNotification, object: self)
+    }
+
+    private func setControlStatus(_ status: TimeControlStatus) {
+        guard _state.timeControlStatus != status else { return }
+        let wasPlaying = _state.timeControlStatus == .playing
+        freezeTime()
+        _state.timeControlStatus = status
+        if status == .playing { stamp = Self._clock() }
+        if wasPlaying != (status == .playing) { fireObservers(force: true) }
+    }
+
+    // MARK: Volume
+
+    open var isMuted: Bool {
+        get { _state.isMuted }
+        set { if newValue != _state.isMuted { _state.isMuted = newValue } }
+    }
+
+    /// 0…1, applied on top of mute.
+    open var volume: Float {
+        get { _state.volume }
+        set { if newValue != _state.volume { _state.volume = newValue } }
+    }
+
+    // MARK: Time
+
+    open func currentTime() -> CMTime {
+        guard _state.item != nil else { return .zero }
+        return CMTime(seconds: _currentSeconds(), preferredTimescale: 600)
+    }
+
+    /// The current item's position, extrapolated from the last report while playing.
+    func _currentSeconds() -> Double {
+        guard let item = _state.item else { return 0 }
+        guard let stamp, _state.timeControlStatus == .playing else { return item._time }
+        return item._clamp(item._time + (Self._clock() - stamp) * Double(_state.rate))
+    }
+
+    /// Fixes the extrapolated position as the item's (before a change of rate or status).
+    private func freezeTime() {
+        if let item = _state.item, stamp != nil { item._time = _currentSeconds() }
+        stamp = _state.timeControlStatus == .playing ? Self._clock() : nil
+    }
+
+    open func seek(to time: CMTime) {
+        _seek(to: time, completion: nil)
+    }
+
+    open func seek(to time: CMTime, completionHandler: @escaping @Sendable (Bool) -> Void) {
+        _seek(to: time, completion: completionHandler)
+    }
+
+    /// The page seeks to the nearest point it can; the tolerances are not applied.
+    open func seek(to time: CMTime, toleranceBefore: CMTime, toleranceAfter: CMTime) {
+        _seek(to: time, completion: nil)
+    }
+
+    open func seek(to time: CMTime, toleranceBefore: CMTime, toleranceAfter: CMTime, completionHandler: @escaping @Sendable (Bool) -> Void) {
+        _seek(to: time, completion: completionHandler)
+    }
+
+    @discardableResult
+    open func seek(to time: CMTime) async -> Bool {
+        await withCheckedContinuation { continuation in
+            _seek(to: time) { continuation.resume(returning: $0) }
+        }
+    }
+
+    @discardableResult
+    open func seek(to time: CMTime, toleranceBefore: CMTime, toleranceAfter: CMTime) async -> Bool {
+        await seek(to: time)
+    }
+
+    /// Moves the current item to `time`: the item's position changes at once,
+    /// and the page seeks the element that plays it. The completion runs with
+    /// true once the page has seeked (at once when no view shows the player),
+    /// with false when a later seek replaces it.
+    func _seek(to time: CMTime, completion: (@Sendable (Bool) -> Void)?) {
+        guard let item = _state.item, time.isValid else {
+            if let completion { Task { completion(false) } }
+            return
+        }
+        for (_, superseded) in pendingSeeks { superseded(false) }
+        pendingSeeks = [:]
+        item._time = item._clamp(time.seconds)
+        stamp = _state.timeControlStatus == .playing ? Self._clock() : nil
+        _state.seekTime = item._time
+        _state.seekSerial += 1
+        if let completion {
+            if _state.surfaces.isEmpty { Task { completion(true) } } else { pendingSeeks[_state.seekSerial] = completion }
+        }
+        FoundationBridge.NotificationCenter.default.post(name: AVPlayerItem.timeJumpedNotification, object: item)
+        fireObservers(force: true)
+    }
+
+    /// A seek to where the player is, for the view that takes over playing it.
+    private func resync() {
+        _state.seekTime = _state.item?._time ?? 0
+        _state.seekSerial += 1
+    }
+
+    // MARK: Time observers
+
+    /// Calls `block` every `interval` of playback (as the page reports the
+    /// position: about four times a second, or at `interval` when it is
+    /// shorter), and when playback starts, stops or seeks. The queue is
+    /// ignored: blocks run on the page's one thread.
+    open func addPeriodicTimeObserver(forInterval interval: CMTime, queue: FoundationBridge.DispatchQueue?,
+                                      using block: @escaping @Sendable (CMTime) -> Void) -> Any {
+        let observer = _PeriodicTimeObserver(interval: interval, block: block)
+        periodicObservers.append(observer)
+        updateReportInterval()
+        return observer
+    }
+
+    open func removeTimeObserver(_ observer: Any) {
+        guard let observer = observer as? _PeriodicTimeObserver else { return }
+        periodicObservers.removeAll { $0 === observer }
+        updateReportInterval()
+    }
+
+    private func updateReportInterval() {
+        let shortest = periodicObservers.map(\.seconds).filter { $0 > 0 && $0 < 0.25 }.min()
+        if _state.reportInterval != shortest { _state.reportInterval = shortest }
+    }
+
+    private func fireObservers(force: Bool) {
+        guard !periodicObservers.isEmpty, _state.item != nil else { return }
+        let now = _currentSeconds()
+        for observer in periodicObservers {
+            if !force, let last = observer.last, abs(now - last) < observer.seconds * 0.999 { continue }
+            observer.last = now
+            observer.block(CMTime(seconds: now, preferredTimescale: observer.timescale))
+        }
+    }
+
+    // MARK: Views
+
+    /// A view started showing the player: it plays it from here.
+    func _attach(_ surface: ObjectIdentifier) {
+        let previous = _state.surfaces.last
+        _state.surfaces.removeAll { $0 == surface }
+        _state.surfaces.append(surface)
+        if previous != surface {
+            freezeTime()
+            resync()
+        }
+    }
+
+    /// A view stopped showing the player.
+    func _detach(_ surface: ObjectIdentifier) {
+        guard let index = _state.surfaces.firstIndex(of: surface) else { return }
+        let wasActive = index == _state.surfaces.count - 1
+        _state.surfaces.remove(at: index)
+        guard wasActive else { return }
+        freezeTime()
+        for (_, completion) in pendingSeeks { completion(true) }
+        pendingSeeks = [:]
+        if _state.surfaces.isEmpty {
+            setControlStatus(_state.rate == 0 ? .paused : .waitingToPlayAtSpecifiedRate)
+        } else {
+            resync()
+        }
+    }
+
+    /// The `video` element's props for one of the views showing the player
+    /// (docs/ops-protocol.md, "Video and audio"). Read in the view's body, so
+    /// the view draws again when any of it changes (the position does not).
+    func _videoProps(surface: ObjectIdentifier, gravity: AVLayerVideoGravity, controls: Bool) -> _JSON {
+        let item = _state.item
+        let active = _state.surfaces.last == surface
+        let rate = _state.rate
+        var props: [String: _JSON] = [
+            "url": item?._state.pageURL.map(_JSON.string) ?? .null,
+            "playing": .bool(active && rate > 0 && item != nil && item?._state.status != .failed),
+            "muted": .bool(_state.isMuted || !active),
+            "volume": .number(Double(min(max(_state.volume, 0), 1))),
+            "rate": .number(Double(rate > 0 ? rate : max(defaultRate, 0.0625))),
+            "loop": .bool(_state.loops),
+            "gravity": .string(gravity._pageName),
+            "controls": .bool(controls),
+            "seek": .object(["time": .number(_state.seekTime), "serial": .number(Double(_state.seekSerial))]),
+        ]
+        if let interval = _state.reportInterval { props["report"] = .number(interval) }
+        if let size = item?._state.presentationSize, size.width > 0, size.height > 0 {
+            props["width"] = .number(Double(size.width))
+            props["height"] = .number(Double(size.height))
+        }
+        return .object(props)
+    }
+
+    /// A `video` event from the element of one of the views showing the player.
+    func _event(_ event: _JSON, from surface: ObjectIdentifier) {
+        guard case .object(let fields) = event, case .string(let kind)? = fields["event"] else { return }
+        func number(_ key: String) -> Double? {
+            if case .number(let value)? = fields[key], value.isFinite { return value }
+            return nil
+        }
+        let active = _state.surfaces.last == surface
+        guard let item = _state.item else { return }
+        // Events about another URL (the item changed since) are stale.
+        if case .string(let url)? = fields["url"], let pageURL = item._state.pageURL, url != pageURL { return }
+
+        switch kind {
+        case "ready":
+            let duration: Double? = if case .number(let value)? = fields["duration"], value.isFinite { value } else { nil }
+            item._ready(_AVMediaInfo(duration: duration, width: number("width") ?? 0, height: number("height") ?? 0))
+        case "error":
+            let error = AVError(Self.errorCode(number("code")), message: {
+                if case .string(let message)? = fields["message"], !message.isEmpty { return message }
+                return "the page could not play \(item._state.pageURL ?? "the item")"
+            }())
+            item._fail(error)
+            setControlStatus(.paused)
+            FoundationBridge.NotificationCenter.default.post(name: AVPlayerItem.failedToPlayToEndTimeNotification, object: item,
+                                                             userInfo: [AVPlayerItemFailedToPlayToEndTimeErrorKey: error])
+        case _ where !active:
+            // A view that does not play the player only reports metadata.
+            return
+        case "time":
+            guard let time = number("time") else { return }
+            let previous = item._time
+            item._time = item._clamp(time)
+            if _state.timeControlStatus == .playing { stamp = Self._clock() }
+            if _state.loops, let duration = item._state.duration, previous - time > duration / 2 {
+                // The element looped (`loop`): one more pass of the template item.
+                _looper?._looped()
+                FoundationBridge.NotificationCenter.default.post(name: AVPlayerItem.didPlayToEndTimeNotification, object: item)
+            }
+            fireObservers(force: false)
+        case "status":
+            if let time = number("time") { item._time = item._clamp(time) }
+            switch fields["status"] {
+            case .string("playing")?: if _state.rate != 0 { setControlStatus(.playing) }
+            case .string("waiting")?: if _state.rate != 0 { setControlStatus(.waitingToPlayAtSpecifiedRate) }
+            default: if _state.rate == 0 { setControlStatus(.paused) }
+            }
+        case "seeked":
+            if let serial = number("serial").map(Int.init), let completion = pendingSeeks.removeValue(forKey: serial) {
+                completion(true)
+            }
+        case "play":
+            // The viewer pressed play on the native controls.
+            if _state.rate == 0 { _setRate(defaultRate) }
+        case "pause":
+            // The viewer paused, or the browser refused to start (`blocked`:
+            // unmuted playback without a tap first).
+            if let time = number("time") { item._time = item._clamp(time) }
+            if _state.rate != 0 { _setRate(0) }
+        case "volume":
+            if case .bool(let muted)? = fields["muted"] { isMuted = muted }
+            if let value = number("volume") { volume = Float(value) }
+        case "rate":
+            if let value = number("rate"), value > 0, _state.rate != 0 { _setRate(Float(value)) }
+        case "ended":
+            if let duration = item._state.duration { item._time = duration } else if let time = number("time") { item._time = time }
+            stamp = nil
+            FoundationBridge.NotificationCenter.default.post(name: AVPlayerItem.didPlayToEndTimeNotification, object: item)
+            // An observer may have moved on already (seeked, replaced the item).
+            guard _state.item === item, item._time >= (item._state.duration ?? item._time) else { return }
+            switch actionAtItemEnd {
+            case .pause: _setRate(0)
+            case .advance: _advance()
+            case .none: setControlStatus(.paused)
+            }
+        default:
+            break
+        }
+    }
+
+    /// AVFoundation's error for an HTML `MediaError` code.
+    static func errorCode(_ code: Double?) -> AVError.Code {
+        switch code {
+        case 2?: .contentIsUnavailable
+        case 3?: .decodeFailed
+        case 4?: .fileFormatNotRecognized
+        default: .unknown
+        }
+    }
+}
+
+/// What `addPeriodicTimeObserver` returns.
+final class _PeriodicTimeObserver: @unchecked Sendable {
+    let seconds: Double
+    let timescale: CMTimeScale
+    let block: @Sendable (CMTime) -> Void
+    var last: Double?
+
+    init(interval: CMTime, block: @escaping @Sendable (CMTime) -> Void) {
+        seconds = interval.isNumeric ? max(interval.seconds, 0.001) : 1
+        // Times are reported at Core Media's video timescale at least.
+        timescale = max(interval.timescale, 600)
+        self.block = block
+    }
+}
+
+// MARK: - AVQueuePlayer
+
+/// A player of a list of items, one after another (`actionAtItemEnd` is `.advance`).
+open class AVQueuePlayer: AVPlayer, @unchecked Sendable {
+    private var queue: [AVPlayerItem] = []
+
+    public override init() {
+        super.init()
+        actionAtItemEnd = .advance
+    }
+
+    public override init(playerItem item: AVPlayerItem?) {
+        super.init(playerItem: item)
+        actionAtItemEnd = .advance
+    }
+
+    public init(items: [AVPlayerItem]) {
+        super.init(playerItem: items.first)
+        queue = Array(items.dropFirst())
+        actionAtItemEnd = .advance
+    }
+
+    open func items() -> [AVPlayerItem] {
+        (currentItem.map { [$0] } ?? []) + queue
+    }
+
+    open func advanceToNextItem() {
+        let next = queue.isEmpty ? nil : queue.removeFirst()
+        _setItem(next)
+    }
+
+    override func _advance() {
+        advanceToNextItem()
+    }
+
+    open func canInsert(_ item: AVPlayerItem, after afterItem: AVPlayerItem?) -> Bool {
+        !items().contains { $0 === item }
+    }
+
+    /// Inserts `item` after `afterItem`, or at the end when that is nil.
+    open func insert(_ item: AVPlayerItem, after afterItem: AVPlayerItem?) {
+        guard canInsert(item, after: afterItem) else { return }
+        if currentItem == nil {
+            _setItem(item)
+        } else if let afterItem, afterItem !== currentItem, let index = queue.firstIndex(where: { $0 === afterItem }) {
+            queue.insert(item, at: index + 1)
+        } else if let afterItem, afterItem === currentItem {
+            queue.insert(item, at: 0)
+        } else {
+            queue.append(item)
+        }
+    }
+
+    open func remove(_ item: AVPlayerItem) {
+        if item === currentItem {
+            advanceToNextItem()
+        } else {
+            queue.removeAll { $0 === item }
+        }
+    }
+
+    open func removeAllItems() {
+        queue.removeAll()
+        _setItem(nil)
+    }
+}
+
+// MARK: - AVPlayerLooper
+
+/// Plays an item over and over in a queue player: the page's element loops
+/// (`loop`), and each pass counts and posts `didPlayToEndTimeNotification`.
+/// Looping stops when the looper is released or disabled. `timeRange` is kept
+/// and not applied (the whole item loops).
+public final class AVPlayerLooper: @unchecked Sendable {
+    public enum Status: Int, Sendable {
+        case unknown, ready, failed, cancelled
+    }
+
+    private weak var player: AVQueuePlayer?
+    private let templateItem: AVPlayerItem
+    public let timeRange: CMTimeRange
+    public private(set) var loopCount = 0
+    private var disabled = false
+
+    public init(player: AVQueuePlayer, templateItem itemToLoop: AVPlayerItem,
+                timeRange loopRange: CMTimeRange = CMTimeRange(start: .zero, duration: .positiveInfinity)) {
+        self.player = player
+        templateItem = itemToLoop
+        timeRange = loopRange
+        player.removeAllItems()
+        player.insert(itemToLoop, after: nil)
+        player._looper = self
+        player._state.loops = true
+    }
+
+    public convenience init(player: AVQueuePlayer, templateItem itemToLoop: AVPlayerItem) {
+        self.init(player: player, templateItem: itemToLoop, timeRange: CMTimeRange(start: .zero, duration: .positiveInfinity))
+    }
+
+    public var status: Status {
+        if disabled { return .cancelled }
+        switch templateItem.status {
+        case .readyToPlay: return .ready
+        case .failed: return .failed
+        case .unknown: return .unknown
+        }
+    }
+
+    public var error: (any Error)? { templateItem.error }
+
+    /// The item each pass plays (the page replays the template itself).
+    public var loopingPlayerItems: [AVPlayerItem] { [templateItem] }
+
+    public func disableLooping() {
+        disabled = true
+        if let player, player._looper === self {
+            player._state.loops = false
+            player._looper = nil
+        }
+    }
+
+    func _looped() {
+        loopCount += 1
+    }
+
+    deinit {
+        if let player, player._looper == nil || player._looper === self {
+            player._state.loops = false
+        }
+    }
+}