tencent cloud

TXVodPlayer
Download PDF
Last updated: 2025-05-30 15:00:37
TXVodPlayer
Last updated: 2025-05-30 15:00:37
Download PDF

Introducing the TXVodPlayer API

TXVodPlayer is a core playback class, primarily responsible for playback, suspension, and playback speed control. For the full capability of the player, please see Player SDK Feature Description.

API Overview

Basic Playback API

API
Description
Play an HTTP URL-formatted address. Starting from version 10.7, `startPlay` has been changed to `startVodPlay`. You need to call `TXLiveBase#setLicence` to set the License before successful playback; otherwise, playback will fail (resulting in a black screen). The License only needs to be set globally once. Live stream License, short video License, and player License can all be used. If you have not obtained the above License yet, you can click Player License to apply. An official License requires purchase.
Play in fileId format, pass in TXPlayInfoParams parameter. Starting from version 10.7, startPlay is changed to startVodPlay. You must call {@link TXLiveBase#setLicence} to set the Licence before successful playback; otherwise, playback will fail (black screen). The Licence only needs to be set globally once. Live stream Licence, short video Licence, and player Licence can all be used. If you have not obtained the above Licence yet, you can click Player License to apply. The official license requires purchase.
Play DRM-encrypted video.
stopPlay
Stop playback.
isPlaying
Whether it is playing.
pause
Pause playback Stop retrieving streaming data Retain the last frame
resume
Resume playback. Re-fetch streaming data.
seek
Navigate to the specified time point in the video stream, in seconds.
seek
Navigate to the specified time point in the video stream, in seconds, with precision up to 3 decimal places.
Retrieve the current playback position, in seconds.
Retrieve the total duration of the cache, in seconds.
Retrieve the total duration, in seconds.
Retrieve the playable duration, in seconds.
getWidth
Get video width.
getHeight
Retrieve video height.
Set whether to autoplay after startPlay, default is autoplay.
Set playback start time.
setToken
Encrypt the token for HLS.
Retrieve the encryption key for secure encrypted playback.
setLoop
Set whether to loop playback.
isLoop
Return whether the playback loop status is enabled.
Add external subtitle (only supported in player premium).
Return subtitle track information list (only supported in player premium).
Return audio track information list (only supported in player premium).
Select track (only supported in player premium).
Cancel track selection (only supported in player premium).
Navigate to a specified PDT (Program Date Time) time point in the video stream, enabling features such as fast-forward, rewind, and progress bar jumping. Currently only supports HLS video format (starting from player premium version 11.6).
Parameter unit: milliseconds (ms).

Player Configuration API

API
Description
setConfig
Set player configuration information. For configuration details, please see TXVodPlayConfig.
Set the video rendering TXCloudVideoView for the player.
Set the video rendering TextureView for the player.
Set the video rendering Surface for the player.
Set the player's business parameters, with the parameter format as <String,Object>.
Set subtitle style information. Subtitle styles can be updated after playback (only supported in player premium).
Set the subtitle rendering target object View (only supported in player premium).
Set volume equalization and loudness range. Default values can be filled in (related classes or files: Android: TXVodConstants; iOS: TXVodPlayConfig.h).
{Turn off: AUDIO_NORMALIZATION_OFF}
{On: AUDIO_NORMALIZATION_ON}
AUDIO_NORMALIZATION_STANDARD
AUDIO_NORMALIZATION_LOW
AUDIO_NORMALIZATION_HIGH
Custom value can be filled in: ranging from -70 to 0 LUFS.

Video-Related Interfaces

API
Description
Enable or disable video hardware decoding.
snapshot
Retrieve the current video frame.
Note: Since retrieving the current frame image is a time-consuming operation, the screenshot will be returned via an asynchronous callback.
setMirror
Set the image.
setRate
Set the playback speed of on-demand video, default is 1.0.
Return the bitrate index of current playback.
When the playback address is HLS, return the list of supported bitrates (resolutions).
Set the bitrate index of the currently playing content. Switch resolution seamlessly. Clarity switching may require a short while.
Set the switchable highest bitrate for adaptive playback.

Audio-Related Interfaces

API
Description
setMute
Set whether to mute playback.
Set volume level, range: 0 - 100.
Set whether to automatically obtain audio focus. Default is automatic obtain.

Event Notification API

API
Description
Set video subtitle text data output callback.
Set player event callback.

TRTC Playback-Related APIs

Through the following interfaces, you can push the audio and video stream of a VOD player via TRTC. For more TRTC services, please see the TRTC product overview.
API
Description
Bind VOD to TRTC service.
Unbind VOD from TRTC service.
Start pushing video stream.
Cancel pushing video stream.
Start pushing audio stream.
Cancel pushing audio stream.

API Detail

TXVodPlayer

Create a video-on-demand (VOD) player instance.
public TXVodPlayer(Context context)
Parameter Description
Parameter Name
Type
Description
context
Context
System

startVodPlay

Start playing through URL.
Starting from version 10.7, you need to pass through XLiveBase#setLicence to set the Licence only after which successful playback can be achieved; otherwise, playback will fail (screen goes black). The global setting only needs to be done once.
public int startVodPlay(String playUrl)
Parameter Description
Parameter Name
Type
Description
playUrl
String
Playback address.
Return Value
0: Playback success.
Playback failure.

startVodPlay

Start playing through Tencent Cloud fileId.
Starting from version 10.7, you need to pass through XLiveBase#setLicence to set the Licence only after which successful playback can be achieved; otherwise, playback will fail (screen goes black). The global setting only needs to be done once.
public void startVodPlay(TXPlayInfoParams playInfoParams)
Parameter Description
Parameter Name
Type
Description
playInfoParams
TXPlayInfoParams
System
Return Value
0: Playback success.
Playback failure.

startPlayDrm

Play Drm-encrypted video.
Starting from version 10.7, you need to pass through XLiveBase#setLicence to set the Licence only after which successful playback can be achieved; otherwise, playback will fail (screen goes black). The global setting only needs to be done once.
Notes:
Note: Only supported in player premium.
public int startPlayDrm(TXPlayerDrmBuilder playerDrmBuilder)
Parameter Description
Parameter Name
Type
Description
playerDrmBuilder
TXPlayerDrmBuilder
Playback information for Drm.
Return Value
0: Playback success.
Non-zero: playback failure.

stopPlay

Stop playback.
public int stopPlay(boolean isNeedClearLastImg)
Parameter Description
Parameter Name
Type
Description
isNeedClearLastImg
boolean
Whether to clear the last frame.
true: Clear the last frame. It is recommended to clear when stopping playback normally.
false: Retain the last frame.

isPlaying

Whether it is playing.
public boolean isPlaying()

pause

Pause playback.
public void pause()

resume

Resume playback.
public void resume()

seek

Navigate to the specified time point in the video stream.
public void seek(int time)
Parameter Description
Parameter Name
Type
Description
time
int
Video stream time point, in seconds.
Return Value

seek

Navigate to the specified time point in the video stream.
public void seek(float time)
Parameter Description
Parameter Name
Type
Description
time
float
Video stream time point, in seconds, with precision up to 3 decimal places.

seek

Navigate to the specified time point in the video stream.
public void seek(float timeInSeconds, boolean isAccurateSeek)
Parameter Description
Parameter Name
Type
Description
timeInSeconds
float
Video stream time point, in seconds, with precision up to 3 decimal places.
isAccurateSeek
boolean
Whether it is precise Seek.
true: Indicates precise Seek, must find the current time point, which may take longer.
false: Indicates imprecise Seek, that is, searching for the previous I-frame.

seekToPdtTime

Navigate to the specified time point in the video stream.
Notes:
Note: Player Premium version 11.6 or later is supported.
public void seekToPdtTime(long pdtTimeMs)
Parameter Description
Parameter Name
Type
Description
pdtTimeMs
long
Video stream PDT time point, in milliseconds.

getCurrentPlaybackTime

Retrieve the current playback time point, in seconds.
public float getCurrentPlaybackTime()

getBufferDuration

Retrieve the total duration of the cache, in seconds.
public float getBufferDuration()

getDuration

Retrieve the total video duration, in seconds.
public float getDuration()

getPlayableDuration

Retrieve the currently playable video duration, in seconds.
public float getPlayableDuration()

getWidth

Get video width.
public int getWidth()

getHeight

Retrieve video height.
public int getHeight()

setAutoPlay

Set whether to autoplay after startPlay. Default is autoplay.
public void setAutoPlay(boolean autoPlay)

setStartTime

Set playback start time, in seconds, need to be set before starting playing.
public void setStartTime(float pos)
Parameter Description
Parameter Name
Type
Description
pos
float
Video stream time point, in seconds, with precision up to 3 decimal places.

setToken

Set encryption HLS token. After setting this value, the player automatically adds voddrm.token before the file name in the URL.
public void setToken(String token)

getEncryptedPlayKey

Retrieve the encryption key for secure encrypted playback.
public static String getEncryptedPlayKey(final String key)

setLoop

Set whether to loop playback. Default is non-loop playback.
public void setLoop(boolean loop)

isLoop

Whether to loop playback.
public void setLoop(boolean loop)

addSubtitleSource

Add external subtitle.
Note: Only supported in player premium.
public void addSubtitleSource(@NonNull String url, @NonNull String name, String mimeType)
Parameter Description
Parameter Name
Type
Description
url
String
Subtitle address, supports Http link and local storage absolute path.
name
String
Subtitle name. If adding multiple subtitles, set the subtitle names to different names to distinguish them from other added subtitles; otherwise, it may result in subtitle selection error.
mimeType
String
Subtitle type, only supports VVT and SRT format.
VTT format: TXVodConstants#VOD_PLAY_MIMETYPE_TEXT_SRT
SRT format: TXVodConstants#VOD_PLAY_MIMETYPE_TEXT_VTT

getSubtitleTrackInfo

Return subtitle track information list.
Note:
Only supported in player premium.
public List<TXTrackInfo> getSubtitleTrackInfo()
Return Value
List<TXTrackInfo>: subtitle track information list.

getAudioTrackInfo

Return audio track information list.
Note:
Only supported in player premium.
public List<TXTrackInfo> getAudioTrackInfo()
Return Value
List<TXTrackInfo>: audio track information list.

selectTrack

Select a track.
Note:
Only supported in player premium.
public void selectTrack(int trackIndex)
Parameter Description
Parameter Name
Type
Description
trackIndex
int
Track index, obtained via TXTrackInfo#getTrackIndex.

deselectTrack

Cancel track selection.
Note:
Only supported in player premium.
public void deselectTrack(int trackIndex)
Parameter Description
Parameter Name
Type
Description
trackIndex
int
Track index, obtained via TXTrackInfo#getTrackIndex.

setConfig

Set player configuration information. Refer to TXVodPlayConfig.
public void setConfig(TXVodPlayConfig config)
Parameter Description

setPlayerView

Set the video rendering TXCloudVideoView for the player. It is only valid when set before starting playback.
public void setPlayerView(TXCloudVideoView glRootView)
Parameter Description
Parameter Name
Type
Description
glRootView
TXCloudVideoView
video rendering View.

setPlayerView

Set the video rendering TextureRenderView for the player, which is only valid before starting playback.
public void setPlayerView(TextureRenderView glRootView)
Parameter Description
Parameter Name
Type
Description
glRootView
TextureRenderView
video rendering View.

setSurface

Set the video rendering Surface for the player, which is only valid before starting playback.
public void setSurface(Surface surface)

setStringOption

Set the player's business parameters, with the parameter format as <String,Object>.
public void setStringOption(String key, Object value)

setSubtitleStyle

Set subtitle style information. Supports configuration before playback and allows updating subtitle styles after playback.
Note:
Only supported in player premium.
public void setSubtitleStyle(TXSubtitleRenderModel renderModel)
Parameter Description
Parameter Name
Type
Description
renderModel
Subtitle style configuration parameters.

setSubtitleView

Set the subtitle rendering target object View.
Note:
Only supported in player premium.
public void setSubtitleView(TXSubtitleView subtitleView)
Parameter Description
Parameter Name
Type
Description
subtitleView
TXSubtitleView
The subtitle rendering target object View provided by player SDK.

setAudioNormalization

Set volume balance, loudness range: -70 ~ 0 (LUFS).
Note:
Only supported in player premium.
public void setAudioNormalization(float value)
Parameter Description
Parameter Name
Type
Description
value
float
Preset value can be filled in (related class or file: Android: TXVodConstants; iOS: TXVodPlayConfig.h)
Turn off: AUDIO_NORMALIZATION_OFF
On: AUDIO_NORMALIZATION_ON
AUDIO_NORMALIZATION_STANDARD
AUDIO_NORMALIZATION_LOW
AUDIO_NORMALIZATION_HIGH
Custom value can be filled in: ranging from -70 to 0 LUFS.

setAutoMaxBitrate

Set the switchable highest bitrate for adaptive playback.
public void setAutoMaxBitrate(int autoMaxBitrate)

enableHardwareDecode

Enable or disable video hardware decoding. Hardware decoding is enabled by default.
public boolean enableHardwareDecode(boolean enable)

snapshot

Retrieve the current video frame.
public void snapshot(TXLivePlayer.ITXSnapshotListener listener)
Parameter Description
Parameter Name
Type
Description
listener
public interface ITXSnapshotListener {
void onSnapshot(Bitmap bmp);
}
Callback interface class for screenshots.

setMirror

Set mirror video.
public void setMirror(boolean mirror)

setRate

Set the playback speed of on-demand video, default is 1.0.
public void setRate(float rate)

getBitrateIndex

Return the bitrate index of current playback.
public TXVodPlayer(Context context)

getSupportedBitrates

When the playback address is HLS, return the list of supported bitrates (resolutions).
public ArrayList<TXBitrateItem> getSupportedBitrates
Return Value
ArrayList<TXBitrateItem>: Bitrate list.

setBitrateIndex

Set the bitrate index of the currently playing content. Tencent Cloud supports multi-bitrate HLS fragment alignment to ensure the best experience. When switching resolution seamlessly, clarity switching may require a short while.
public void setBitrateIndex(int index) {
Parameter Description
Parameter Name
Type
Description
index
int
Bitrate index.
index == -1 indicates enabling HLS adaptive bitrate streaming.
index > 0 means manually switching to the corresponding clarity bitrate. The index value can be obtained through the API TXVodPlayer#getSupportedBitrates.

setRenderMode

Set the player's Image Tiling Mode.
public void setRenderMode(int mode)
Parameter Description
Parameter Name
Type
Description
mode
int
Image Tiling Mode, valid values:
TXVodConstants#RENDER_MODE_FULL_FILL_SCREEN: Fill the video footage to the entire screen, scale the image proportionally to cover the whole screen, and crop the excess part. In this mode, there is no black border on the screen.
TXVodConstants#RENDER_MODE_ADJUST_RESOLUTION: Adapt the video footage to the screen, scale the image proportionally, ensure the scaled width and height do not exceed the display area, display it centered, and may leave a black border.

setRenderRotation

Set the image rendering angle of the player.
public void setRenderRotation(int rotation)
Parameter Description
Parameter Name
Type
Description
context
Context
Image rendering angle, valid values:
TXVodConstants#RENDER_ROTATION_PORTRAIT: portrait
TXVodConstants#RENDER_ROTATION_LANDSCAPE: Rotate 90 degrees clockwise.

setMute

Set whether to mute playback. Default is unmuted playback.
public void setMute(boolean mute)

setAudioPlayoutVolume

Set volume level, range: 0 - 100.
public void setAudioPlayoutVolume(int volume)

setRequestAudioFocus

Set whether to automatically obtain audio focus. Default is automatic obtain.
false can be passed in, then the business manages audio focus itself.
public boolean setRequestAudioFocus(boolean requestFocus)

setVodSubtitleDataListener

Set video subtitle text data output callback.
public void setVodSubtitleDataListener(ITXVodPlayListener.ITXVodSubtitleDataListener listener)
Parameter Description
Parameter Name
Type
Description
listener
Subtitle text data callback API.

setVodListener

Create a video-on-demand (VOD) player instance.
public void setVodListener(ITXVodPlayListener listener)
Parameter Description
Parameter Name
Type
Description
listener
Player event callback API.

attachTRTC

Bind VOD to TRTC service.
public void attachTRTC(Object trtcCloud)

detachTRTC

Unbind VOD from TRTC service.
public void detachTRTC()

publishVideo

Start pushing video stream.
public void publishVideo()

unpublishVideo

Cancel pushing video stream.
public void unpublishVideo()

publishAudio

Start pushing audio stream.
public void publishAudio()

unpublishAudio

Cancel pushing audio stream.
public void unpublishAudio()

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback