OTVVideoView Class Reference

Detailed Description

Replaces the android.widget.VideoView class

OTVVideoView class is used to control playback of audio/video files and streams. The OTVVideoView class can load video streams from various sources (such as resources or content providers), takes care of computing its measurement from the video so that it can be used in any layout manager, and provides various display options such as scaling and tinting.

Note: OTVVideoView does not retain its full state when going into the background. In particular, it does not restore the current play state and play position. Applications should save and restore these on their own in onSaveInstanceState(Bundle) and onRestoreInstanceState(Bundle).
Integrators should consider listening to configuration changes - android.app.Activity.onConfigurationChanged(Configuration newConfig).
See also Handling the configuration change yourself in the Android Developers site.

Inherits RelativeLayout, MediaPlayerControl, and OTVPlayerInterface.

Classes
interface	OnScalingModeChangedListener
	Interface definition of a callback to be invoked when scale mode are changed. More...

Public Member Functions
	OTVVideoView ()
	Default Constructor. More...
	OTVVideoView (Context context)
	Simple constructor to use when creating a view from code. More...
	OTVVideoView (Context context, AttributeSet attrs)
	Constructor that is called when inflating a view from XML. More...
	OTVVideoView (Context context, AttributeSet attrs, int defStyle)
	Perform inflation from XML and apply a class-specific base style from a theme attribute. More...
void	addExoEventListener (Player.Listener listener)
	Used to add listener to the player to be notified of changes in player states. More...
void	addMetadataOutput (OTVVideoView.OnMetadataOutput listener)
	Used to add listener to the player to be notified of metadata output from the player. More...
Timeline	getCurrentTimeline ()
	Returns the current timeline of a valid player object. More...
String	toString ()
	Returns a string containing a concise, human-readable description of this object. More...
void	setMediaDrmCallback (OTVMediaDrmCallback mediaDrmCallback)
	Set the media DRM callback object. More...
void	setVideoPath (@NonNull String path)
	Sets the video path. More...
void	setVideoPath (@NonNull String path, int contentType)
	Sets the video path with content type. More...
void	setVideoURI (@NonNull Uri uri)
	Sets the video uri. More...
void	setVideoURI (@NonNull Uri uri, int contentType)
	Sets the video uri with content type. More...
void	setAndroidTVPreviewSurface (@Nullable Surface surface)
	Sets the surface for player draws video directly on it This is designed to preview video on android home screen via TvInputService The caller is responsible for tracking the lifecycle of the surface, and must clear the surface by calling. More...
boolean	setVideoPathFromDownloadItem (OTVDownloadItem xDownloadItem)
	Instruct the player to play back the content associated with the OTVDownloadItem. More...
boolean	addSubtitleSource (String url, String mimeType, String language)
	Adds an external subtitle source to the content. More...
void	start ()
	Starts playback Valid States: PLAYING, PLAYBACK_COMPLETE. More...
void	pause ()
	Pauses playback Valid States: PLAYING. More...
void	resume ()
	Resumes paused content Valid States: PAUSED. More...
void	stopPlayback ()
	Stop playback and destroy player. More...
long[]	getSeekableRangeInfo ()
	This method returns the range of the current content that can seek. More...
int	getDuration ()
	Get the duration of the content. More...
int	getCurrentPosition ()
	Get the current playback position More...
int	getBufferPercentage ()
	Gets the current buffer percentage. More...
void	seekTo (int msec)
	Tells the player to seek to a specific time. More...
void	selectTrack (int index)
	Selects and activates the track referenced by index. More...
void	deselectTrack (int index)
	Deactivates the current caption. More...
OTVTrackInfo[]	getOTVTrackInfo ()
	Returns an array of track information objects. More...
void	setOnPreparedListener (OnPreparedListener listener)
	Register a callback to be invoked when the media file is loaded and ready to go. More...
void	setOnCompletionListener (OnCompletionListener listener)
	Register a callback to be invoked when the end of a media file has been reached during playback. More...
void	setOnInfoListener (OnInfoListener listener)
	Register a callback to be invoked when an informational event occurs during playback or setup. More...
void	setOnErrorListener (MediaPlayer.OnErrorListener listener)
	Register a callback to be invoked when an error occurs during playback or setup. More...
void	setOnSeekCompleteListener (OnSeekCompleteListener listener)
	Register a callback to be invoked when a seek operation has been completed. More...
void	addOnVideoSizeChangedListener (OnVideoSizeChangedListener listener)
	Add a callback to be invoked when the video size is known or updated. More...
void	removeOnVideoSizeChangedListener (OnVideoSizeChangedListener listener)
	Remove a callback to be invoked when the video size is known or updated. More...
boolean	isPlaying ()
	Check if content is currently playing back. More...
void	setDebugLogs (int protocolLog, int playbackCoreLog, int rendererLog)
boolean	canPause ()
	Check if the content being played can be paused. More...
boolean	canSeekBackward ()
	Check if the content being played can seek backwards. More...
boolean	canSeekForward ()
	Check if the content being played can seek forwards. More...
int	getMaxBandwidth ()
	Get the maximum bandwidth. More...
int	getBufferSize ()
	Gets the buffer size. More...
int	getSourceTimeout ()
	Get the source timeout for a playback, in seconds. More...
void	setMaxBandwidth (int bandwidth)
	Set the maximum bandwidth for content playback, in bits per second. More...
void	setSourceTimeout (int timeout)
	Set the source timeout for a playback, in seconds. More...
void	setMediaController (MediaController xController)
	Sets the media controller to be used by the VideoView to interface with playback. More...
void	seekIFrameTo (long xSeekTimeMs)
	Seek IFrame thumbnail to given position. More...
void	setVolume (float leftVolume, float rightVolume)
	Sets the audio volume, with 0 being silence and 1 being unity gain. More...
void	setMaxResolution (int width, int height)
	Set the maximum video width and height for content playback. More...
Pair< Integer, Integer >	getMaxResolution ()
	Get the maximum video width and height for content playback. More...
void	setVideoScalingMode (int mode)
	Sets video scaling mode. More...
int	getVideoScalingMode ()
	Returns the video scaling mode that the player is using. More...
void	addOTVMetadataListener (OTVMetadataListener xListener)
	Register an OTVMetadataListener callback to be invoked when metadata changed. More...
void	removeOTVMetadataListener (OTVMetadataListener xListener)
	Remove an OTVMetadataListener listener. More...
void	setThumbnailListener (IOTVThumbnailListener xListener, int xBandwidth)
	Set the thumbnail listener to the SDK. More...
void	setThumbnailListener (IOTVThumbnailListener xListener)
	Set the thumbnail listener to the SDK. More...
void	setPlayerConfiguration (@NonNull OTVPlayerConfiguration xConfig)
	Set player configuration. More...
OTVPlayerConfiguration	getPlayerConfiguration ()
	Get player configuration. More...
void	resetPlayerConfiguration ()
	Reset player configuration. More...
void	setMutualAuthentication (SSLSocketFactory sslSocketFactory)
	sets the mutual authentication for Manifest or segment downloads. More...
void	setVolumeGain (int xTargetGain)
	Amplify the volume of the content. More...
int	getVolumeGain ()
	Gets the current volume gain setting. More...

Constructor & Destructor Documentation

OTVVideoView

(

)

Default Constructor.

OTVVideoView

(

Context

context

)

Simple constructor to use when creating a view from code.

Parameters

context

the app context to create videoView

OTVVideoView	(	Context	context,
		AttributeSet	attrs
	)

Constructor that is called when inflating a view from XML.

Parameters

context	the app context to create videoView
attrs	the attributes to initialize the videoview

OTVVideoView	(	Context	context,
		AttributeSet	attrs,
		int	defStyle
	)

Perform inflation from XML and apply a class-specific base style from a theme attribute.

Parameters

context	the app context to create videoView
attrs	the attributes to initialize the videoview
defStyle	the style of view

Member Function Documentation

void addExoEventListener

(

Player.Listener

listener

)

Used to add listener to the player to be notified of changes in player states.

Parameters

listener

the Player.EventListener object

void addMetadataOutput

(

OTVVideoView.OnMetadataOutput

listener

)

Used to add listener to the player to be notified of metadata output from the player.

Parameters

listener

the MetadataOutput object

void addOnVideoSizeChangedListener

(

OnVideoSizeChangedListener

listener

)

Add a callback to be invoked when the video size is known or updated.

Parameters

listener

the callback that will be added

void addOTVMetadataListener

(

OTVMetadataListener

xListener

)

Register an OTVMetadataListener callback to be invoked when metadata changed.

Parameters

xListener

the listener object

boolean addSubtitleSource	(	String	url,
		String	mimeType,
		String	language
	)

Adds an external subtitle source to the content.

An external subtitle/caption source can be added to the content to play back via this method. Currently only SRT subs are supported.

Parameters

url	the remote url of the subtitles
mimeType	the mime type of the subtitles (must be "application/x-subrip" currently)
language	the language identifier of the subtitles (will appear in subtitle track selection)

Returns

false if no video path/url has been set or the url/mime type is invalid, true otherwise

boolean canPause

(

)

Check if the content being played can be paused.

Returns

true if content can be paused, false otherwise States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

boolean canSeekBackward

(

)

Check if the content being played can seek backwards.

Returns

true if content can be seek backwards, false otherwise Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

boolean canSeekForward

(

)

Check if the content being played can seek forwards.

Returns

true if content can be seek forwards, false otherwise Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

void deselectTrack

(

int

index

)

Deactivates the current caption.

Parameters

index

the index of the track to deactivate Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

int getBufferPercentage

(

)

Gets the current buffer percentage.

Returns

the buffer percentage.

Remarks

Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

Note

This method is not implemented yet. Always return 0

int getBufferSize

(

)

Gets the buffer size.

Returns

The maximum buffer size for the content in second.
Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

Note

This method is not implemented yet. Always return 0

int getCurrentPosition

(

)

Get the current playback position

Returns

the current playback position in milliseconds
Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

after an onSeekComplete callback, the current position may take up to a second to update to the accurate position

Timeline getCurrentTimeline

(

)

Returns the current timeline of a valid player object.

This method should only be invoked after the playback starts. It will return null if the player is null.

int getDuration

(

)

Get the duration of the content.

Returns

the duration of the content in milliseconds
Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

int getMaxBandwidth

(

)

Get the maximum bandwidth.

0 means no maximum bandwidth limit.

Returns

the capped bitrate, in bits/second.

Pair<Integer, Integer> getMaxResolution

(

)

Get the maximum video width and height for content playback.

A width or height of 0 means no maximum is set.

Returns

the capped resolution, in a pair of width x height pixels.

OTVTrackInfo [] getOTVTrackInfo

(

)

Returns an array of track information objects.

Returns

Array of track info. The total number of tracks is the array length. Must be called again if MEDIA_INFO_METADATA_UPDATE of MEDIA_INFO has been called.
Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

OTVPlayerConfiguration getPlayerConfiguration

(

)

Get player configuration.

return current play configuration. see OTVPlayerConfiguration

long [] getSeekableRangeInfo

(

)

This method returns the range of the current content that can seek.

This method is used to allow OTVVideoView to support timeshifting playback within Live Streaming content. Based on the amount of content available from the server at a particular time, it determines the seek range within the playing content which also indicates the range where playback may be timeshifted.

This range will be constantly shifting as the live streaming content available from the server changes in real time, so this method will need to be repeatedly called to ensure accurate shifting of playback.

For VOD content this method will always return the same two values, and the second value indicating the end of the seek range, but this method is most relevant when playing live streaming content.

Returns

An array of two longs in milliseconds, the first long being the timestamp indicating the start of the seek range, and the second being the timestamp indicating the end of the seek range.
return null means that the player can't get the seek range information now.
Valid States: PREPARED, PLAYING, PAUSE, PLAYBACK_COMPLETE

int getSourceTimeout

(

)

Get the source timeout for a playback, in seconds.

This timeout value specifies how long the player waits (in seconds) when no media data is received.

Returns

int, the timeout in seconds

0 - no timeout (infinity)

>0 - timeout in seconds

<0 - not available or not implemented
If you call this method before playing the stream, it returns -1. If you call it after a stream starts playing but before calling setSourceTimeout, it returns the default value. If it returns -1 after the stream starts playing, it means the stream type does not support setting a timeout.

Note

This method is not implemented yet. Always return 0

See Also

setSourceTimeout

int getVideoScalingMode

(

)

Returns the video scaling mode that the player is using.

The supported video scaling modes are:

• MediaPlayer::VIDEO_SCALING_MODE_SCALE_TO_FIT: The content is scaled to the surface dimensions
• MediaPlayer::VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING: The content is scaled, maintaining its aspect ratio, the whole surface area is used, content may be cropped

Returns

video scaling mode

int getVolumeGain

(

)

Gets the current volume gain setting.

Returns

The current volume gain. Between MIN_VOLUME_GAIN and MAX_VOLUME_GAIN.

boolean isPlaying

(

)

Check if content is currently playing back.

Returns

true if content is currently playing back, false if it is not or no content is loaded
Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

void pause

(

)

Pauses playback
Valid States: PLAYING.

void removeOnVideoSizeChangedListener

(

OnVideoSizeChangedListener

listener

)

Remove a callback to be invoked when the video size is known or updated.

Parameters

listener

the callback that will be removed

void removeOTVMetadataListener

(

OTVMetadataListener

xListener

)

Remove an OTVMetadataListener listener.

Parameters

xListener

the listener need be removed.

void resetPlayerConfiguration

(

)

Reset player configuration.

This method should be called before setVideoPath() The default player configuration will be used after configuration is reset.

void resume

(

)

Resumes paused content
Valid States: PAUSED.

void seekIFrameTo

(

long

xSeekTimeMs

)

Seek IFrame thumbnail to given position.

Deprecated:

Use OTVIFrameThumbnailView#seekTime(long).

void seekTo

(

int

msec

)

Tells the player to seek to a specific time.

Parameters

msec	The time, in milliseconds, to seek to. Limited to the range returned from getSeekableRangeInfo() Valid States: PREPARED, PLAYING, PAUSE, PLAYBACK_COMPLETE

void selectTrack

(

int

index

)

Selects and activates the track referenced by index.

Note: Must have got the track info first by calling getOTVTrackInfo()

Parameters

index

the index of the track to activate Valid States: PREPARED, PLAYING, PAUSED, PLAYBACK_COMPLETE

void setAndroidTVPreviewSurface

(

@Nullable Surface

surface

)

Sets the surface for player draws video directly on it This is designed to preview video on android home screen via TvInputService The caller is responsible for tracking the lifecycle of the surface, and must clear the surface by calling.

setAndroidTVPreviewSurface(null) 

if the surface is destroyed.

Parameters

surface

surface that player needs to draw video directly onto

void setDebugLogs	(	int	protocolLog,
		int	playbackCoreLog,
		int	rendererLog
	)

Parameters

protocolLog	The level of logs to be generated related to protocols, as an integer.
playbackCoreLog	The level of logs to be generated related to playback core, as an integer.
rendererLog	The level of logs to be generated related to rendering, as an integer.

Deprecated:

please use OTVLog.setLogLevel() sets the debugging log levels related to protocols,

void setMaxBandwidth

(

int

bandwidth

)

Set the maximum bandwidth for content playback, in bits per second.

When set, the SDK will prevent the player from obtaining content streams above this bandwidth limit. If a playlist does not have any streams available with this limit, the lowest bandwidth stream will be used for playback.

Setting a maximum bandwidth of 0 or negative values will remove the limit.

The maximum bandwidth will remain in place until setMaxBandwidth is called again, or until the OTVVideoView is disposed of.

Parameters

bandwidth

the bandwidth, in bits/second, to cap the content.

void setMaxResolution	(	int	width,
		int	height
	)

Set the maximum video width and height for content playback.

When set, the SDK will prevent the player from obtaining content streams above this video resolution. If a playlist does not have any streams available with this limit, the lowest resolution stream will be used for playback.

Setting a maximum video width and height of 0 or negative values will remove the limit.

The maximum resolution will remain in place until setMaxResolution is called again, or until the OTVMediaPlayer is disposed of.

Parameters

width	the video width.
height	the video height.

void setMediaController

(

MediaController

xController

)

Sets the media controller to be used by the VideoView to interface with playback.

Parameters

xController

the MediaController object to be used

void setMediaDrmCallback

(

OTVMediaDrmCallback

mediaDrmCallback

)

Set the media DRM callback object.

This is only required when using Widevine or PlayReady DRM. For Nagra DRM (PRM or Connect) the callback is set through either OTVPRMManager or OTVConnectManager.

Parameters

mediaDrmCallback

the media drm callback object

void setMutualAuthentication

(

SSLSocketFactory

sslSocketFactory

)

sets the mutual authentication for Manifest or segment downloads.

Parameters

sslSocketFactory

SSLSocketFactory instance.

void setOnCompletionListener

(

OnCompletionListener

listener

)

Register a callback to be invoked when the end of a media file has been reached during playback.

Parameters

listener

The callback that will be run

void setOnErrorListener

(

MediaPlayer.OnErrorListener

listener

)

Register a callback to be invoked when an error occurs during playback or setup.

Parameters

listener

The callback that indicate an error will be run:

• boolean onError(MediaPlayer mp, int what, int extra):
  

• mp the OTVMediaPlayer the error pertains to
  

• what the type of error that has occurred:
  
  • OTVMediaPlayer.MEDIA_ERROR_UNKNOWN
  • OTVMediaPlayer.MEDIA_ERROR_SERVER_DIED
  • OTVMediaPlayer.MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK
  extra an extra code, specific to the error. Typically implementation dependent.

void setOnInfoListener

(

OnInfoListener

listener

)

Register a callback to be invoked when an informational event occurs during playback or setup.

Parameters

listener

The callback that indicate an info or a warning, will be run:

-boolean onInfo(MediaPlayer mp, int what, int extra):

• mp the MediaPlayer the info pertains to
  

• what the type of info or warning
  

• extra an extra code, specific to the info. Typically implementation dependent
  

void setOnPreparedListener

(

OnPreparedListener

listener

)

Register a callback to be invoked when the media file is loaded and ready to go.

Parameters

listener

The callback that will be run

void setOnSeekCompleteListener

(

OnSeekCompleteListener

listener

)

Register a callback to be invoked when a seek operation has been completed.

Parameters

listener

the callback that will be run

void setPlayerConfiguration

(

@NonNull OTVPlayerConfiguration

xConfig

)

Set player configuration.

This method should be called before setVideoPath() The default player configuration will be used if configuration isn't set

Parameters

xConfig

the OTVPlayerConfiguration object. see OTVPlayerConfiguration

void setSourceTimeout

(

int

timeout

)

Set the source timeout for a playback, in seconds.

For supported stream types, this specifies how long the player waits when no media data is received. For unsupported stream types, this timeout value is ignored.

Parameters

timeout

0 - no timeout (infinity)

>0 - timeout in seconds

<0 - not allowed (stream type does not support setting a timeout)

Remarks

If you call this method before playing the stream, the value will only be set after setVideoPath.

Note

This method is not implemented yet.

See Also

getSourceTimeout

void setThumbnailListener	(	IOTVThumbnailListener	xListener,
		int	xBandwidth
	)

Set the thumbnail listener to the SDK.

Setting a new listener / null overrides the previous listener and its handle will be released. The thumbnails provided will be the lowest available bandwidth representation

Parameters

xListener	the listener object
xBandwidth	the preferred bandwidth (bits per thumbnail duration). The playew will attempt to pick the thumbnail with the closest advertised bandwidth.

void setThumbnailListener

(

IOTVThumbnailListener

xListener

)

Set the thumbnail listener to the SDK.

Setting a new listener / null overrides the previous listener and its handle will be released. The thumbnails provided will be the lowest available bandwidth representation

Parameters

xListener

the listener object

void setVideoPath

(

@NonNull String

path

)

Sets the video path.

Parameters

path	the String based path to the content to be played back.

void setVideoPath	(	@NonNull String	path,
		int	contentType
	)

Sets the video path with content type.

It is a recommended API if the stream content type is known.

Parameters

path	the String based path to the content to be played back.
contentType	indicate the stream content type. The available values are: OTVContentType#CONTENT_TYPE_HLS OTVContentType#CONTENT_TYPE_DASH OTVContentType#CONTENT_TYPE_PROGRESSIVE_MP4 Error message MediaPlayer.MEDIA_ERROR_MALFORMED will be received if content type is invalid

boolean setVideoPathFromDownloadItem

(

OTVDownloadItem

xDownloadItem

)

Instruct the player to play back the content associated with the OTVDownloadItem.

Parameters

xDownloadItem

the OTVDownloadItem associated with the content to be played back

Returns

true if the OTVDownloadItem is ready to be played back false if the OTVDownloadItem is not ready to be played back (current OTVDownloadItem state is not STATE_SUCCESSFUL. TO REVIEW AND UPDATE)

Note

if the content associated with the OTVDownloadItem passed is encrypted and there are

void setVideoScalingMode

(

int

mode

)

Sets video scaling mode.

To make the target video scaling mode effective during playback, this method must be called after data source is set. If not called, the default video scaling mode is MediaPlayer::VIDEO_SCALING_MODE_SCALE_TO_FIT.

The supported video scaling modes are:

• MediaPlayer::VIDEO_SCALING_MODE_SCALE_TO_FIT: The content is scaled to the surface dimensions
• MediaPlayer::VIDEO_SCALING_MODE_SCALE_TO_FIT_WITH_CROPPING: The content is scaled, maintaining its aspect ratio, the whole surface area is used, content may be cropped

Parameters

mode	target video scaling mode. Most be one of the supported video scaling modes; otherwise, IllegalArgumentException will be thrown.

void setVideoURI

(

@NonNull Uri

uri

)

Sets the video uri.

Parameters

uri	the Uri of the content to be played back.

void setVideoURI	(	@NonNull Uri	uri,
		int	contentType
	)

Sets the video uri with content type.

It is a recommended API if the stream content type is known.

Parameters

uri	the Uri of the content to be played back.
contentType	indicate the stream content type. The available values are: OTVContentType#CONTENT_TYPE_HLS OTVContentType#CONTENT_TYPE_DASH OTVContentType#CONTENT_TYPE_PROGRESSIVE_MP4 Error message MediaPlayer.MEDIA_ERROR_MALFORMED will be received if content type is invalid

void setVolume	(	float	leftVolume,
		float	rightVolume
	)

Sets the audio volume, with 0 being silence and 1 being unity gain.

Parameters

leftVolume	The left channel audio volume.
rightVolume	The right channel audio volume.

void setVolumeGain

(

int

xTargetGain

)

Amplify the volume of the content.

The default value is MIN_VOLUME_GAIN which means the volume won't be amplified. The maximum value is MAX_VOLUME_GAIN.

Parameters

xTargetGain

The volume gain, between MIN_VOLUME_GAIN and MAX_VOLUME_GAIN

void start

(

)

Starts playback
Valid States: PLAYING, PLAYBACK_COMPLETE.

void stopPlayback

(

)

Stop playback and destroy player.

String toString

(

)

Returns a string containing a concise, human-readable description of this object.