tencent cloud

All product documents
Video on Demand
DocumentationVideo on Demand
API Documentation
Last updated: 2023-03-15 17:43:58
API Documentation
Last updated: 2023-03-15 17:43:58

TXVodPlayer

VOD player

See TXVodPlayer. The player pulls audio/video data from the specified VOD stream URL and plays the data after decoding and local rendering. The player has the following capabilities:
FLV, MP4, and HLS files can be played back in two playback methods: basic playback (by URL) and VOD playback (by Fileid ).
Screenshots of the video stream can be taken.
The brightness, volume level, and playback progress can be adjusted through gestures.
Resolution can be switched manually or resolution can be automatically switched to adapt to the current network bandwidth.
Different playback speeds can be specified, videos can be flipped horizontally, and hardware acceleration can be enabled.
For more information about all capabilities of the player, see Overview.

Player configuration APIs

API
Description
Configures VOD. For more information on the configuration, see TXVodPlayConfig.
Sets whether to start playback immediately after call of startPlay. Default value: YES.
Sets the token for HLS encryption. After the token is set, the player will automatically add voddrm.token.TOKEN TextureView before the filename in the URL.
Sets whether to loop SurfaceView.
Sets whether to enable hardware acceleration.
Sets the player business parameters in the format of <NSString *, id>.

Basic playback APIs

API
Description
Starts playing back the video at the specified HTTP URL.
Starts playing back a file encrypted with standard FairPlay DRM.
Starts playing back the video of the specified fileId.
Stops playback.
Gets whether playback is ongoing.
Pauses playback by stopping the retrieval of stream data and retaining the last-frame image.
Resumes playback by getting the stream data again.
Seeks to the video stream to the specified time point in s.
Gets the current playback time point in seconds.
Gets the total video duration in seconds.
Gets the playable video duration in seconds.
Gets the video width.
Gets the video height.
Sets the playback start time.
Creates the video rendering view. This control is used to display the video content.
Removes the video rendering view.

Video APIs

API
Description
Gets the current video frame image.
Note: As this operation is time-consuming, the screenshot will be called back asynchronously.
Sets whether to flip the video image horizontally.
Sets the VOD playback speed. Default value: 1.0.
Returns the current playback bitrate index.
Sets the current playback bitrate index for seamless definition switch. <br>You may need to wait momentarily to switch the definition.
Returns the supported bitrates (definitions) if the playback address is a master playlist.
Sets the image fill mode.
Enters the PiP mode.
Exits the PiP mode.

Audio APIs

API
Description
Sets whether to mute the player.
Sets the volume level. Value range: 0–100.

Event notification APIs

API
Description
The event callback. We recommend you use vodDelegate.
Sets the player callback.
Sets the video rendering callback (supported by hardware encoding only).

TRTC APIs

You can use the following APIs to push the audio/video streams of the VOD player through TRTC. For more information on TRTC services, see the TRTC Overview page.
API
Description
Binds VOD to TRTC.
Unbinds VOD from TRTC.
Starts pushing the video stream.
Cancels pushing the video stream.
Starts pushing the audio stream.
Cancels pushing the audio stream.

Class methods

API
Description
Gets the encrypted playback key.
Queries whether the current device supports the picture-in-picture (PiP) feature.

TXVodPlayListener

VOD callback notifications.

Basic SDK callback APIs

API
Description
VOD playback event notification. For more information, see the playback event list and event parameters.
The callback for PiP status.
The callback for PiP error status.

TXVodPlayConfig

VOD player configuration class.

Basic configuration APIs

API
Description
Sets the maximum number of player reconnection attempts.
Sets the player reconnection interval in seconds.
Sets the player connection timeout period in seconds.
Sets the VOD cache directory, which takes effect for MP4 and HLS files.
This API has been deprecated. We recommend you use TXPlayerGlobalSetting##setCacheFolderPath.
Sets the maximum number of cached files.
This API has been deprecated. We recommend you use TXPlayerGlobalSetting#setMaxCacheSizeMB.
Sets the player type.
Sets custom HTTP headers.
Sets whether to enable accurate seek. Default value: true.
If it is set to YES, the MP4 file will be automatically rotated according to the rotation angle set in the file, which can be obtained from the PLAY_EVT_CHANGE_ROTATION event. Default value: YES
Sets whether to enable smooth switch for multi-bitrate HLS streams. Default value: false.
Sets the progress callback interval in ms.
Sets the maximum preloading buffer size in MB.
Sets the maximum preloading buffer size in MB.
Sets the duration (in ms) of the video data that needs to be loaded during the first buffering. Default value: 100 ms.
The minimum buffered data size to stop buffering (secondary buffering for insufficient buffered data or progress bar drag buffering caused by seek) in ms. Default value: 250 ms.
Sets the HLS security hardening encryption and decryption key.
Sets the HLS security hardening encryption and decryption IV.
Sets the extended information.
Starts playing back the most preferred bitstream according to the configured preferredResolution if there are multiple HLS bitstreams. Here, preferredResolution is the product of the video width and height (width x height) and can only take effect if it is set before playback starts.
Sets whether to allow postrendering and postproduction features such as super resolution plugin, which is enabled by default.
The video format called back by the video rendering object.
Whether to retain the last image frame when stopPlay is called. Default value: NO.
Sets the media asset type.

TXPlayerGlobalSetting

Global configuration of the VOD player.
API
Description
Sets the cache directory of the playback engine. After setting, this directory will be first read and written during predownloading and player use.
Sets the maximum cache size in MB of the playback engine. After setting, the backend will clear files in the cache directory automatically according to the set value.

TXVodPreloadManager

Predownloading API class of the VOD player.
API
Description
Gets the TXVodPreloadManager instance object in singleton mode.
Sets the playback engine cache directory (TXPlayerGlobalSetting#setCacheFolderPath) and cache size (TXPlayerGlobalSetting#setMaxCacheSize) before starting predownloading.
Stops predownloading.

Callback for video predownloading

API
Description
The callback for download completion.
The callback for download error.

TXVodDownloadManager

Video download API class of the VOD player.

TXVodDownloadDataSource

API
Description
The fileid information.
The download definition, which is the original resolution by default.
Enter the token if the address is encrypted.
The definition template.
The file ID.
The signature information.
The application's appId, which is required.
The account name.
The HLS EXT-X-KEY encryption/decryption parameter.
The overlayIv encryption/decryption parameter.

TXVodDownloadMediaInfo

API
Description
Whether download is completed.
The download object specified byfileid, which is optional.
The download address.
The account name.
The duration.
The playable duration.
The total file size in bytes.
The size of the downloaded part in bytes.
The total number of segments.
The number of downloaded segments.
The progress.
The playback path, which can be passed in to TXVodPlayer for playback.
The download speed in B/s.
The download status.

TXVodDownloadManager

API
Description
Gets the TXVodDownloadManager instance object in singleton mode.
Sets the download root directory.
Sets download HTTP headers.
Sets the download callback method, which must be set before download.
Starts downloading the video at the specified URL.
Starts downloading the video of the specified FileID.
Stops the download. If ITXVodDownloadListener.onDownloadStop is called back, the download stops successfully.
Deletes the downloaded file.
Deletes the download information.
Gets the download lists of all users.
Gets the download information.
Gets the HLS EXT-X-KEY.
Gets a random number for encryption.
Encrypts.

TXVodDownloadDelegate

API
Description
Download started.
The download progress was updated.
Download stopped.
Download ended.
An error occurred during download.
Verifies the decryption key by the player if an encrypted file is found during HLS stream download.

TXDownloadError

The download error code
Enumerated Value
Description
TXDownloadSuccess
Download succeeded.
TXDownloadAuthFaild
Failed to authenticate the fileid.
TXDownloadNoFile
The file with the specified resolution does not exist.
TXDownloadFormatError
The format is not supported.
TXDownloadDisconnet
The network was disconnected.
TXDownloadHlsKeyError
Failed to get the HLS decryption key.
TXDownloadPathError
Failed to access the download directory.

TXVodDownloadMediaInfoState

The download status
Enumerated Value
Description
TXVodDownloadMediaInfoStateInit
Download was initialized.
TXVodDownloadMediaInfoStateStart
Download started.
TXVodDownloadMediaInfoStateStop
Download stopped.
TXVodDownloadMediaInfoStateError
An error occurred during download.
TXVodDownloadMediaInfoStateFinish
Download was completed.

TXVodQuality

The definition of the downloaded video
Enumerated Value
Description
TXVodQualityOD
Original
TXVodQualityFLU
LD
TXVodQualitySD
SD
TXVodQualityHD
HD
TXVodQualityFHD
FHD
TXVodQuality2K
2K
TXVodQuality4K
4K

TXPlayerAuthParams

The configuration for encrypted video playback through fileId.
API
Description
The application's appId.
The file ID.
The encrypted link timeout timestamp.
The preview duration.
The unique request ID.
The hotlink protection signature.
Whether to use HTTPS requests.

TXBitrateItem

The HLS multi-bitrate information.
API
Description
The number of the stream in the m3u8 file.
The video width of this stream.
The video height of this stream.
The video bitrate of this stream.

TXImageSprite

The image sprite parsing tool.
API
Description
Sets the image sprite URL.
Gets a thumbnail.

TXPlayerDrmBuilder

The VOD DRM constructor.
API
Description
The URL of the certificate provider.
The URL of the decryption key.
The playback URL.

Error Codes

Normal events

Code
Event Definition
Description
2004
PLAY_EVT_PLAY_BEGIN
Video playback started, and the loading icon animation (if any) ended.
2005
PLAY_EVT_PLAY_PROGRESS
Video playback progress (including the current playback progress, loading progress, and total video duration).
2007
PLAY_EVT_PLAY_LOADING
The video is being loaded. The LOADING_END event will be reported if video playback resumes.
2014
PLAY_EVT_VOD_LOADING_END
Video loading ended, and video playback resumed.
2006
PLAY_EVT_PLAY_END
Video playback ended.
2013
PLAY_EVT_VOD_PLAY_PREPARED
The player has been prepared and can start playback.
2003
PLAY_EVT_RCV_FIRST_I_FRAME
The network received the first renderable video data packet (IDR).
2009
PLAY_EVT_CHANGE_RESOLUTION
The video resolution changed.
2011
PLAY_EVT_CHANGE_ROTATION
The MP4 video was rotated.

Warnings

Code
Event Definition
Description
-2301
PLAY_ERR_NET_DISCONNECT
The network was disconnected and could not be reconnected after multiple retries. You can restart the player to perform more connection retries.
-2305
PLAY_ERR_HLS_KEY
Failed to get the HLS decryption key.
2101
PLAY_WARNING_VIDEO_DECODE_FAIL
Failed to decode the current video frame.
2102
PLAY_WARNING_AUDIO_DECODE_FAIL
Failed to decode the current audio frame.
2103
PLAY_WARNING_RECONNECT
The network was disconnected, and automatic reconnection was performed (the PLAY_ERR_NET_DISCONNECT event will be thrown after three failed attempts).
2106
PLAY_WARNING_HW_ACCELERATION_FAIL
Failed to start the hardware decoder, and the software decoder was used instead.
-2304
PLAY_ERR_HEVC_DECODE_FAIL
Failed to decode with H.265.
-2303
PLAY_ERR_FILE_NOT_FOUND
The file to be played back does not exist.

Player SDK Constants

Definitions of event codes and error codes

Enumerated Value
Description
VOD_PLAY_EVT_RCV_FIRST_I_FRAME
Playback event: Received the first video frame successfully.
VOD_PLAY_EVT_RCV_FIRST_AUDIO_FRAME
Playback event: Received the first audio frame successfully.
VOD_PLAY_EVT_PLAY_BEGIN
Playback event: Playback started.
VOD_PLAY_EVT_PLAY_PROGRESS
Playback event: The playback progress was updated. This event is applicable to the VOD player only.
VOD_PLAY_EVT_PLAY_END
Playback event: Playback ended.
VOD_PLAY_EVT_PLAY_LOADING
Playback event: The data is buffering.
VOD_PLAY_EVT_START_VIDEO_DECODER
Playback event: The video decoder started.
VOD_PLAY_EVT_CHANGE_RESOLUTION
Playback event: The video resolution changed.
VOD_PLAY_EVT_GET_PLAYINFO_SUCC
Playback event: Obtained the information of the VOD file successfully. This event is applicable to the VOD player only.
VOD_PLAY_EVT_CHANGE_ROTATION
Playback event: The rotation angle of the MP4 video changed. This event is applicable to the VOD player only.
VOD_PLAY_EVT_VOD_PLAY_PREPARED
Playback event: Video loading was completed. This event is applicable to the VOD player only.
VOD_PLAY_EVT_VOD_LOADING_END
Playback event: Video buffering ended. This event is applicable to the VOD player only.
VOD_PLAY_EVT_STREAM_SWITCH_SUCC
Playback event: Switched the video stream between different definitions successfully.
VOD_PLAY_EVT_VOD_PLAY_TCP_CONNECT_SUCC
TCP connection succeeded.
VOD_PLAY_EVT_VOD_PLAY_FIRST_VIDEO_PACKET
Received the first data frame successfully.
VOD_PLAY_EVT_VOD_PLAY_SEEK_COMPLETE
Video playback seeking was completed.
VOD_PLAY_EVT_AUDIO_SESSION_INTERRUPT
Playback event: The audio session was interrupted by another app. This event is applicable to iOS only.
VOD_PLAY_ERR_NET_DISCONNECT
Live streaming error: The network was disconnected and couldn't be reconnected after three retries.
VOD_PLAY_ERR_FILE_NOT_FOUND
VOD error: The file to be played back does not exist.
VOD_PLAY_ERR_HLS_KEY
VOD error: Failed to get the HLS decryption key.
VOD_PLAY_ERR_GET_PLAYINFO_FAIL
VOD error: Failed to get the information of the VOD file.

PiP error type

Enumerated Value
Description
TX_VOD_PLAYER_PIP_ERROR_TYPE_NONE
No error.
TX_VOD_PLAYER_PIP_ERROR_TYPE_DEVICE_NOT_SUPPORT
The device model or system version doesn't support PiP (only supported on iPadOS 9+ and iOS 14+).
TX_VOD_PLAYER_PIP_ERROR_TYPE_PLAYER_NOT_SUPPORT
The player doesn't support PiP.
TX_VOD_PLAYER_PIP_ERROR_TYPE_VIDEO_NOT_SUPPORT
The video doesn't support PiP.
TX_VOD_PLAYER_PIP_ERROR_TYPE_PIP_IS_NOT_POSSIBLE
The PiP controller is unavailable.
TX_VOD_PLAYER_PIP_ERROR_TYPE_ERROR_FROM_SYSTEM
The PiP controller reported an error.
TX_VOD_PLAYER_PIP_ERROR_TYPE_PLAYER_NOT_EXIST
The player object does not exist.
TX_VOD_PLAYER_PIP_ERROR_TYPE_PIP_IS_RUNNING
The PIP feature is running.
TX_VOD_PLAYER_PIP_ERROR_TYPE_PIP_NOT_RUNNING
The PIP feature has not been started.

PiP controller status

Enumerated Value
Description
TX_VOD_PLAYER_PIP_STATE_UNDEFINED
No status is set.
TX_VOD_PLAYER_PIP_STATE_WILL_START
PiP will start soon.
TX_VOD_PLAYER_PIP_STATE_DID_START
PiP started.
TX_VOD_PLAYER_PIP_STATE_WILL_STOP
PiP will end soon.
TX_VOD_PLAYER_PIP_STATE_DID_STOP
PiP ended.
TX_VOD_PLAYER_PIP_STATE_RESTORE_UI
The UI was reset.
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.

Contact Us
Technical Support

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

Submit a Ticket
7x24 Phone Support