tencent cloud

All product documents
Video on Demand
VOD Scenario
Last updated: 2025-04-02 14:50:12
VOD Scenario
Last updated: 2025-04-02 14:50:12

Limits

1. To try out all features of the player, we recommend you activate VOD. If you don't have an account yet, sign up for one first. If you don't use the VOD service, you can skip this step; however, you will only be able to use basic player features after integration.
2. Download and install Android Studio. If you have already done so, skip this step.

This Document Describes

How to integrate the Tencent Cloud Player SDK for Android.
How to use the Player SDK for VOD playback.
How to use the underlying capabilities of the Player SDK to implement more features.

SDK Integration

Step 1. Integrate the SDK ZIP file

Download and integrate the SDK ZIP file as instructed in Integration Guide.

Step 2. Configure the license

If you have obtained a license, you can view the license URL and key in the VOD console.
If you don't have the required license yet, you can get it as instructed in Adding and Renewing a License.
After obtaining the License information, you need to initialize and configure the License before calling the relevant interfaces of the SDK. For detailed tutorials, please see Configuring View License.

Step 3. Add a view

The SDK provides TXCloudVideoView for video rendering by default. First, add the following code to the layout XML file:
<com.tencent.rtmp.ui.TXCloudVideoView
android:id="@+id/video_view"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:layout_centerInParent="true"
android:visibility="gone"/>

Step 4. Create a player object

Create the TXVodPlayer object and use the setPlayerView API to associate the object with the video_view control just added to the UI.
// `mPlayerView` is the video rendering view added in step 3
TXCloudVideoView mPlayerView = findViewById(R.id.video_view);
// Create a player object
TXVodPlayer mVodPlayer = new TXVodPlayer(getActivity());
// Associate the player object with the video rendering view
mVodPlayer.setPlayerView(mPlayerView);

Step 5. Start playback

TXVodPlayer supports two playback modes for you to choose as needed:
Through URL
Through FileId
TXVodPlayer will internally recognize the playback protocol automatically. You only need to pass in your playback URL to the startVodPlay function.
// Play back a video resource at a URL
String url = "http://1252463788.vod2.myqcloud.com/xxxxx/v.f20.mp4";
mVodPlayer.startVodPlay(url);


// Play back a local video resource
String localFile = "/sdcard/video.mp4";
mVodPlayer.startVodPlay(localFile);

// Starting from version 11.8, the player supports content:// URI video resources and asset catalog video resources
// Play content:// URI video resources
String localFile = "content://xxx/xxx/video.mp4";
mVodPlayer.startVodPlay(localFile);

// Play asset catalog video resources, the passed address must start with asset://
String localFile = "asset://video.mp4";
mVodPlayer.startVodPlay(localFile
// We recommend you use the following new API:
// `psign` is a player signature. For more information on the signature and how to generate it, see [Player Signature](https://intl.cloud.tencent.com/document/product/266/38099).
TXPlayInfoParams playInfoParam = new TXPlayInfoParams(1252463788, // `appId` of the Tencent Cloud account
"4564972819220421305", // `fileId` of the video
"psignxxxxxxx"); // The player signature
mVodPlayer.startVodPlay(playInfoParam);

// Legacy API, which is not recommended
TXPlayerAuthBuilder authBuilder = new TXPlayerAuthBuilder();
authBuilder.setAppId(1252463788);
authBuilder.setFileId("4564972819220421305");
mVodPlayer.startVodPlay(authBuilder);
Find the target video file in Media Assets, and you can view the FileId below the filename.
Play back the video through the FileId, and the player will request the backend for the real playback URL. If the network is abnormal or the FileId doesn't exist, the TXLiveConstants.PLAY_ERR_GET_PLAYINFO_FAIL event will be received; otherwise, TXLiveConstants.PLAY_EVT_GET_PLAYINFO_SUCC will be received, indicating that the request succeeded.

Step 6. Stop playback

Remember to terminate the view control when stopping the playback, especially before the next call of startVodPlay. This can prevent memory leak and screen flashing issues.
In addition, when exiting the playback UI, you need to call the onDestroy() function for the rendering view. This can prevent memory leak and "Receiver not registered" alarms.
@Override
public void onDestroy() {
super.onDestroy();
mVodPlayer.stopPlay(true); // `true` indicates to clear the last-frame image
mPlayerView.onDestroy();
}
Note:
The boolean parameter of stopPlay indicates whether to clear the last-frame image. Early versions of the live player of the RTMP SDK don't have an official pause feature; therefore, this boolean value is used to clear the last-frame image.
If you want to retain the last-frame image after VOD stops, simply do nothing after receiving the playback stop event; playback will stop at the last frame by default.

Basic Feature Usage

1. Playback control

Starting playback

// Start playback
mVodPlayer.startVodPlay(url)

Pausing playback

// Pause the video
mVodPlayer.pause();

Resuming playback

// Resume the video
mVodPlayer.resume();

Stopping playback

// Stop the video
mVodPlayer.stopPlay(true);

Adjusting playback progress (seek)

When the user drags the progress bar, seek can be called to start playback at the specified position. The Player SDK supports accurate seek.
int time = 600; // In seconds if the value is of `int` type
// float time = 600; // In seconds if the value is of `float` type
// Adjust the playback progress
mVodPlayer.seek(time);

Precise and Imprecise Seek

Starting from version 11.8 of the player SDK, it is supported to specify precise or imprecise seek when calling the seek interface.
float time = 600; // Unit is seconds for float type
// Adjust progress
mVodPlayer.seek(time, true); // Precise seek
mVodPlayer.seek(time, false); // Imprecise seek

Seek to the specified Program Date Time (PDT) point in the video stream

To seek to the specified Program Date Time (PDT) point in the video stream, which enables functions such as fast-forward, rewind, and progress bar jumping, currently only HLS video format is supported.
Note:
Starting from version 11.6 of the player's premium edition, this function is supported.
long pdtTimeMs = 600; // Unit is milliseconds
mVodPlayer.seekToPdtTime(time);

Specifying playback start time

You can specify the playback start time before calling startVodPlay for the first time.
float startTimeInSecond = 60; // Unit: Second
mVodPlayer.setStartTime(startTimeInSecond); // Set the playback start time
mVodPlayer.startVodPlay(url);

2. Image adjustment

view: size and position You can modify the size and position of video images by adjusting the size and position of the video_view control added in the Add a view step during SDK integration.
setRenderMode: Aspect fill or aspect fit
Value
Definition
RENDER_MODE_FULL_FILL_SCREEN
Images are scaled to fill the entire screen, and the excess parts are cropped. There are no black bars in this mode, but images may not be displayed entirely.
RENDER_MODE_ADJUST_RESOLUTION
Images are scaled so that the long side of the video fits the screen. Neither side exceeds the screen after scaling. Images are centered, and there may be black bars visible.
setRenderRotation: Image rotation
Value
Definition
RENDER_ROTATION_PORTRAIT
Normal playback (the Home button is below the video image)
RENDER_ROTATION_LANDSCAPE
Clockwise rotation of the image by 270 degrees (the Home button is on the left of the video image)
// Fill the screen at the original aspect ratio
mVodPlayer.setRenderMode(TXLiveConstants.RENDER_MODE_FULL_FILL_SCREEN);
// Normal playback (the Home button is below the video image)
mVodPlayer.setRenderRotation(TXLiveConstants.RENDER_ROTATION_PORTRAIT);

3. Adjustable-Speed playback

The VOD player supports adjustable-speed playback. You can use the setRate API to set the VOD playback speed, such as 0.5x, 1.0x, 1.2x, and 2x speed.
// Set playback at 1.2X rate
mVodPlayer.setRate(1.2);

4. Playback loop

// Set playback loop
mVodPlayer.setLoop(true);
// Get the current playback loop status
mVodPlayer.isLoop();

5. Muting/Unmuting

// Mute or unmute the player. true: Mute; false: Unmute
mVodPlayer.setMute(true);

6. Screencapturing

Call snapshot to take a screenshot of the current video frame. This method captures only the video frame. To capture the UI, use the corresponding API of the Android system.
// Take a screenshot
mVodPlayer.snapshot(new ITXSnapshotListener() {
@Override
public void onSnapshot(Bitmap bmp) {
if (null != bmp) {
// Get the screenshot bitmap
}
}
});

7. Roll image ad

The Player SDK allows you to add roll images on the UI for advertising as follows:
If autoPlay is set to NO, the player will load the video normally but will not immediately start playing it back.
Users can see the roll image ad on the player UI after the player is loaded and before the video playback starts.
When the ad display stop conditions are met, the resume API will be called to start video playback.
mVodPlayer.setAutoPlay(false); // Set manual playback
mVodPlayer.startVodPlay(url); // The video will be loaded after `startVodPlay` is called and won't be played back automatically after being loaded successfully.
// ......
// Display the ad on the player UI
// ......
mVodPlayer.resume(); // Call `resume` to start playing back the video after the ad display ends

8. HTTP-REF

headers in TXVodPlayConfig can be used to set HTTP request headers, such as the Referer field commonly used to prevent the URL from being copied arbitrarily (Tencent Cloud provides a more secure signature-based hotlink protection solution) and the Cookie field for client authentication
TXVodPlayConfig mPlayConfig = new TXVodPlayConfig();
Map<String, String> headers = new HashMap<>();
headers.put("Referer", "${Refer Content}");
mPlayConfig.setHeaders(headers);
mVodPlayer.setConfig(mPlayConfig);

9. Hardware acceleration

It is extremely difficult to play back videos of the Blu-ray (1080p) or higher image quality smoothly if only software decoding is used. Therefore, if your main scenario is game live streaming, we recommend you use hardware acceleration.
Before switching between software and hardware decoding, you need to call stopPlay first. After the switch, you need to call startVodPlay; otherwise, severe blurs will occur.
mVodPlayer.stopPlay(true);
mVodPlayer.enableHardwareDecode(true);
mVodPlayer.startVodPlay(flvUrl, type);

10. Definition settings

The SDK supports the multi-bitrate format of HLS, so users can switch between streams at different bitrates to switch the video definition. You can set the definition as follows:
// Get the array of multiple bitrates. The TXBitrateItem class fields mean: index - bitrate index; width - video width; height - video height; bitrate - video bitrate
ArrayList<TXBitrateItem> bitrates = mVodPlayer.getSupportedBitrates();
int index = bitrates.get(i).index; // Specify the bitrate index to be played
mVodPlayer.setBitrateIndex(index); // Switch the bitrate to the desired clarity

// Get the index of the currently played bitrate. The return value of -1000 is the default value, indicating that no bitrate has been set; the return value of -1 indicates that adaptive streaming is enabled
int index = mVodPlayer.getBitrateIndex();
During playback, you can call mVodPlayer.setBitrateIndex(int) at any time to switch the bitrate. During the switch, the data of another stream will be pulled. The SDK is optimized for Tencent Cloud multi-bitrate files to implement smooth switching.
If you know the resolution information of the video stream in advance, you can specify the video resolution to be played before starting playback to avoid switching streams after playback. For detailed methods, refer to Player Configuration#Specifying Resolution Before Playback.

11. Adaptive bitrate streaming

The SDK supports adaptive bitrate streaming of HLS. After this capability is enabled, the player can dynamically select the most appropriate bitrate for playback based on the current bandwidth. You can enable adaptive bitrate streaming as follows:
mVodPlayer.setBitrateIndex(-1); // Pass in `-1` for the `index` parameter
During playback, you can call mVodPlayer.setBitrateIndex(int) at any time to switch to another bitrate. After the switch, adaptive bitrate streaming will be disabled.

12. Enabling smooth bitrate switch

Before starting playback, you can enable smooth bitrate switch to seamlessly switch between different definitions (bitrates) during playback. If smooth bitrate switch is enabled, the transition between different bitrates will be smoother but will be more time-consuming. Therefore, this feature can be configured as needed.
TXVodPlayConfig mPlayConfig = new TXVodPlayConfig();
// If it is set to `true`, the bitrate can be switched smoothly when IDR frames are aligned. If it is set to `false`, multi-bitrate URLs are opened faster.
mPlayConfig.setSmoothSwitchBitrate(true);
mVodPlayer.setConfig(mPlayConfig);

13. Playback progress listening

There are two metrics for the VOD progress: loading progress and playback progress. Currently, the SDK notifies the two progress metrics in real time through event notifications. For more information on the event notification content, see Event Listening.
You can bind a TXVodPlayerListener listener to the TXVodPlayer object, and the progress notification will be called back to your application through the PLAY_EVT_PLAY_PROGRESS event. The event information contains the above two progress metrics.
mVodPlayer.setVodListener(new ITXVodPlayListener() {
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
if (event == TXLiveConstants.PLAY_EVT_PLAY_PROGRESS) {
// Loading progress in ms
int playable_duration_ms = param.getInt(TXLiveConstants.EVT_PLAYABLE_DURATION_MS);
mLoadBar.setProgress(playable_duration_ms); // Set the loading progress bar

// Playback progress in ms
int progress_ms = param.getInt(TXLiveConstants.EVT_PLAY_PROGRESS_MS);
mSeekBar.setProgress(progress_ms); // Set the playback progress bar

// Total video duration in ms
int duration_ms = param.getInt(TXLiveConstants.EVT_PLAY_DURATION_MS);
// It can be used to set duration display, etc.
// Get the PDT time. This function is supported starting from version 11.6 of the player's advanced edition.
long pdt_time_ms = param.getLong(TXVodConstants.EVT_PLAY_PDT_TIME_MS);
}
}

@Override
public void onNetStatus(TXVodPlayer player, Bundle bundle) {
}
});

14. Playback network speed listening

You can display the current network speed when the video is lagging by listening on events.
You can use the NET_STATUS_NET_SPEED of onNetStatus to get the current network speed. For detailed directions, see Playback status feedback (onNetStatus).
After the PLAY_EVT_PLAY_LOADING event is detected, the current network speed will be displayed.
After the PLAY_EVT_VOD_LOADING_END event is received, the view showing the current network speed will be hidden.
mVodPlayer.setVodListener(new ITXVodPlayListener() {
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
if (event == TXLiveConstants.PLAY_EVT_PLAY_LOADING) {
// Show the current network speed

} else if (event == TXLiveConstants.PLAY_EVT_VOD_LOADING_END) {
// Hide the view showing the current network speed
}
}

@Override
public void onNetStatus(TXVodPlayer player, Bundle bundle) {
// Get the real-time speed in Kbps
int speed = bundle.getInt(TXLiveConstants.NET_STATUS_NET_SPEED);
}
});

15. Video resolution acquisition

The Player SDK plays back a video through a URL string. The URL doesn't contain the video information, and you need to access the cloud server to load such information. Therefore, the SDK can only send the video information to your application as event notifications. For more information, see Event Listening.
You can get the resolution information in the following two methods:
Method 1: Use the NET_STATUS_VIDEO_WIDTH and NET_STATUS_VIDEO_HEIGHT of onNetStatus to get the video width and height. For detailed directions, see Playback status feedback (onNetStatus).
Method 2: Directly call TXVodPlayer.getWidth() and TXVodPlayer.getHeight() to get the current video width and height after receiving the PLAY_EVT_VOD_PLAY_PREPARED event callback from the player.
mVodPlayer.setVodListener(new ITXVodPlayListener() {
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
}

@Override
public void onNetStatus(TXVodPlayer player, Bundle bundle) {
// Get the video width
int videoWidth = bundle.getInt(TXLiveConstants.NET_STATUS_VIDEO_WIDTH);
// Get the video height
int videoHeight = bundle.getInt(TXLiveConstants.NET_STATUS_VIDEO_HEIGHT);
}
});

// Get the video width and height. The values can be returned only after the `PLAY_EVT_VOD_PLAY_PREPARED` event callback is received from the player
mVodPlayer.getWidth();
mVodPlayer.getHeight();

16. Player buffer size

During normal video playback, you can control the maximum size of the data buffered from the network in advance. If the maximum buffer size is not configured, the player will use the default buffer policy to guarantee a smooth playback experience.
TXVodPlayConfig config = new TXVodPlayConfig();
config.setMaxBufferSize(10); // Maximum buffer size during playback in MB
mVodPlayer.setConfig(config); // Pass in `config` to `mVodPlayer`

17. Local video cache

In short video playback scenarios, the local video file cache is required, so that general users don't need to consume traffic again to reload an already watched video.
Supported format: The SDK supports caching videos in two common VOD formats: HLS (M3U8) and MP4.
Enablement time: The SDK doesn't enable the caching feature by default. We recommend you do not enable it for scenarios in which most videos are watched only once.
Enablement method: This feature can be enabled in the player and takes effect globally. To enable it, you need to configure two parameters: local cache directory and cache size.
File sdcardDir = getApplicationContext().getExternalFilesDir(null);
if (sdcardDir != null) {
// Set the global cache directory of the playback engine
TXPlayerGlobalSetting.setCacheFolderPath(sdcardDir.getPath() + "/txcache");
// Set the global cache directory and cache size in MB of the playback engine
TXPlayerGlobalSetting.setMaxCacheSize(200);
}

// Use the player
Note:
The TXVodPlayConfig#setMaxCacheItems API used for configuration on earlier versions has been deprecated and is not recommended.

18. DRM-encrypted video playback

Note:
This feature requires the premium version of the player to be supported.
DRM playback must be done by importing the Surface of the system android.view.SurfaceView through TXVodPlayer#setSurface before playing, and TXCloudVideoView cannot be used.
The premium version of Player SDK supports playback of commercial DRM-encrypted videos, currently supporting two DRM schemes: WideVine and Fairplay. For more information on commercial DRM, please refer to the product introduction.
You can play it as follows :
Playback via FileId
Customized playback configuration
// DRM playback must be done by importing the Surface of the system android.view.SurfaceView through TXVodPlayer#setSurface before playing, and TXCloudVideoView cannot be used.
mVodPlayer.setSurface(surfaceView.getHolder().getSurface());

// psign is the signature of the player. For information on generating and using player signatures, please refer to the following link:https://cloud.tencent.com/document/product/266/42436
TXPlayInfoParams playInfoParam = new TXPlayInfoParams(${appId}, // Tencent Cloud account's appId
${fieId}, // The fileId of the DRM-encrypted video
${psgin}); // The player signature of the encrypted video
mVodPlayer.startVodPlay(playInfoParam);
Playback via FileId is suitable for integration with the VOD backend. This method is no different from playing regular FileId files, but DRM resources need to be configured in the VOD backend first, and the SDK will recognize and process them internally.
// DRM playback must be done by importing the Surface of the system android.view.SurfaceView through TXVodPlayer#setSurface before playing, and TXCloudVideoView cannot be used.
mVodPlayer.setSurface(surfaceView.getHolder().getSurface());

// Step 1: Set the DRM certificate provider environment. This step is not required by default.
// The Google DRM certificate provider environment defaults to the googleapis.com domain, but can be set to the googleapis.cn domain using the following API:
TXPlayerGlobalSetting.setDrmProvisionEnv(TXPlayerGlobalSetting.DrmProvisionEnv.DRM_PROVISION_ENV_CN); // googleapis.cn domain certificate location

// Step 2: Play using the TXVodPlayer#startPlayDrm interface.
TXPlayerDrmBuilder builder = new TXPlayerDrmBuilder();
builder.setPlayUrl(${url}); // Set the URL of the video to be played.
builder.setKeyLicenseUrl(${keyLicneseUrl}); // Set decryption key URL
mVodPlayer.startPlayDrm(builder);


19. External Subtitles

Note:
This feature requires the premium version of the player to be supported.
The premium version of the player SDK supports adding and switching external subtitles, and now supports two subtitle formats: SRT and VTT.
Best practice: It is recommended to add subtitles and configure subtitle styles before calling startVodPlay. After receiving the VOD_PLAY_EVT_VOD_PLAY_PREPARED event, call selectTrack to choose the subtitle. Adding subtitles does not automatically load them. After calling selectTrack, the subtitles will be loaded. The successful selection of subtitles will trigger the VOD_PLAY_EVT_SELECT_TRACK_COMPLETE event callback.
The usage is as follows:
Step 1: Set the subtitle rendering target object View.
// Add TXSubtitleView to the layout XML where the player is located. 
<com.tencent.rtmp.ui.TXSubtitleView
android:id="@+id/subtitle_view"
android:layout_width="wrap_content"
android:layout_height="wrap_content"/>
mSubtitleView = findViewById(R.id.subtitle_view);
// Set the subtitle rendering target object.
mVodPlayer.setSubtitleView(mSubtitleView);
Step 2: Add external subtitles.
// Pass in the subtitle URL, subtitle name, and subtitle type. It is recommended to add subtitles before starting the playback.
mVodPlayer.addSubtitleSource("https://mediacloud-76607.gzc.vod.tencent-cloud.com/DemoResource/subtitleVTT.vtt", "subtitleName", TXVodConstants.VOD_PLAY_MIMETYPE_TEXT_VTT);
Step 3: Switch subtitles after playback starts.
// After starting to play the video, select the added external subtitle. Please call it after receiving the VOD_PLAY_EVT_VOD_PLAY_PREPARED event.
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
if (event == TXVodConstants.VOD_PLAY_EVT_VOD_PLAY_PREPARED) {
List<TXTrackInfo> subtitleTrackInfoList = mVodPlayer.getSubtitleTrackInfo();
for (TXTrackInfo track : subtitleTrackInfoList) {
Log.d(TAG, "TrackIndex= " + track.getTrackIndex() + " ,name= " + track.getName());
if (TextUtils.equals(track.getName(), "subtitleName")) {
// Selected Subtitles
mVodPlayer.selectTrack(track.trackIndex);
} else {
// If other subtitles are not required, proceed with deselectTrack.
mVodPlayer.deselectTrack(track.trackIndex);
}
}
}
}


// If needed, you can listen for track switching messages.
mVodPlayer.setVodListener(new ITXVodPlayListener() {
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
if (event == TXVodConstants.VOD_PLAY_EVT_SELECT_TRACK_COMPLETE) {
int trackIndex = param.getInt(TXVodConstants.EVT_KEY_SELECT_TRACK_INDEX);
int errorCode = param.getInt(TXVodConstants.EVT_KEY_SELECT_TRACK_ERROR_CODE);
Log.d(TAG, "receive VOD_PLAY_EVT_SELECT_TRACK_COMPLETE, trackIndex=" + trackIndex + " ,errorCode=" + errorCode);
}
}

@Override
public void onNetStatus(TXVodPlayer player, Bundle status) {

}
});
Step 4: Configure subtitle style.
Subtitle style can be configured before or during playback.
// For detailed parameter configuration, please refer to the API documentation.
TXSubtitleRenderModel model = new TXSubtitleRenderModel();
model.canvasWidth = 1920; // Width of the subtitle rendering canvas
model.canvasHeight = 1080; // Height of the subtitle rendering canvas model
model.fontColor = 0xFFFFFFFF; // Set the font color of the subtitle, default is white and opaque
model.isBondFontStyle = false; // Set whether the subtitle font is bold
mVodPlayer.setSubtitleStyle(model);

20. Subtitle text callback

Note:
This feature is supported starting from Player Premium 12.3.
The default configuration of the player premium SDK is to render and display subtitles through the built-in engine. You can modify the configuration to support callback text. The business can render and display the subtitle text by itself after obtaining it. Subtitles in SRT and VTT formats are currently supported.
The detailed usage is as follows:
Step 1: Set up the subtitle text callback
TXVodPlayConfig config = new TXVodPlayConfig();
Map<String, Object> extInfoMap = new HashMap<>();
extInfoMap.put("450", new Integer(0));
config.setExtInfo(extInfoMap);
mVodPlayer.setConfig(config);
Step 2: Add and select subtitles
To add and select subtitle files, please refer to the External Subtitles section.
Step 3: Register to listen for subtitle text callback
After selecting the subtitle, you can register the following interface to listen to the subtitle text content. The meaning of the relevant fields: TXVodSubtitleData#trackIndex, the track index of the current subtitle; TXVodSubtitleData#subtitleData, the actual subtitle text content. When the callback subtitleData is empty, it means that the subtitle is empty. The business can be encapsulated and displayed; the other fields of the TXVodSubtitleData class have no practical meaning for the time being, so don't pay attention to them.
mVodPlayer.setVodSubtitleDataListener(new ITXVodSubtitleDataListener() {
@Override
public void onSubtitleData(TXVodDef.TXVodSubtitleData subtitleData) {
long trackIndex = subtitleData.trackIndex; // The track index of the current subtitle
String data = subtitleData.subtitleData; // The actual subtitle text content
// Display the data subtitle text content as needed
}
});

21. Switching between multiple audio tracks

Note:
This feature requires the premium version of the player to be supported.
The advanced version of the player SDK supports switching between multiple audio tracks embedded in the video. Usage is as follows:
// Returns a list of audio track information
List<TXTrackInfo> soundTrackInfoList = mVodPlayer.getAudioTrackInfo();
for (TXTrackInfo trackInfo : soundTrackInfoList) {
if (trackInfo.trackIndex == 0) {
// Switch to the required audio track by checking the trackIndex or name
mVodPlayer.selectTrack(trackInfo.trackIndex);
} else {
// Deselect the unwanted audio track
mVodPlayer.deselectTrack(trackInfo.trackIndex);
}
}

Using Advanced Features

1. Video preloading

Step 1. Use video preloading

In UGSV playback scenarios, the preloading feature contributes to a smooth viewing experience: When a video is being played, you can load the next video to be played back on the backend. When a user switches to the next video, it will already be loaded and can be played back immediately.
Video preloading can deliver an instant playback effect but has certain performance overheads. It will occupy download bandwidth and thread resources. It is recommended that the number of concurrent video pre-playbacks be controlled within 3. If your business needs to preload many videos, we recommend you use this feature together with video predownloading.
This is how seamless switch works in video playback. You can use setAutoPlay in TXVodPlayer to implement the feature as follows:


// Play back video A: If `autoPlay` is set to `true`, the video will be immediately loaded and played back when `startVodPlay` is called
String urlA = "http://1252463788.vod2.myqcloud.com/xxxxx/v.f10.mp4";
playerA.setAutoPlay(true);
playerA.startVodPlay(urlA);

// To preload video B when playing back video A, set `setAutoPlay` to `false`
String urlB = @"http://1252463788.vod2.myqcloud.com/xxxxx/v.f20.mp4";
playerB.setAutoPlay(false);
playerB.startVodPlay(urlB); // The video won't be played back immediately but will start to be loaded
After video A ends and video B is automatically or manually switched to, you can call the resume function to immediately play back video B.
Note:
After autoPlay is set to false, make sure that video B has been prepared before calling resume, that is, you should call it only after the PLAY_EVT_VOD_PLAY_PREPARED event of video B (2013: the player has been prepared, and the video can be played back) is detected.
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
// When video A ends, directly start playing back video B for seamless switch
if (event == PLAY_EVT_PLAY_END) {
playerA.stop();
playerB.setPlayerView(mPlayerView);
playerB.resume();
}
}

Step 2. Configure the video preloading buffer

You can set a large buffer to play back videos more smoothly under unstable network conditions.
You can set a smaller buffer to reduce the traffic consumption.
Preloading buffer size
This API is used to control the maximum buffer size before the playback starts in preloading scenarios (that is, AutoPlay of the player is set to false before video playback starts).
TXVodPlayConfig config = new TXVodPlayConfig();
config.setMaxPreloadSize(2); // Maximum preloading buffer size in MB. Set it based on your business conditions to reduce the traffic consumption
mVodPlayer.setConfig(config); // Pass in `config` to `mVodPlayer`
Playback buffer size
During normal video playback, you can control the maximum size of the data buffered from the network in advance. If the maximum buffer size is not configured, the player will use the default buffer policy to guarantee a smooth playback experience.
TXVodPlayConfig config = new TXVodPlayConfig();
config.setMaxBufferSize(10); // Maximum buffer size during playback in MB
mVodPlayer.setConfig(config); // Pass in `config` to `mVodPlayer`

2. Video predownloading

You can download part of the video content in advance without creating a player instance, so as to start playing back the video faster when using the player. This helps deliver a better playback experience.
Before using the playback service, make sure that video cache has been set.
Note:
1. Video pre-downloading will occupy download bandwidth and thread resources. It is recommended to control the queue and limit the number of concurrent downloads to less than 3.
2. TXPlayerGlobalSetting is the global cache setting API, and the original TXVodConfig API has been deprecated.
3. The global cache directory and size settings have a higher priority than those configured in TXVodConfig of the player.
Download via media URL
Download via media FileId
The code example for pre-downloading video via media URL is as follows:
// Set the global cache directory and cache size of the playback engine
File sdcardDir = getApplicationContext().getExternalFilesDir(null);
// Set the global cache directory and cache size of the playback engine
if (sdcardDir != null) {
TXPlayerGlobalSetting.setCacheFolderPath(sdcardDir.getPath() + "/PlayerCache");
TXPlayerGlobalSetting.setMaxCacheSize(200); // Unit: MB
}

String palyrl = "http://****";
// Start predownloading
final TXVodPreloadManager downloadManager = TXVodPreloadManager.getInstance(getApplicationContext());
final int taskID = downloadManager.startPreload(playUrl, 3, 1920*1080, new ITXVodPreloadListener() {
@Override
public void onComplete(int taskID, String url) {
Log.d(TAG, "preload: onComplete: url: " + url);
}

@Override
public void onError(int taskID, String url, int code, String msg) {
Log.d(TAG, "preload: onError: url: " + url + ", code: " + code + ", msg: " + msg);
}

});

// Cancel predownloading
downloadManager.stopPreload(taskID);

Noe:
Pre-downloading via fileId is supported from version 11.3 onwards.
Pre-downloading via fileId is a time-consuming operation. Please do not call it on the main thread, otherwise an illegal call exception will be thrown. The preferredResolution parameter passed in when calling startPreload should be consistent with the preferred resolution set when starting playback, otherwise the expected effect will not be achieved. Here is an example of how to use it:
// Set the global cache directory and cache size for the playback engine File
File sdcardDir = getApplicationContext().getExternalFilesDir(null);
// Set the global cache directory and cache size for the playback engine
if (sdcardDir != null) {
TXPlayerGlobalSetting.setCacheFolderPath(sdcardDir.getPath() + "/PlayerCache");
TXPlayerGlobalSetting.setMaxCacheSize(200); // Unit: MB
}

// Start preloading
Runnable task = new Runnable() {
@Override
public void run() {
TXPlayInfoParams playInfoParams = new TXPlayInfoParams(${appId}, "${fileId}",
"${psign}");
//  Note: This is a time-consuming operation, do not call it on the main thread! // Calling it on the main thread will throw an illegal call exception.
mPreLoadManager.startPreload(playInfoParams, 3, 1920 * 1080, new ITXVodFilePreloadListener() {

@Override
public void onStart(int taskID, String fileId, String url, Bundle bundle) {
// The onStart method will be called when the file URL is successfully obtained using the fileId.
Log.d(TAG, "preload: onStart: taskID: " + taskID + ", fileId: " + fileId + ", url: " + url + ",bundle: " + bundle);
}

@Override
public void onComplete(int taskID, String url) {
Log.d(TAG, "preload: onComplete: url: " + url);
}

@Override
public void onError(int taskID, String url, int code, String msg) {
Log.d(TAG, "preload: onError: url: " + url + ", code: " + code + ", msg: " + msg);
}
});
}
};
new Thread(task).start();


// Cancel preloading
downloadManager.stopPreload(taskID);

3. Video download

Video download allows users to download online videos and watch them offline. If the video is encrypted, the downloaded video through the player SDK will be kept in an encrypted state locally and can only be decrypted and played through Tencent Cloud Player SDK. This can effectively prevent illegal dissemination of downloaded videos and protect video security.
As HLS streaming media cannot be directly saved locally, you cannot download them and play back them as local files. You can use the video download scheme based on TXVodDownloadManager to implement offline HLS playback.
Note:
Video download supports downloading MP4 and HLS videos. For nested HLS videos, you need to specify the preferred resolution.

Step 1. Make preparations

When initializing the SDK, set the global storage path for video downloading, preloading, caching, and other functions. Usage is as follows:
File sdcardDir = context.getExternalFilesDir(null);
TXPlayerGlobalSetting.setCacheFolderPath(sdcardDir.getPath() + "/txcache");
TXVodDownloadManager is designed as a singleton; therefore, you cannot create multiple download objects. It is used as follows:
TXVodDownloadManager downloader = TXVodDownloadManager.getInstance();
Set the httpHeader used for downloading
Configure according to business needs. When the player starts downloading, it will be sent to the server. Player version 12.2 starts to support it.
Map<String, String> httpHeaders = new HashMap<>();
downloader.setHeaders(httpHeaders); // Set the download httpHeader

Step 2. Start the download

You can start the download through Fileid or URL as follows:
Through Fileid
Through URL
For download through Fileid, you need to pass in AppID, Fileid, and qualityId at least. For signed videos, you also need to pass in pSign. If no specific value is passed in to userName, it will be default by default.
Note: You can download encrypted videos only through Fileid and must enter the psign parameter.
// QUALITY_240P 240p
// QUALITY_360P 360P
// QUALITY_480P 480p
// QUALITY_540P 540p
// QUALITY_720P 720p
// QUALITY_1080P 1080p
// QUALITY_2K 2k
// QUALITY_4K 4k
// The quality parameter can be customized to take the minimum value of the resolution width and height (for example, if the resolution is 1280*720 and you want to download the stream with this resolution, pass in QUALITY_720P)
// The player SDK will select a stream that is less than or equal to the passed-in resolution for downloading.
TXVodDownloadDataSource source = new TXVodDownloadDataSource(1252463788, "4564972819220421305", QUALITY_720P, "pSignxxxx", ""); //pSign encrypted video signature, mandatory download via fileId
downloader.startDownload(source)
You need to pass in the download URL at least. Only the non-nested HLS, i.e., single-bitstream HLS, is supported. If no specific value is passed in to userName, it will be default by default.
downloader.startDownloadUrl("http://1500005830.vod2.myqcloud.com/43843ec0vodtranscq1500005830/00eb06a88602268011437356984/video_10_0.m3u8", "");

Step 3. Receive the task information

Before receiving the task information, you need to set the callback listener first.
downloader.setListener(this);
You may receive the following task callbacks:
Callback Message
Description
void onDownloadStart(TXVodDownloadMediaInfo mediaInfo)
The task started, that is, the SDK started the download.
void onDownloadProgress(TXVodDownloadMediaInfo mediaInfo)
Task progress. During download, the SDK will frequently call back this API. You can use mediaInfo.getProgress() to get the current progress.
void onDownloadStop(TXVodDownloadMediaInfo mediaInfo)
The task stopped. When you call stopDownload to stop the download, if this message is received, the download is stopped successfully.
void onDownloadFinish(TXVodDownloadMediaInfo mediaInfo)
Download was completed. If this callback is received, the entire file has been downloaded, and the downloaded file can be played back by TXVodPlayer.
void onDownloadError(TXVodDownloadMediaInfo mediaInfo, int error, String reason)
A download error occurred. If the network is disconnected during download, this API will be called back and the download task will stop. The error code is in TXVodDownloadManager.
The download error codes are as follows:
Error Code
Value
Description
DOWNLOAD_SUCCESS
0
Download succeeded.
DOWNLOAD_AUTH_FAILED
-5001
Request for video information from the VOD console failed. Check whether the fileId and psign parameters are correct.
DOWNLOAD_NO_FILE
-5003
The file of the specified definition does not exist.
DOWNLOAD_FORMAT_ERROR
-5004
The downloaded file format is not supported.
DOWNLOAD_DISCONNECT
-5005
Network disconnected. Check whether the network is normal.
DOWNLOAD_HLS_KEY_ERROR
-5006
Failed to obtain the HLS decryption key.
DOWNLOAD_PATH_ERROR
-5007
Failed to access the download directory. Check whether you have the permission to access the download directory.
DOWNLOAD_403FORBIDDEN
-5008
Authentication information failed to pass when downloading. Check whether the signature (psign) has expired.
As the downloader can download multiple files at a time, the callback API carries the TXVodDownloadMediaInfo object. You can access the URL or dataSource to determine the download source and get other information such as download progress and file size.

Step 4. Stop the download

You can call the downloader.stopDownload() method to stop the download. The parameter is the object returned by downloader.startDownload(). The SDK supports checkpoint restart. If the download directory is not changed, when you resume downloading a file, the download will start from the point where it stopped.

Step 5. Manage downloads

You can get the download lists of all accounts or the specified account.
// Get the download lists of all users
// You can distinguish between the download lists of different users by `userName` in the download information
// getDownloadMediaInfoList is a time-consuming function. Please do not call it in the main thread.
List<TXVodDownloadMediaInfo> downloadInfoList = downloader.getDownloadMediaInfoList();
if (downloadInfoList == null || downloadInfoList.size() <= 0) return;
// Get the download list of the `default` user
List<TXVodDownloadMediaInfo> defaultUserDownloadList = new ArrayList<>();
for(TXVodDownloadMediaInfo downloadMediaInfo : downloadInfoList) {
if ("default".equals(downloadMediaInfo.getUserName())) {
defaultUserDownloadList.add(downloadMediaInfo);
}
}
To get the download information of a Fileid, such as the current download status and progress, you need to pass in AppID, Fileid, and qualityId.
// Get the download information of a `fileId`
TXVodDownloadMediaInfo downloadInfo = downloader.getDownloadMediaInfo(1252463788, "4564972819220421305", QUALITYHD);
// Get the total size of the file being downloaded in bytes. This API takes effect only for download through `fileid`.
// Note: The total size refers to the size of the original file uploaded to the VOD console. Currently, the substream size after adaptive bitrate streaming cannot be obtained.
int size = downloadInfo.getSize(); // Get the total size of the file being downloaded
int duration = downloadInfo.getDuration(); // Get the total duration
int playableDuration = downloadInfo.getPlayableDuration(); // Get the playable duration of the downloaded video
float progress = downloadInfo.getProgress(); // Get the download progress
String playPath = downloadInfo.getPlayPath(); // Get the offline playback path, which can be passed in to the player to start offline playback.
int downloadState = downloadInfo.getDownloadState(); // Get the download status. For more information, see the `STATE_xxx` constant.
boolean isDownloadFinished = downloadInfo.isDownloadFinished(); // If `true` is returned, the download is completed.
To get the download information of a URL, you need to pass in the URL information.
// Get the download information of a URL
TXVodDownloadMediaInfo downloadInfo = downloader.getDownloadMediaInfo("http://1253131631.vod2.myqcloud.com/26f327f9vodgzp1253131631/f4bdff799031868222924043041/playlist.m3u8");
To delete the download information and relevant file, you need to pass in the TXVodDownloadMediaInfo parameter.
// Delete the download information
boolean deleteRst = downloader.deleteDownloadMediaInfo(downloadInfo);

Step 6: Offline Playback after Download

The downloaded video supports playback without network connection. After downloading, you can obtain the download URL through TXVodDownloadMediaInfo#getPlayPath for playback.
// `getDownloadMediaInfoList` is a time-consuming function. Please do not call it in the main thread.
List<TXVodDownloadMediaInfo> mediaInfoList = TXVodDownloadManager.getInstance().getDownloadMediaInfoList();
// Business logic finds the media object that needs to be played according to actual needs
for (TXVodDownloadMediaInfo mediaInfo : mediaInfoList) {
if (mediaInfo.getDownloadState() == TXVodDownloadMediaInfo.STATE_FINISH) { // Check if the download is complete
mVodPlayer.startVodPlay(mediaInfo.getPlayPath()); // Play the downloaded video
}
}

4. Encrypted playback

The video encryption solution is used in scenarios where the video copyright needs to be protected, such as online education. To encrypt your video resources, you need to alter the player and encrypt and transcode video sources. For more information, see Media Encryption and Copyright Protection Overview.
After you get the appId as well as the encrypted video's fileId and psign in the Tencent Cloud console, you can play back the video as follows:
// `psign` is a player signature. For more information on the signature and how to generate it, see [Player Signature](https://intl.cloud.tencent.com/document/product/266/38099).
TXPlayInfoParams playInfoParam = new TXPlayInfoParams(1252463788, // `appId` of the Tencent Cloud account
"4564972819220421305", // `fileId` of the video
"psignxxxxxxx"); // The player signature
mVodPlayer.startVodPlay(playInfoParam);

5. Player configuration

Before calling statPlay, you can call setConfig to configure the player parameters, such as player connection timeout period, progress callback interval, and maximum number of cached files. TXVodPlayConfig allows you to configure detailed parameters. For more information, see Basic Configuration API. Below is the configuration sample code:
TXVodPlayConfig config = new TXVodPlayConfig();
config.setEnableAccurateSeek(true); // Set whether to enable accurate seek. Default value: true
config.setMaxCacheItems(5); // Set the maximum number of cached files to 5
config.setProgressInterval(200); // Set the progress callback interval in ms
config.setMaxBufferSize(50); // Set the maximum preloading buffer size in MB
mVodPlayer.setConfig(config); // Pass in `config` to `mVodPlayer`
Specifying resolution when playback starts
When playing back an HLS multi-bitrate video source, if you know the video stream resolution information in advance, you can specify the preferred resolution before playback starts, and the player will select and play back the stream at or below the preferred resolution. In this way, after playback starts, you don't need to call setBitrateIndex to switch to the required bitstream.
TXVodPlayConfig config = new TXVodPlayConfig();
// The parameter passed in is the product of the video width and height. You can pass in a custom value.
config.setPreferredResolution(TXLiveConstants.VIDEO_RESOLUTION_720X1280);
mVodPlayer.setConfig(config); // Pass in `config` to `mVodPlayer`
Specify media type before broadcasting
When the type of media asset to be played is known in advance, the playback speed can be enhanced by configuring TXVodPlayConfig#setMediaType to reduce the internal playback type detection of the player SDK.
Note:
TXVodPlayConfig#setMediaType is supported starting from version 11.2.
TXVodPlayConfig config = new TXVodPlayConfig();
config.setMediaType(TXVodConstants.MEDIA_TYPE_FILE_VOD); // Used to improve MP4 playback startup speed 
// config.setMediaType(TXVodConstants.MEDIA_TYPE_HLS_VOD); // Used to improve HLS playback startup speed
mVodPlayer.setConfig(config);
Setting playback progress callback interval
TXVodPlayConfig config = new TXVodPlayConfig();
config.setProgressInterval(200); // Set the progress callback interval in ms
mVodPlayer.setConfig(config); // Pass in `config` to `mVodPlayer`
Specify the priority audio track before starting playback
Note:
This feature is supported starting from the Premium Player 12.3 version.
When the name of the audio track to be played is known in advance, you can specify the priority audio track before starting playback by configuring TXVodPlayConfig#setPreferredAudioTrack.
TXVodPlayConfig config = new TXVodPlayConfig();
config.setPreferredAudioTrack("audioTrackName"); // audioTrackName is the actual track name
mVodPlayer.setConfig(config); // Pass config to mVodPlayer

6. HttpDNS resolution service

Mobile analysis (HTTPDNS) sends domain name resolution requests to DNS servers based on the HTTP protocol, replacing the traditional method of sending resolution requests to the operator's local DNS based on the DNS protocol. This can avoid domain name hijacking and cross-network access issues caused by local DNS, and solve the problem of video playback failure caused by abnormal domain name resolution in mobile Internet services.
Note:
HttpDNS resolution service is supported starting from version 10.9.
1. Enabling HTTPDNS resolution service
You can choose Tencent Cloud or other cloud providers to enable HTTPDNS resolution service. Make sure to integrate it into the player SDK after successful activation.
2. Accessing HTTPDNS resolution service in the player SD
Taking Tencent Cloud HTTPDNS as an example, the following shows how to access it in the player SDK::
It is not recommended for the business layer to cache domain name resolution results. For example, Tencent HTTPDNS has a built-in intelligent cache mechanism. Additional caching on the business side may result in untimely updates.
Disable the LocaIDNS fallback domain name resolution policy. Configure setUseExpiredIpEnable(false) and setCachedIpEnable(false) through the DnsConfig of the HTTPDNS SDK to avoid obtaining non-optimal or unavailable IPs in the scenario where LocaIDNS has an exception (such as hijacking, pollution, or recursive resolution failure).
// Step 1: Enable HttpDNS parsing switch
TXLiveBase.enableCustomHttpDNS(true);
// Step 2: Set HttpDNS resolution callback, TXLiveBaseListener#onCustomHttpDNS
TXLiveBase.setListener(new TXLiveBaseListener() {
@Override
public void onCustomHttpDNS(String hostName, List<String> ipList) {
// The player SDK will callback the hostName to the business. The business can determine whether to resolve the hostName to an ip based on your actual needs.
// If an empty ip is returned, the SDK will not use httpdns for this network request.
// After resolving the hostName to an ip address, save it to iPList and return it to inside the SDK. Note: Do not perform asynchronous operations here.
// Usage example: MSDKDnsResolver is the HTTPDNS SDK resolution API provided by Tencent Cloud
// String ips = MSDKDnsResolver.getInstance().getAddrByName(hostname);
String[] ipArr = ips.split(";");
if (0 != ipArr.length) {
for (String ip : ipArr) {
if ("0".equals(ip)) {
continue;
}
ipList.add(ip);
}
}
}
});

7. HEVC Adaptive Downgrade Play

The player supports playing links that contain both HEVC and other video encoding formats, such as H.264. When the player device does not support the HEVC format, it will automatically downgrade to playing videos in the configured alternative encoding format (such as H.264).
Note: Supported from player version 11.7 of the premium version.
// Set backup playback link
String backupPlayUrl = "${backupPlayUrl}"; // Alternative playback link
mVodPlayer.setStringOption(TXVodConstants.VOD_KEY_MIMETYPE, TXVodConstants.VOD_PLAY_MIMETYPE_H265); // Specify the original HEVC video encoding type
mVodPlayer.setStringOption(TXVodConstants.VOD_KEY_BACKUP_URL, backupPlayUrl); // Set the backup playback link address for formats such as H.264

// Set the original HEVC playback link
String hevcPlayUrl = "${hevcPlayUrl}";
mVodPlayer.startVodPlay(hevcPlayUrl);

8. Volume Normalization

The player supports automatically adjusting the volume when playing audio to ensure that the volume of all audio is consistent. This can avoid problems with some audio being too loud or too quiet, providing a better auditory experience. Use TXVodPlayer#setAudioNormalization to set the volume normalization, with a loudness range of -70 to 0 (LUFS), and custom values are also supported. Note: Supported from player version 11.7 of the premium version.
/**
Can be set to preset values (related classes or files: Android: TXVodConstants; iOS: TXVodPlayConfig.h)
Off: AUDIO_NORMALIZATION_OFF
On: AUDIO_NORMALIZATION_STANDARD (standard)
AUDIO_NORMALIZATION_LOW (low)
AUDIO_NORMALIZATION_HIGH (high)
Custom values can be set: from low to high, range -70 to 0 LUFS
*/
mVodPlayer.setAudioNormalization(TXVodConstants.AUDIO_NORMALIZATION_STANDARD); // Enable volume normalization

mVodPlayer.setAudioNormalization(TXVodConstants.AUDIO_NORMALIZATION_OFF); // Disable volume normalization

9. MP4 video local encryption

After MP4 local encryption is turned on, the player will encrypt and store the data when caching files. Encrypted video files can only be decrypted and played by the player, and cannot be played by third-party players.
Note:
After MP4 local encryption is turned on and playback begins, the encryption settings cannot be changed unless the file is cleared and re-cached.
This feature is supported starting with the Advanced Player 12.2 version.
//Precondition: Set the global cache directory of the player. This configuration only needs to be set once in the project
File sdcardDir = getApplicationContext().getExternalFilesDir(null);
if (sdcardDir != null) {
TXPlayerGlobalSetting.setCacheFolderPath(sdcardDir.getPath() + "/PlayerCache");
}

TXVodPlayConfig config = new TXVodPlayConfig();
config.setEncryptedMp4Level(TXVodConstants.MP4_ENCRYPTION_LEVEL_L2); // Set to use mp4 local encrypted playback and storage
mVodPlayer.setConfig(config);

Player Event Listening

You can bind a TXVodPlayListener listener to the TXVodPlayer object to use onPlayEvent (event notification) and onNetStatus (status feedback) to sync information to your application.

Playback event notifications (onPlayEvent)

Event ID
Code
Description
PLAY_EVT_PLAY_BEGIN
2004
Video playback started.
PLAY_EVT_PLAY_PROGRESS
2005
The video playback progress (including the current playback progress, loading progress, and total video duration).
PLAY_EVT_PLAY_LOADING
2007
The video is being loaded. The LOADING_END event will be reported if video playback resumes.
PLAY_EVT_VOD_LOADING_END
2014
Video loading ended, and video playback resumed.
TXVodConstants.VOD_PLAY_EVT_SEEK_COMPLETE
2019
Seeking was completed. The seeking feature is supported by v10.3 or later.
VOD_PLAY_EVT_LOOP_ONCE_COMPLETE
6001
A round of loop was completed. The loop feature is supported by v10.8 or later.
TXVodConstants.VOD_PLAY_EVT_HIT_CACHE
2002
Cache hit event during playback (supported by v11.2 or later).
TXVodConstants.VOD_PLAY_EVT_VIDEO_SEI
2030
Received SEI frame event (supported from player version 11.6 of the premium version).
VOD_PLAY_EVT_HEVC_DOWNGRADE_PLAYBACK
2031
HEVC downgrade playback occurs (supported by the player's advanced version 12.0).
VOD_PLAY_EVT_FIRST_VIDEO_PACKET
2017
The player receives the first frame data packet event (supported by version 12.0).
SEI frame
SEI (Supplemental Enhancement Information) frames are a type of frame used to transmit additional information. The premium version of the player will parse the SEI frames in the video stream and provide callbacks through the `VOD_PLAY_EVT_VIDEO_SEI` event. Note: Supported from player version 11.6 of the premium version.
@Override public void onPlayEvent(TXVodPlayer player, int event, Bundle param) { if (event == TXVodConstants.VOD_PLAY_EVT_VIDEO_SEI) { int seiType = param.getInt(TXVodConstants.EVT_KEY_SEI_TYPE); // the type of video SEI int seiSize = param.getInt(TXVodConstants.EVT_KEY_SEI_SIZE); // the data size of video SEI byte[] seiData = param.getByteArray(TXVodConstants.EVT_KEY_SEI_DATA); // the byte array data of video SEI } }

Stop events

Event ID
Code
Description
PLAY_EVT_PLAY_END
2006
Video playback ended.
PLAY_ERR_NET_DISCONNECT
-2301
The network was disconnected and could not be reconnected after multiple retries. You can restart the player to perform more connection retries.
PLAY_ERR_HLS_KEY
-2305
Failed to get the HLS decryption key.

Warning events

You can ignore the following events, which are only used to notify you of some internal events of the SDK.
Event ID
Code
Description
PLAY_WARNING_VIDEO_DECODE_FAIL
2101
Failed to decode the current video frame.
PLAY_WARNING_AUDIO_DECODE_FAIL
2102
Failed to decode the current audio frame.
PLAY_WARNING_RECONNECT
2103
The network was disconnected, and automatic reconnection was performed (the PLAY_ERR_NET_DISCONNECT event will be thrown after three failed attempts).
PLAY_WARNING_HW_ACCELERATION_FAIL
2106
Failed to start the hardware decoder, and the software decoder was used instead.

Connection events

The following server connection events are mainly used to measure and collect the server connection time:
Event ID
Code
Description
PLAY_EVT_VOD_PLAY_PREPARED
2013
The player has been prepared and can start playback. If autoPlay is set to false, you need to call resume after receiving this event to start playback.
PLAY_EVT_RCV_FIRST_I_FRAME
2003
The network received the first renderable video data packet (IDR).

Image quality events

The following events are used to get image change information:
Event ID
Code
Description
PLAY_EVT_CHANGE_RESOLUTION
2009
The video resolution changed.
PLAY_EVT_CHANGE_ROTATION
2011
The MP4 video was rotated.

Video information events

Event ID
Code
Description
TXLiveConstants.PLAY_EVT_GET_PLAYINFO_SUCC
2010
Obtained the information of the file played back successfully.
If you play back a video through fileId and the playback request succeeds (called API::startVodPlay(TXPlayInfoParams playInfoParams)), the SDK will notify the upper layer of some request information, and you can parse param to get the video information after receiving the TXLiveConstants.PLAY_EVT_GET_PLAYINFO_SUCC event.
Video Information
Description
EVT_PLAY_COVER_URL
Video thumbnail URL
EVT_PLAY_URL
Video playback address
EVT_PLAY_DURATION
Video duration
EVT_DESCRIPTION
Event description
EVT_PLAY_NAME
Video name
TXVodConstants.EVT_IMAGESPRIT_WEBVTTURL
Download URL of the image sprite WebVTT file, which is supported by v10.2 or later
TXVodConstants.EVT_IMAGESPRIT_IMAGEURL_LIST
The download URL of the image sprite image, which is supported by v10.2 or later.
TXVodConstants.EVT_DRM_TYPE
The encryption type, which is supported by v10.2 or later.
TXVodConstants.EVT_KEY_WATER_MARK_TEXT
Ghost watermark text content (supported from version 11.6).
Below is the sample code of using onPlayEvent to get the video playback information:
mVodPlayer.setVodListener(new ITXVodPlayListener() {
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
if (event == TXLiveConstants.PLAY_EVT_VOD_PLAY_PREPARED) {
// The player preparation completion event is received, and you can call the `pause`, `resume`, `getWidth`, and `getSupportedBitrates` APIs.
} else if (event == TXLiveConstants.PLAY_EVT_PLAY_BEGIN) {
// The playback start event is received
} else if (event == TXLiveConstants.PLAY_EVT_PLAY_END) {
// The playback end event is received
}
}

@Override
public void onNetStatus(TXVodPlayer player, Bundle bundle) {
}
});
Ghost watermark
The content of the ghost watermark is filled in the player signature and is ultimately displayed on the playback end through collaboration between the cloud and the player, ensuring the security of the watermark throughout the transmission process. Follow the tutorial to configure the ghost watermark in the player signature. The content of the ghost watermark can be obtained through `param.getString(TXVodConstants.EVT_KEY_WATER_MARK_TEXT)` after receiving the `TXVodConstants#VOD_PLAY_EVT_GET_PLAYINFO_SUCC` event from the player. For detailed usage tutorial, please refer to SuperPlayer Component > Ghost Watermark.
Note: Supported from player version 11.6.

Playback error event

Note:
Error events [-6004, -6010] are supported starting from version 11.0.
Event ID
Value
Description
PLAY_ERR_NET_DISCONNECT
-2301
Video data error that cannot be recovered by retrying. For example, network anomaly or data download error that causes demultiplexing timeout or failure.
PLAY_ERR_HLS_KEY
-2305
Failed to obtain HLS decryption key.
VOD_PLAY_ERR_SYSTEM_PLAY_FAIL
-6004
System player playback error.
VOD_PLAY_ERR_DECODE_VIDEO_FAIL
-6006
Video decoding error, video format not supported.
VOD_PLAY_ERR_DECODE_AUDIO_FAIL
-6007
Audio decoding error, audio format not supported.
VOD_PLAY_ERR_DECODE_SUBTITLE_FAIL
-6008
Subtitle decoding error.
VOD_PLAY_ERR_RENDER_FAIL
-6009
Video rendering error.
VOD_PLAY_ERR_PROCESS_VIDEO_FAIL
-6010
Video post-processing error.
VOD_PLAY_ERR_GET_PLAYINFO_FAIL
-2306
Failed to obtain the on-demand file information. It is recommended to check whether the AppId, FileId or Psign is filled in correctly.

Playback status feedback (onNetStatus)

The status feedback is triggered once every 0.5 seconds to provide real-time feedback on the current status of the pusher. It can act as a dashboard to inform you of what is happening inside the SDK so you can better understand the current video playback status.
Parameter
Description
NET_STATUS_CPU_USAGE
Current instantaneous CPU utilization
NET_STATUS_VIDEO_WIDTH
Video resolution - width
NET_STATUS_VIDEO_HEIGHT
Video resolution - height
NET_STATUS_NET_SPEED
Current network data reception speed in KBps
NET_STATUS_VIDEO_FPS
Current video frame rate of streaming media
NET_STATUS_VIDEO_BITRATE
Current video bitrate in bps of streaming media
NET_STATUS_AUDIO_BITRATE
Current audio bitrate in bps of streaming media
NET_STATUS_VIDEO_CACHE
Buffer (`jitterbuffer`) size. If the current buffer length is 0, lag will occur soon.
NET_STATUS_SERVER_IP
Connected server IP
Below is the sample code of using `onNetStatus` to get the video playback information:
mVodPlayer.setVodListener(new ITXVodPlayListener() {
@Override
public void onPlayEvent(TXVodPlayer player, int event, Bundle param) {
}

@Override
public void onNetStatus(TXVodPlayer player, Bundle bundle) {
// Get the current CPU utilization
CharSequence cpuUsage = bundle.getCharSequence(TXLiveConstants.NET_STATUS_CPU_USAGE);
// Get the video width
int videoWidth = bundle.getInt(TXLiveConstants.NET_STATUS_VIDEO_WIDTH);
// Get the video height
int videoHeight = bundle.getInt(TXLiveConstants.NET_STATUS_VIDEO_HEIGHT);
// Get the real-time rate in Kbps
int speed = bundle.getInt(TXLiveConstants.NET_STATUS_NET_SPEED);
// Get the current video frame rate of streaming media
int fps = bundle.getInt(TXLiveConstants.NET_STATUS_VIDEO_FPS);
// Get the current video bitrate in bps of streaming media
int videoBitRate = bundle.getInt(TXLiveConstants.NET_STATUS_VIDEO_BITRATE);
// Get the current audio bitrate in bps of streaming media
int audioBitRate = bundle.getInt(TXLiveConstants.NET_STATUS_AUDIO_BITRATE);
// Get the buffer (`jitterbuffer`) size. If the current buffer length is 0, lag will occur soon.
int jitterbuffer = bundle.getInt(TXLiveConstants.NET_STATUS_VIDEO_CACHE);
// Get the connected server IP
String ip = bundle.getString(TXLiveConstants.NET_STATUS_SERVER_IP);
}
});

Other functions

HLS live video source playback

The premium version of the player supports playing HLS live video sources. Starting from version 11.8, it supports live video sources with HLS EVENT. Usage is as follows:
TXVodPlayConfig config = new TXVodPlayConfig();
config.setMediaType(TXVodConstants.MEDIA_TYPE_HLS_LIVE); // Specify the HLS live media type
mVodPlayer.setConfig(config);
mVodPlayer.startVodPlay(${YOUR_HSL_LIVE_URL});

Scenario-Specific Features

1. SDK-based demo component

Based on the Player SDK, Tencent Cloud has developed a player component. It integrates quality monitoring, video encryption, Top Speed Codec, definition selection, and small window playback and is suitable for all VOD and live playback scenarios. It encapsulates complete features and provides upper-layer UIs to help you quickly create a playback program comparable to popular video apps.

2. Open-source GitHub projects

Based on the Player SDK, Tencent Cloud has developed immersive video player, video feed stream, and multi-layer reuse components and will provide more user scenario-based components on future versions. You can download Player for Android to try them out.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 available.

7x24 Phone Support