Basic Player Configuration

Set VOD playback start position

The initial time (in milliseconds) from which player should start playback can be set using PlaybackProperties. This object should be passed to the PlayerBuilder.

const val INITIAL_PLAYBACK_TIME_MS = 0L // use preferred value here

val playbackPropertiesBuilder = PlaybackProperties.Builder()
playbackPropertiesBuilder.initialStartTimeMs(INITIAL_PLAYBACK_TIME_MS)

val playbackProperties = playbackPropertiesBuilder.build()

val player = PlayerBuilder()
    .mediaURL(url)
    .mediaType(MediaType.DASH)
    .drmScheme(DRMScheme.NONE)
    .playbackProperties(playbackProperties)
    .build(applicationContext)

For tweaking start position in live streams, refer Advanced player configuration.

Trick Play

The factor by which playback should be sped up.

/**
 * The factor by which playback should be sped up.
 * Must be greater than zero.
 * 1.0f indicates normal speed.
 */
player.playbackRateFactor = 2.0f  // Renders in 2X mode.

Configure forward and back seeking time interval

seeking forward

Seeks forward in the current content by Seek interval. Exoplayer's default value of 15000 milliseconds will be taken if no overridden values provided.

    const val DEFAULT_SEEK_FORWARD_INCREMENT_MS = 15000L // default value

val playbackPropertiesBuilder = PlaybackProperties.Builder()
playbackPropertiesBuilder.preferredSeekForwardIncrement(DEFAULT_SEEK_FORWARD_INCREMENT_MS)

val playbackProperties = playbackPropertiesBuilder.build()

val player = PlayerBuilder()
    .mediaURL(url)
    .mediaType(MediaType.DASH)
    .drmScheme(DRMScheme.NONE)
    .playbackProperties(playbackProperties)
    .build(applicationContext)

seeking back

Seeks back in the current content by Seek interval. Exoplayer's default value of 5000 milliseconds will be taken if no overridden values provided.

    const val DEFAULT_SEEK_BACK_INCREMENT_MS = 5000L // default value

val playbackPropertiesBuilder = PlaybackProperties.Builder()
playbackPropertiesBuilder.preferredSeekForwardIncrement(DEFAULT_SEEK_BACK_INCREMENT_MS)

val playbackProperties = playbackPropertiesBuilder.build()

val player = PlayerBuilder()
    .mediaURL(url)
    .mediaType(MediaType.DASH)
    .drmScheme(DRMScheme.NONE)
    .playbackProperties(playbackProperties)
    .build(applicationContext)

Subtitle Positioning

The vertical position of subtitles can be changed using subtitleBottomMarginPosition attribute.

// value below specifies bottom margin size to be set.
player.subtitleBottomMarginPosition = 100

The value set to this attribute will be set as bottom margin (extra space) on the bottom side of the subtitle view to position the subtitle as required.
This is typically used to raise the subtitle position above the playback controls when they become visible.

note

This space is outside this subtitle view's bounds. subtitleBottomMarginPosition value should be positive.

Play automatically when ready

The autoPlayOnLoad property of PlaybackProperties can be used to automatically start playing as soon as the player is ready. This is the equivalent of calling Player.play() directly without calling Player.load().
Default value is true.

val playbackPropertiesBuilder = PlaybackProperties.Builder()
playbackpropertiesBuilder.autoPlayOnLoad(true) //use preferred value here
// build PlaybackProperties and pass to PlayerBuilder

Resize Mode

Sets the aspect ratio of the video output. Default mode is FIT.

Name	Description
FIT	A resize mode that scales the content to fit within the surface rendering area, while maintaining the aspect ratio of the video source. The entire area is used only if the surface has the same aspect ratio as the video content, otherwise the content scales to the maximum size without cropping and is rendered at the center of the surface.
FILL	A resize mode that completely fills the surface rendering area, while maintaining the aspect ratio of the video source. The entire surface rendering area is always used and the video content outside of the surface gets cropped.
ZOOM	A resize mode that stretches the video to completely fill the surface rendering area. The entire surface rendering area is always used.

//Set the resize mode of choice
player.resizeMode = ResizeMode.ZOOM

Thumbnail Preview

Thumbnail Preview is a functionality that allows users to see a preview image of the video while seeking.

The Player uses a series of images woven into a sprite from a given URL which is used to retrieve the corresponding image for a given playhead position.

Setup Thumbnail Preview

ThumbnailPreviewConfig

ThumbnailPreviewConfig describes the dimensions and duration of each image in a given sprite. These values can be obtained from the property keyframeMetadata of ContentAuthorizationToken. Additionally, it also holds other properties that dictate the image caching strategy.

Name	Type	Required?	Description
noOfcolumns	Int	Yes	The number of columns in each sprite image.
noOfRows	Int	Yes	The number of rows in each sprite image.
keyFrameDuration	Int	Yes	The time (in seconds) that each thumbnail in each sprite image corresponds to.
thumbnailWidth	Int	Yes	The width (in pixels) of each thumbnail in each sprite image.
thumbnailHeight	Int	Yes	The height (in pixels) of each thumbnail in each sprite image.
isPrefetchRequired	Boolean?	No	Indicates whether the sprite images should be downloaded even before the user starts seeking, which can help in smoother performance. Default value is True.
shouldDeleteFromDiskOnExit	Boolean?	No	Indicates whether the sprite images in the disk cache should be cleared on exiting the player or not. Default value is True.

val keyframeMetadata = contentAuthorizationToken.keyframeMetadata
val isPrefetchRequired = true // Preferred configuration
val shouldDeleteFromDiskOnExit = true // Preferred configuration
val thumbnailPreviewConfig = ThumbnailPreviewConfig(
    keyframeMetadata.numberOfColumns,
    keyframeMetadata.numberOfRows,
    keyframeMetadata.thumbnailHeight,
    keyframeMetadata.thumbnailWidth,
    (keyframeMetadata.thumbnailFrequency * 1000).toLong(),
    isPrefetchRequired, // Optional
    shouldDeleteFromDiskOnExit // Optional
)

note

The thumbnailFrequency obtained from KeyframeMetadata should be converted from seconds (Int) to milliseconds (Long) before creating the ThumbnailPreviewConfig instance.

Pass information to PlayerBuilder

Thumbnail Preview is an optional feature that can be opted into by passing the required information to thumbnailPreviewProperties of the corresponding PlayerBuilder (See Player creation) instance.

Name	Type	Required?	Description	Default Value
spriteURL	String	Yes	The fully formed sprite image URL that combines the endpoint URL and generic name, which includes the flag ~index~. Player calculates the sprite index based on given position and replaces ~index~ with the index to construct the sprite URL.	N/A
maxConcurrentThumbnailDownloads	Int?	No	The maximum number of concurrent sprite image downloads allowed.	Number of processors on the device
thumbnailPreviewConfig	ThumbnailPreviewConfig?	No	The ThumbnailPreviewConfig instance that holds the required metadata for sprite images.	noOfColumns = 10 noOfRows = 10 thumbnailWidth = 384 thumbnailHeight = 216 keyframeDuration = 6000L isPrefetchRequired = true shouldDeleteFromDiskOnExit = true

playerBuilder.thumbnailPreviewProperties(
    spriteURL,
    maxConcurrentThumbnailDownloads,
    thumbnailPreviewConfig
)

Implement Thumbnail Preview

The thumbnail preview image for a particular position can be obtained by calling the getThumbnail extension API on the Player instance. The API returns the preview image for the given position in the form of a Bitmap.

Parameter	Type	Description
positionMs	Long	The position of the playhead for which the thumbnail is to be retrieved, in milliseconds.
thumbnailHandler	(Bitmap?) -> Unit	The callback function that returns a Bitmap of the thumbnail or null in case of any error / insufficient memory.

var thumbnail: Bitmap?
val thumbnailView: View = findViewById(R.id.thumbnail_view) //The UI component to display the thumbnail
player.getThumbnail(position) { preview -> 
    thumbnail = preview
}
thumbnailView.setImageBitmap(thumbnail) // Display thumbnail as required on the UI thread

This function is typically called in tandem with a scrub bar listener attached to the Player which listens to all the seeking activity from the user.

note

All the image downloads and the thumbnailHandler run on the IO thread. Thus, the handler should not be used to update the UI directly.