tencent cloud

All product documents
Video on Demand
DocumentationVideo on DemandPlayer SDKAPI DocumentationiOS
iOS
Download PDF
Last updated: 2024-11-22 17:02:47
iOS
Last updated: 2024-11-22 17:02:47
Download PDF

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:
Play FLV, MP4, and HLS files by URL (general playback) or by file ID (VOD playback).
Take screenshots of the video stream.
Adjust the brightness, volume level, and playback progress using gestures.
Change the resolution manually or select a resolution automatically according to current network bandwidth.
Change the playback speed, flip the video, and use hardware decoding for acceleration.
For more information on the capabilities of the player, see Video Playback Overview.

Player configuration APIs

API
Description
config
Configures VOD. For more information on the configuration, see TXVodPlayConfig.
Sets whether to start playback automatically after startVodPlay is called. Auto-play is on by default.
token
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.
loop
Sets whether to loop SurfaceView.
Sets whether to enable hardware acceleration.
Sets the player business parameters in the format of <NSString *, id>.
setSubtitleStyle
Set the subtitle style information, and the subtitle style can be updated after playback (only supported by the advanced version of the player).
setAudioNormalization
Setting volume normalization, loudness range: -70 to 0 (LUFS). Supported from player version 11.7 of the premium version. You can set the volume normalization to preset values or custom values. The preset values are defined in the related classes or files, such asTXVodConstants for Android and TXVodPlayConfig.hfor iOS: Off: AUDIO_NORMALIZATION_OFF
On: AUDIO_NORMALIZATION_STANDARD (standard) AUDIO_NORMALIZATION_LOW (low) AUDIO_NORMALIZATION_HIGH (high) Custom values can be set in the range of -70 to 0 LUFS, from low to high.

Basic playback APIs

API
Description
Plays a video from an HTTP URL. Since v10.7, startPlay has been replaced by startVodPlay, and you need to call V2TXLivePremier#setLicence or TXLiveBase#setLicence to set the license in order to use the playback feature (you only need to set the license once). Otherwise, playback will fail (black screen). You can use a live stream publishing license, UGSV license, or video playback license to activate the playback feature.
Start a standard FairPlay DRM playback.
Plays a video by VOD file ID. Since v10.7, startPlayWithParams has been replaced by startVodPlayWithParams, and you need to call V2TXLivePremier#setLicence or TXLiveBase#setLicence to set the license in order to use the playback feature (you only need to set the license once). Otherwise, playback will fail (black screen). You can use a live stream publishing license, UGSV license, or video playback license to activate the playback feature.
stopPlay
Stops the audio/video stream.
isPlaying
Gets whether playback is ongoing.
pause
Pauses playback. The player will stop pulling data and freeze on the last frame.
resume
Resumes playback. The player will resume pulling data.
seek
Seeks to a specified time point of the video stream (in seconds).
Gets the current playback time point in seconds.
duration
Gets the total video duration in seconds.
Gets the playable video duration in seconds.
width
Gets the video width.
height
Gets the video height.
Sets the playback start time.
Create a Video rendering View, which hosts the display of video content.
Remove Video rendering View .
Add external subtitles (only supported by the advanced version of the player).
Returns the list of subtitle track information (only supported by the advanced version of the player).
Returns the list of audio track information (supported only by the advanced version of the player).
Select a track (supported only in the premium version of the player).
Deselects a track (only supported in advanced versions of the player).
seekToPdtTime
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. This function is supported starting from version 11.6 of the player's advanced edition. The parameter unit is milliseconds (ms).

Video APIs

API
Description
snapshot
Gets the current video frame image.
Note: Because this operation is time-consuming, the screenshot will be called back asynchronously.
setMirror
Sets whether to flip the video image.
setRate
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.
You may need to wait momentarily to switch the definition.
When the playback address is a master playlist, return the supported bitrates (resolutions).
Sets the image fill mode.
Sets the rotation.
Enter the picture-in-picture function.
Exit the picture-in-picture function.

Audio APIs

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

Event notification APIs

API
Description
delegate
Sets player callbacks. We recommend you use vodDelegate instead.
Sets player callbacks.
Sets the video rendering callback (supported only if hardware encoding is used).

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 method.

API
Description
Get the encrypted playback key for content protection.
Whether Picture-in-Picture (PiP) function is supported.

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.
Network status notification of the VOD player.
Picture-in-Picture state callback.
Picture-in-Picture error state callback.

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.
timeout
Sets the player connection timeout period in seconds.
cacheFolderPath
This interface has been deprecated. It is recommended to useTXPlayerGlobalSetting##setCacheFolderPath.
Sets the VOD cache directory, which takes effect for MP4 and HLS files.
maxCacheItems
This interface has been deprecated. It is recommended to useTXPlayerGlobalSetting#setMaxCacheSizeMB.
Sets the maximum number of cached files.
Sets the player type.
PLAYER_AVPLAYER: Use the system's built-in player.
PLAYER_THUMB_PLAYER: Use Tencent Cloud's self-developed player.
headers
Sets custom HTTP headers.
Sets whether to enable accurate seek. Default value: true.
Sets whether to enable auto rotation. If the parameter is set to YES (default), MP4 files will be automatically rotated.
You can get the rotation angle from the PLAY_EVT_CHANGE_ROTATION callback.
Sets whether to enable smooth switch for multi-bitrate HLS streams. Default value: false.
Sets the progress callback interval in ms.
Sets the maximum buffer size in MB.
Sets the maximum preloading size in MB.
Sets the duration (ms) of video that needs to be loaded before playback starts. Default value: 100 ms.
Sets the minimum data to buffer when there is insufficient buffer data or after seeking is performed. Default value: 250 ms.
Sets the HLS security hardening encryption and decryption key.
overlayIv
Sets the HLS security hardening encryption and decryption IV.
Sets the extended information.
Sets the preferred resolution. In case of multi-bitrate HLS streams, the resolution specified by preferredResolution (width x height) will be played. This API works only if it is called before playback.
Sets whether to enable post-rendering and post-processing (such as that used by the super-resolution plugin). They are enabled by default.
The video format of the video rendering object callback.
Whether to keep the last frame when calling `stopPlay`, with a default value of NO.
mediaType
Set the media type. Optional values are:
MEDIA_TYPE_AUTO, AUTO type (default value, not supported for adaptive bitrate playback).
MEDIA_TYPE_HLS_VOD, HLS on-demand media.
MEDIA_TYPE_HLS_LIVE, HLS live media.
MEDIA_TYPE_HLS_VOD, MP4 and other general file on-demand media (supported since version 11.2).
MEDIA_TYPE_DASH_VOD, DASH on-demand media (supported since version 11.2).
encryptedMp4Level
Set the MP4 playback and storage encryption level. Supported since the Advanced Player 12.2. Currently supported:
MP4_ENCRYPTION_LEVEL_NONE: non-encrypted playback, supported by default.
MP4_ENCRYPTION_LEVEL_L2: MP4 local encrypted playback.

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 playback engine’s maximum cache size in MB. The cache directory will be cleared automatically if its size exceeds the specified value.

TXVodPreloadManager

Predownloading API class of the VOD player.
API
Description
Gets a singleton object of TXVodPreloadManager.
Starts predownloading. Before you call this API, make sure you have called TXPlayerGlobalSetting#setCacheFolderPath and TXPlayerGlobalSetting#setMaxCacheSize to set the cache directory and maximum cache size.
Stops predownloading.

 TXVodPreloadManagerDelegate

API
Description
Download completion callback.
Download error callback.

TXVodDownloadManager

Video download API class of the VOD player.

TXVodDownloadDataSource

API
Description
auth
File ID information.
quality
Download definition, default original.
token
If the address is encrypted, please fill in the token.
Definition template.
fileId
File ID.
pSign
Signature information.
appId
Application AppID. Required.
userName
Account name.
HLS EXT-X-KEY encryption and decryption parameters.
overlayIv
Encryption and decryption parameter overlayIv.

TXVodDownloadMediaInfo

API
Description
Whether the download is complete.
FileID download object (optional).
url
Download address.
userName
Account name.
duration
Duration.
Playable duration.
size
Get the total size of the downloaded file, in bytes, only valid for FileID download sources. Note: The total size refers to the size of the original file uploaded to the Tencent Cloud VOD console, and the size of the sub-streams after being converted to adaptive bitrate streams cannot be obtained temporarily.
Downloaded size, in bytes.
segments
Total number of segments.
Number of segments downloaded.
progress
Progress.
playPath
Play path, can be passed to TXVodPlayer for playback.
speed
Download speed, in bytes per second.
Download status.
isResourceBroken
Determine whether the downloaded video resource is damaged, and return YES if it is deleted after downloading, etc. (Supported since version 11.0).

TXVodDownloadManager

API
Description
Get the TXVodDownloadManager instance object, singleton mode.
Set the download root directory.
headers
Set the download HTTP headers.
delegate
Set the download callback method, which must be set before downloading.
Start downloading using URL.
Start downloading using FileID.
Stop downloading, and stop successfully when ITXVodDownloadListener.onDownloadStop is called back.
Delete the downloaded file.
Delete the download information.
Get the download list information for all users.
Get the download information.
Get the HLS EXT-X-KEY. genRandomHexStringForHls
Get the encryption random number.
Encryption.

TXVodDownloadDelegate

API
Description
Download started.
The download progress was updated.
Download stopped.
Download ended.
An error occurred during download.
The decryption key for downloading encrypted HLS files.

TXDownloadError

Download Error Code
Enumeration value
Description
TXDownloadSuccess
Download successful.
TXDownloadAuthFaild
File ID authentication failed.
TXDownloadNoFile
No file of this definition.
TXDownloadFormatError
Format not supported.
TXDownloadDisconnet
Network disconnected.
TXDownloadHlsKeyError
Failed to obtain HLS decryption key.
TXDownloadPathError
Failed to access download directory.

TXVodDownloadMediaInfoState

Download Status
Enumeration value
Description
TXVodDownloadMediaInfoStateInit 
Download initial state.
TXVodDownloadMediaInfoStateStart
Download started.
TXVodDownloadMediaInfoStateStop
Download stopped.
TXVodDownloadMediaInfoStateError
Download error.
TXVodDownloadMediaInfoStateFinish
Download completed.

TXVodQuality

The resolution of the downloaded video.
Explanation：
The constants TXVodQuality240P ~ TXVodQuality1080p are newly added in version 11.0.
Enumeration value
Description
TXVodQualityOD
Original.
TXVodQualityFLU
Smooth.
TXVodQualitySD
Standard Definition.
TXVodQualityHD
High Definition.
TXVodQualityFHD
Full High Definition.
TXVodQuality2K
2K.
TXVodQuality4K
4K.
TXVodQuality240P
Smooth 240P.
TXVodQuality360P
Smooth 360P.
TXVodQuality480P
Standard Definition 480P.
TXVodQuality540P
Standard Definition 540P.
TXVodQuality720P
High Definition 720P.
TXVodQuality1080p
High Definition 1080P.

TXPlayerAuthParams

Play encrypted video configuration by fileId.
API
Description
appId
App appId.
fileId
File id.
timeout
Encrypted link timeout timestamp.
exper
Try the duration.
us
Uniquely identifies the request.
sign
Anti-leech signature.
https
Whether to use https requests.

TXBitrateItem

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

TXImageSprite

Sprite analysis tool.
API
Description
setVTTUrl
Set the sprite map address.
Get a thumbnail.

TXPlayerDrmBuilder

On-demand Drm builder.
API
Description
Certificate provider URL.
Decrypt the key URL.
playUrl
play link.

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
The video playback progress (including the current playback progress, the loaded duration, and the 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 is ready.
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 player was disconnected and is trying to reconnect. 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
H.265 decoding failed.
-2303
PLAY_ERR_FILE_NOT_FOUND
The file to be played back does not exist.

Player SDK constants.

Event code and error code

Enumeration value
Meaning
VOD_PLAY_EVT_RCV_FIRST_I_FRAME
Playback event: The first video frame was successfully received.
VOD_PLAY_EVT_RCV_FIRST_AUDIO_FRAME
Play event: The first audio frame was successfully received.
VOD_PLAY_EVT_PLAY_BEGIN
Play event: Play has started.
VOD_PLAY_EVT_PLAY_PROGRESS
Play event: Play progress update, dedicated to VodPlayer.
VOD_PLAY_EVT_PLAY_END
Play event: Play has ended.
VOD_PLAY_EVT_PLAY_LOADING
Play event: data buffering.
VOD_PLAY_EVT_START_VIDEO_DECODER
Playback event: The video decoder has started.
VOD_PLAY_EVT_CHANGE_RESOLUTION
Playback event: Video resolution changed.
VOD_PLAY_EVT_GET_PLAYINFO_SUCC
Play event: the information about successfully obtaining the VOD file, dedicated to the VOD player (VodPlayer).
VOD_PLAY_EVT_CHANGE_ROTATION
Play event: The rotation angle of the MP4 video changes, dedicated to VodPlayer.
VOD_PLAY_EVT_VOD_PLAY_PREPARED
Play event: Video loading is complete, dedicated to VodPlayer.
VOD_PLAY_EVT_VOD_LOADING_END
Play event: Video buffering ends, dedicated to VodPlayer.
VOD_PLAY_EVT_STREAM_SWITCH_SUCC
Playback event: Stream switching (switching between video streams with different resolutions) has been successfully completed.
VOD_PLAY_EVT_VOD_PLAY_TCP_CONNECT_SUCC
The TCP connection was successful.
VOD_PLAY_EVT_VOD_PLAY_FIRST_VIDEO_PACKET
The first frame of data is received.
VOD_PLAY_EVT_VOD_PLAY_SEEK_COMPLETE
Video playback Seek complete.
VOD_PLAY_EVT_AUDIO_SESSION_INTERRUPT
Playback event: Audio Session is interrupted by other apps (applicable to iOS platform only).
VOD_PLAY_ERR_NET_DISCONNECT
Streaming Error: The network connection was disconnected (after three retries and failed to reconnect).
VOD_PLAY_ERR_FILE_NOT_FOUND
On-demand error: The playback file does not exist.
VOD_PLAY_ERR_HLS_KEY
On-demand error: Failed to obtain HLS decoding KEY.
VOD_PLAY_ERR_GET_PLAYINFO_FAIL
On-demand error: Failed to obtain the file information of the on-demand file.

Picture-in-picture error type

Enumeration value
Meaning
TX_VOD_PLAYER_PIP_ERROR_TYPE_NONE
No errors.
TX_VOD_PLAYER_PIP_ERROR_TYPE_DEVICE_NOT_SUPPORT
The device or system version does not support (iPad iOS9+ only supports PIP).
TX_VOD_PLAYER_PIP_ERROR_TYPE_PLAYER_NOT_SUPPORT
Player does not support.
TX_VOD_PLAYER_PIP_ERROR_TYPE_VIDEO_NOT_SUPPORT
Video not supported.
TX_VOD_PLAYER_PIP_ERROR_TYPE_PIP_IS_NOT_POSSIBLE
PIP controller not available.
TX_VOD_PLAYER_PIP_ERROR_TYPE_ERROR_FROM_SYSTEM
The PIP controller reports 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 function is already running.
TX_VOD_PLAYER_PIP_ERROR_TYPE_PIP_NOT_RUNNING
PIP function is not started.

Picture-in-picture controller status

Enumeration value
Meaning
TX_VOD_PLAYER_PIP_STATE_UNDEFINED
Not Set.
TX_VOD_PLAYER_PIP_STATE_WILL_START
Picture-in-picture is about to start.
TX_VOD_PLAYER_PIP_STATE_DID_START
Picture-in-picture has started.
TX_VOD_PLAYER_PIP_STATE_WILL_STOP
Picture-in-picture is coming to an end.
TX_VOD_PLAYER_PIP_STATE_DID_STOP
Picture-in-picture is over.
TX_VOD_PLAYER_PIP_STATE_RESTORE_UI
reset UI.

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 avaliable.

Submit a Ticket
7x24 Phone Support
Hong Kong, China
+852 800 906 020 (Toll Free)
United States
+1 844 606 0804 (Toll Free)
United Kingdom
+44 808 196 4551 (Toll Free)
Canada
+1 888 605 7930 (Toll Free)
Australia
+61 1300 986 386 (Toll Free)
EdgeOne hotline
+852 300 80699
More local hotlines coming soon