tencent cloud

TXVodPlayer
Download PDF
Last updated: 2025-12-12 11:08:09
TXVodPlayer
Last updated: 2025-12-12 11:08:09
Download PDF

TXVodPlayer API Introduction

TXVodPlayer serves as the core playback class, primarily handling playback controls including play/pause operations and speed adjustment. For comprehensive player capabilities, please refer to the Player SDK feature specifications.

Interface Overview

Basic playback interface

API
Description
To play HTTP URL-formatted addresses:
Starting from version 10.7, startPlay has been renamed to startVodPlay. You must set the Licence via +[TXLiveBase setLicenceURL:key:] before playback will succeed; otherwise, playback will fail (black screen). The Licence only needs to be set once globally.
Live License, Short Video License, and Player License are all acceptable for this use case. If you haven't obtained any of these licenses yet, you may click 'Player License' to apply. Please note that formal version licenses require purchase.
To play using fileId, pass the TXPlayInfoParams parameter. Starting from version 10.7, 'startPlay' has been renamed to 'startVodPlay'. You must configure the license using +[TXLiveBase setLicenceURL:key:] for successful playback - otherwise playback will fail (black screen). The license only needs to be set once globally.
Live License, Short Video License, and Player License are all acceptable for this use case. If you haven't obtained any of these licenses yet, you may click 'Player License' to apply. Please note that formal version licenses require purchase.
Start a standard FairPlay DRM playback.
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 the specified time point of the video stream (in seconds).
Seeks to the specified time point in the video stream, in seconds, with an accuracy of 3 decimal places. Supports precise seek.
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 whether to start playback automatically after startVodPlay is called. Auto-play is on by default.
Sets whether to enable hardware acceleration.
Sets the playback start time.
Create a Video rendering View, which hosts the display of video content.
Remove Video rendering View .
token
Sets the token for HLS encryption.
Get the encrypted playback key for content protection.
loop
Set whether to loop playback.
Add external subtitles (supported by the premium version of the player).
Returns the list of subtitle track information (only supported by the premium version of the player).
Returns the list of audio track information (supported only by the premium version of the player).
Select a track (supported only in the premium version of the player).
Deselects a track (only supported in premium versions of the player).
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 premium edition. The parameter unit is milliseconds (ms).

Player configuration APIs

API
Description
config
Configures VOD. For more information on the configuration, see TXVodPlayConfig.
Sets the player business parameters in the format of <NSString *, id>.
Set the subtitle style information, and the subtitle style can be updated after playback (only supported by the premium version of the player).
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.

Video related interfaces

API
Description
Sets whether to enable hardware acceleration.
snapshot:
Gets the current video frame image.
Note: Because this operation is time-consuming, the screenshot will be called back asynchronously.
Sets whether to flip the video image.
setRate:
Sets the VOD playback speed. Default value: 1.0.
Returns the current playback bitrate index.
When the playback address is a master playlist, return the supported bitrates (resolutions).
Sets the current playback bitrate index for seamless definition switch.
You may need to wait momentarily to switch the definition.
Sets the image fill mode.
Sets the rotation.
Set the highest bitrate that can be switched for adaptive playback.

Picture-in-picture related interfaces

API
Description
Whether Picture-in-Picture (PiP) function is supported.
Whether to support seamless switching of picture-in-picture function.(Only available in the Premium version of the player).
Set whether to automatically start picture-in-picture.(Only available in the Premium version of the player).
Enter picture-in-picture.
Exit picture-in-picture.

Audio related interfaces

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

Event Notification Interface

API
Description
Set the player event callback object.
Set the video rendering callback object.

TRTC video playback related interfaces

You can push the VOD player's audio streams via TRTC using the following APIs. For more TRTC services, refer to the TRTC Product Overview.
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.

Interface Details

startVodPlay:

Start playback via a URL.。
Starting from version 10.7, you need to set the license through +[TXLiveBase setLicenceURL:key:] to play successfully, otherwise the playback will fail (black screen). You only need to set it once globally.
- (int)startVodPlay:(NSString *)url;
Parameter Description
Parameter Name
Type
Description
url
NSString
Playback address.
Return Value
0： Playback successful.
Non-zero： Playback failed.

startVodPlayWithParams:

To play using fileId, pass the TXPlayInfoParams parameter.
Starting from version 10.7, 'startPlay' has been renamed to 'startVodPlay'. You must configure the license using +[TXLiveBase setLicenceURL:key:] for successful playback - otherwise playback will fail (black screen). The license only needs to be set once globally.
- (int)startVodPlayWithParams:(TXPlayerAuthParams *)params;
Parameter Description
Parameter Name
Type
Description
params
Video fieldID and information.
Return Value
0： Playback successful.
Non-zero： Playback failed.

startPlayDrm:

Play DRM encrypted video.
Starting from version 10.7, 'startPlay' has been renamed to 'startVodPlay'. You must configure the license using +[TXLiveBase setLicenceURL:key:] for successful playback - otherwise playback will fail (black screen). The license only needs to be set once globally.
Note:
Only the premium version of the player supports it.
- (int)startPlayDrm:(TXPlayerDrmBuilder *)drmBuilder;
Parameter Description
Parameter Name
Type
Description
drmBuilder
DRM playback information.
Return Value
0: Playback successful.
Non-zero: Playback failed.

stopPlay

Stop playback.
- (int)stopPlay;
Return Value
0: Stop successful.
Non-zero: Stop failed.

isPlaying

Whether it is playing.
- (bool)isPlaying;

pause

Pause playback.
- (void)pause;

resume

Resume playback.
- (void)resume;

seek:

Jump to a specified time point in the video stream.
- (int)seek:(float)time;
Parameter Description
Parameter Name
Type
Description
time
float
Video stream time point, in seconds.
Return Value
0: Seek successful.
Non-zero: Seek failed.

seek:accurateSeek:

Jump to a specified time point in the video stream.
- (void)seek:(float)time accurateSeek:(BOOL)isAccurateSeek;
Parameter Description
Parameter Name
Type
Description
time
float
Video stream time point, in seconds, accurate to 3 decimal places.
isAccurateSeek
BOOL
Whether the Seek is accurate.
YES: Indicates an accurate Seek. Must find the current time point. This will take longer.
NO: Indicates an imprecise Seek, that is, searching for the previous I-frame.

seekToPdtTime:

Navigate to the specified time point in the video stream.
Note:
Player premium 11.6 edition starts to support.
- (void)seekToPdtTime:(long long)pdtTimeMs;
Parameter Description
Parameter Name
Type
Description
pdtTimeMs
long long
Video stream PDT time point, unit milliseconds.

currentPlaybackTime

Retrieve the current playback time point, in seconds.
- (float)currentPlaybackTime;

duration

Retrieve the total video duration, in seconds.
- (float)duration;

playableDuration

Retrieve the current playable video duration, in seconds.
- (float)playableDuration;

width

Get video width.
- (int)width;

height

Retrieve video height.
- (int)height;

setupVideoWidget:insertIndex:

Set the player to render View Host the display of video content
- (void)setupVideoWidget:(NSView *)view insertIndex:(unsigned int)idx;

removeVideoWidget

Remove the player's render View.
- (void)removeVideoWidget;

isAutoPlay

Set whether to autoplay after startPlay. Autoplay is enabled by default.
@property BOOL isAutoPlay;

setStartTime:

Set the playback start time in seconds. It needs to be set before starting playback.
- (void)setStartTime:(CGFloat)startTime;
Parameter Description
Parameter Name
Type
Description
startTime
CGFloat
Video stream time point, in seconds, accurate to 3 decimal places.

token

Set the encryption token for HLS. After setting this value, the player automatically adds `voddrm.token` before the file name in the URL.
@property(nonatomic, strong) NSString *token;

getEncryptedPlayKey:

Retrieve the encrypted playback key for reinforcement.
+ (NSString *)getEncryptedPlayKey:(NSString *)key;

loop

Whether to loop playback.
@property(nonatomic, assign) BOOL loop;

addSubtitleSource:name:mimeType:

Add external subtitle.
Note:
Player premium version only supports.
- (void)addSubtitleSource:(NSString *)url name:(NSString *)name mimeType:(TX_VOD_PLAYER_SUBTITLE_MIME_TYPE)mimeType;
Parameter Description
Parameter Name
Type
Description
url
NSString
Subtitle address, supports Http link and local storage absolute path.
name
NSString
Subtitle name. If adding multiple subtitles, set the subtitle names to different names for distinguishing from other added subtitles; otherwise, it may lead to subtitle selection error.
mimeType
TX_VOD_PLAYER_SUBTITLE_MIME_TYPE
Subtitle type, only supports VVT and SRT formats. For details, see TX_VOD_PLAYER_SUBTITLE_MIME_TYPE.

getSubtitleTrackInfo

Return to subtitle track information list.
Note:
Player premium version only supports.
- (NSArray<TXTrackInfo *> *)getSubtitleTrackInfo;
Return Value
NSArray<TXTrackInfo *> * : subtitle track information list.

getAudioTrackInfo

Return to audio track information list.
Note:
Player premium version only supports.
- (NSArray<TXTrackInfo *> *)getAudioTrackInfo;
Return Value
NSArray<TXTrackInfo *> * : audio track information list.

selectTrack:

Select a track.
Note:
Player premium version only supports.
- (void)selectTrack:(NSInteger)trackIndex;
Parameter Description
Parameter Name
Type
Description
trackIndex
NSInteger
Track index, obtained through -[TXTrackInfo getTrackIndex].

deselectTrack:

Cancel track selection.
Note:
Player premium version only supports.
- (void)deselectTrack:(NSInteger)trackIndex;
Parameter Description
Parameter Name
Type
Description
trackIndex
NSInteger
Track index, obtained through -[TXTrackInfo getTrackIndex].

config

Set player configuration information, refer to TXVodPlayConfig.
@property(nonatomic, copy) TXVodPlayConfig *config;

setExtentOptionInfo:

Set player business parameters, parameter format is <NSString, id>.
- (void)setExtentOptionInfo:(NSDictionary<NSString *, id> *)extInfo;

setSubtitleStyle:

Set subtitle style information, supports pre-play configuration, and can support updating subtitle styles after playback.
Note:
Player premium version only supports.
- (void)setSubtitleStyle:(TXPlayerSubtitleRenderModel *)renderModel;
Parameter Description
Parameter Name
Type
Description
renderModel
Subtitle style configuration parameters.

setAudioNormalization:

Set volume balance, loudness range: -70 to 0 (LUFS).
Note:
Player premium version only supports.
- (void)setAudioNormalization:(float)value;
Parameter Description
Parameter Name
Type
Description
value
float
Preset value can be filled in (related class or file: Android: TXVodConstants; iOS: TXVodPlayConfig.h)
Off: AUDIO_NORMALIZATION_OFF
On: AUDIO_NORMALIZATION_ON
AUDIO_NORMALIZATION_STANDARD
AUDIO_NORMALIZATION_LOW
AUDIO_NORMALIZATION_HIGH
Custom value can be entered: ranging from low to high, range -70 to 0 LUFS.

setAutoMaxBitrate:

Set switchable adaptive playback with maximum bit rate.
- (void)setAutoMaxBitrate:(NSInteger)autoMaxBitrate;

enableHWAcceleration

Enable or disable video hardware decoding, hardware decoding is enabled by default.
@property(nonatomic, assign) BOOL enableHWAcceleration;

snapshot:

Retrieve the current video frame image.
- (void)snapshot:(void (^)(UIImage *))snapshotCompletionBlock;
Parameter Description
Parameter Name
Type
Description
snapshotCompletionBlock
void (^)(UIImage *)
Screenshot callback interface class

setMirror:

Set mirror video.
- (void)setMirror:(BOOL)isMirror;

setRate:

Set the playback speed of on-demand video. Default is 1.0.
- (void)setRate:(float)rate;
Parameter Description
Parameter Name
Type
Description
rate
float
Playback speed [0.5, 3.0].

bitrateIndex

Return the bitrate index of current playback.
- (NSInteger)bitrateIndex;

supportedBitrates

Return the list of supported bitrates (resolution) when the playback address is HLS.
- (NSArray<TXBitrateItem *> *)supportedBitrates;
Return Value
NSArray<TXBitrateItem *> : Bitrate list.

setBitrateIndex:

Set the bitrate index of current playback. Tencent Cloud supports multi-bitrate HLS fragment alignment to ensure the best experience. When switching clarity seamlessly, clarity switching may require waiting for a short while.
- (void)setBitrateIndex:(NSInteger)index;
Parameter Description
Parameter Name
Type
Description
index
NSInteger
bitrate index.
index == -1 indicates enabling HLS adaptive bitrate streaming.
index > 0 indicates manually switching to the corresponding clarity bitrate. The index value can be set through the API. -Retrieve [TXVodPlayer supportedBitrates].

setRenderMode:

Set the player's image tiling mode.
- (void)setRenderMode:(TX_Enum_Type_RenderMode)renderMode;
Parameter Description
Parameter Name
Type
Description
renderMode
Image Tiling Mode, valid values:
RENDER_MODE_FILL_SCREEN: The video fills the entire screen with the image proportionally scaled to cover the whole screen, cropping any excess parts. In this mode, there is no black border around the image.
RENDER_MODE_FILL_EDGE: The video image self-adaptively scales proportionally to fit the screen, with the scaled width and height not exceeding the display area. It is displayed in the center and may leave black borders.

setRenderRotation:

Set the player's image rendering angle.
- (void)setRenderRotation:(TX_Enum_Type_HomeOrientation)rotation;
Parameter Description
Parameter Name
Type
Description
rotation
TX_Enum_Type_HomeOrientation
Image rendering angle, valid values:
HOME_ORIENTATION_RIGHT: The Home button is on the right.
HOME_ORIENTATION_DOWN: The Home button is at the bottom.
HOME_ORIENTATION_LEFT: The Home button is on the left.
HOME_ORIENTATION_UP: The Home button is at the top.

setMute:

Set whether to play with mute. Default is unmuted playback.
- (void)setMute:(BOOL)bEnable;

setAudioPlayoutVolume:

Set volume level, range: 0 - 150, default is 100.
- (void)setAudioPlayoutVolume:(int)volume;

vodDelegate

Set player event callback object.
@property(nonatomic, weak) id<TXVodPlayListener> vodDelegate;

videoProcessDelegate

Set video rendering callback object.
@property(nonatomic, weak) id<TXVideoCustomProcessDelegate> videoProcessDelegate;

attachTRTC

Bind on-demand to TRTC service.
- (void)attachTRTC:(NSObject *)trtcCloud;

detachTRTC

Unbind on-demand from TRTC service.
- (void)detachTRTC;

publishVideo

Start pushing video stream.
- (void)publishVideo;

unpublishVideo

Cancel pushing video stream.
- (void)unpublishVideo;

publishAudio

Start pushing audio stream.
- (void)publishAudio;

unpublishAudio

Cancel pushing audio stream.
- (void)unpublishAudio;

isSupportPictureInPicture

Whether Picture-In-Picture functionality is supported.
+ (BOOL)isSupportPictureInPicture;

isSupportSeamlessPictureInPicture

Whether seamless switching of Picture In Picture functionality is supported. The premium edition player SDK is required.
+ (BOOL)isSupportSeamlessPictureInPicture;

setAutoPictureInPictureEnabled:

Set whether to automatically start Picture In Picture (automatic startup control switch for Picture In Picture).
- (void)setAutoPictureInPictureEnabled:(BOOL)enabled;
Parameter Description
Parameter Name
Type
Description
enabled
BOOL
YES: Automatically enters Picture-in-Picture when going into the background.
NO: Automatic entry into Picture-in-Picture is not allowed.

enterPictureInPicture

Enter the Picture-in-Picture function (this method needs to be called after Prepared).
- (void)enterPictureInPicture;

exitPictureInPicture

Exit the Picture-in-Picture function.
- (void)exitPictureInPicture;

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

Feedback