Concepts

The entry point for the player SDK is the io.video.videokit.player.Player interface. This interface provides functions to control video playback, content, position and rendering.

It also collects important events and dispatches them to subscribers that were registered with the addObserver or similar functions, or, for coroutine users, collectors of one of the exposed flows. We recommend listening at least to the error event:

val player: Player = ...
player.addObserver(object : Player.Observer {
    override fun onError(error: VideoKitException) {
        // handle error!
    }
})

We provide different implementations that can be used within your app depending on your needs, but all of them share the same API surface described below.

Player interface

Playback control

Playback is controlled through simple play and pause functions.

// Starts playback of previously added content
fun play()

// Pauses playback of previously added content
fun pause()

// Calls play if paused, pause if playing
fun toggle()

// Like pause(), but the content position is reset to 0
fun stop()

Content control

All player implementations can play a single Video object, a list of Videos or a Playlist. As soon as the content is set through set (regardless of the play flag), it starts being buffered and prepared for playback.

// Stops playback and sets new content, which will be buffered.
// If play is true, starts playing as soon as possible.
fun set(video: Video, play: Boolean)

fun set(videos: List<Video>, play: Boolean)
fun set(videos: List<Video>, index: Int, play: Boolean)

fun set(playlist: Playlist, play: Boolean)
fun set(playlist: Playlist, index: Int, play: Boolean)

// Stops playback and clears any content that was previously added
// through `set` functions.
fun reset()

Position control

At any given time, you can retrieve the content duration, the current playback position and the bufferedPosition, which is the position of the last video frame available for playback. Buffering will proceed efficiently as the content is played.

We also offer seek* functions to change the current position.

// The duration of the current content in milliseconds
val duration: Long

// the current playback position in milliseconds
val position: Long

// the current buffered position in milliseconds
val bufferedPosition: Long

// seeks to the given position in milliseconds
fun seek(to: Long)

// seeks forward by an amount that depends on the video duration
fun seekForward()

// seeks backward by an amount that depends on the video duration
fun seekBackward()

Other options

We also offer a few extra options that can be used to configure the player:

• aspectMode: either AspectMode.Fill, AspectMode.Crop or AspectMode.Letterbox.
• loopMode: whether the video should be re-played once it ends.
• mute: whether the audio is muted or not.
• playbackQuality: either PlaybackQuality.Auto() (recommended) or a fixed value (PlaybackQuality.Fixed(rendition = ...)).
• speed: a Float controlling the playback speed.
• rotationMode: whether to rotate video based on the device magnetometer.

There are also more advanced options which are less frequently used. These can be found by checking the interface ABI.

var aspectMode: AspectMode

var playbackQuality: PlaybackQuality

var loopMode: LoopMode

var mute: Boolean

var speed: Float

var rotationMode: RotationMode