Concepts

Using the player SDK means interacting with 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 addListener* functions.

We recommend listening at least to the error event:

val player: Player = ...
player.addListener(lifecycle, object : PlayerListener {
    override fun onError(error: VideoError) {
        // 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

Note: if you use the default controls, the user will be able to control the player through the user interface, so there's no need to interact directly with most of these functions.

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.CENTER_CROP or AspectMode.CENTER_INSIDE.
• loop: whether the video should be re-played once it ends.
• mute: whether the audio is muted or not.
• playbackQuality: either Quality.AUTO (recommended) or a fixed value (Quality.FIXED_144P, Quality.FIXED_240P, Quality.FIXED_360P, Quality.FIXED_540P, Quality.FIXED_720P).
• useHls: a boolean to enable or disable HLS playback, true by default (recommended).

var aspectMode: Int

var playbackQuality: Int

var useHls: Boolean

var loop: Boolean

var mute: Boolean

Note that when playbackQuality and useHls are changed, any Playlist that is being played should also be modified accordingly, as you can read in the playlist documentation. This ensures that playlist preloading matches the video renditions that will be actually used by the player.