State & Events

Every PlayerProtocol implementation keeps its internal state and offers a way to register listener objects to listen to important events.

Player state

The player state can be retrieved with player.state and, similar to our recorder component, matches one of the constants in the PlayerState class:

State	Description	Has content	Is playing
PlayerState.idle	Player has no Video content.	false	false
PlayerState.paused(buffering: Bool)	Player has content, which might be ready to play depending on the buffering flag. However, player is currently paused - use play() or toggle() to change.	true	false
PlayerState.playing(buffering: Bool)	Player has content and was asked to play it. Depending on the buffering flag, it might be downloading more data or not.	true	check the Bool flag

Player events

All PlayerProtocol events are dispatched to a PlayerObserver that was previously registered using addObserver or similar function.

player.addObserver(observer) // start listening (weak reference)
player.removeObserver(observer) // stop listening

Observers are very important to be up-to-date about the player state, handle errors and create a responsive UI. We describe the observer interface as comments in the interface description below.

class CustomPlayerObserver : PlayerObserver {

    func playerStateChanged(_ state: PlayerState) {
        // Player state has changed
    }

    func playerError(_ error: Error) {
        // Some error was encountered. Likely playback was stopped as a consequence.
    }

    func playerPlaybackReady() {
        // Player content is ready to be played using play()
    }

    func playerPlaybackFinished() {
        // The playback has reached the end of the content.
    }

    func playerSubtitleChanged(_ text: String?) {
        // Called for subtitled videos when player asks to show the given string of text.
    }

    func playerVideoChanged(video: Video?) {
        // The current video being played has changed.
    }

    func playerDurationChanged(duration: TimeInterval) {
        // The content duration has changed, likely because content itself
        // has changed. This can be used to display a duration UI element.
    }

    func playerPositionChanged(position: TimeInterval) {
        // The playback position has changed. This is invoked many times during
        // playback to implement a smooth UI seekbar, for example.
    }

    func playerMutedChanged(muted: Bool) {
        // The player.muted value has been changed. Useful for reactive UI.
    }

    func playerAspectModeChanged(aspectMode: AspectMode) {
        // The player.aspectMode value has been changed. Useful for reactive UI.
    }
}