State & Events

Every io.video.videokit.player.Player 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 io.video.videokit.player.PlayerState class:

State	Description	Has content	Is playing
PlayerState.IDLE	Player has no content.	false	false
PlayerState.BUFFERING	Player has content and will play it as soon as buffering is finished.	true	true
PlayerState.PLAYING	Player has content and is playing it.	true	true
PlayerState.PAUSED	Player has content and is ready to play it as soon as play() is called.	true	false
PlayerState.PAUSED_BUFFERING	Player has content but it is ready to play it.	true	false

Player events

All Player events are dispatched to a io.video.videokit.player.PlayerListener that was previously registered using addListener.

player.addListener(lifecycle, listener) // start listening, stops automatically

player.addListener(listener) // start listening
player.removeListener(listener) // stop listening

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

interface PlayerListener {
    // Player state has changed - see constants in the State class.
    fun onStateChanged(@PlayerState.Value state: Int) = Unit

    // Playback failed due to some error.
    fun onError(error: VideoError) = Unit

    // The content duration has changed, likely because content itself
    // has changed. This can be used to display a duration UI element.
    fun onDurationChanged(durationMs: Long) = Unit

    // The playback position has changed. This is invoked many times during
    // playback to implement a smooth UI seekbar, for example.
    fun onPositionChanged(positionMs: Long) = Unit

    // The playback buffered position has changed. This is invoked many times
    // as the video is being played and loaded, and can be shown in a UI element.
    fun onBufferedPositionChanged(bufferedPositionMs: Long) = Unit

    // The player.mute value has been changed.
    fun onMuteChanged(mute: Boolean) = Unit

    // The content is ready to be played using play().
    fun onPlaybackReady() = Unit

    // The playback has reached the end of the content.
    fun onPlaybackFinished() = Unit
}