tencent cloud

Feedback

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
    setConfig Sets the player configuration information. For more information on the configuration, see TXVodPlayConfig.
    setPlayerView Sets the player's rendering view TXCloudVideoView.
    setPlayerView Sets the player's rendering view TextureView.
    setSurface Sets the player's rendering view SurfaceView.
    setStringOption Sets the player business parameters in the format of <string,object>.

    Basic playback APIs

    API Description
    startPlay Starts playing back the video at the specified HTTP URL.
    startPlay Starts playing back the video of the specified fileId by passing in the TXPlayInfoParams parameter.
    startPlayDrm Plays back a DRM-encrypted video.
    stopPlay Stops playback.
    isPlaying Gets whether playback is ongoing.
    pause Pauses playback by stopping the retrieval of stream data and retaining the last-frame image.
    resume Resumes playback by getting the stream data again.
    seek Seeks to a specified time point of the video stream (in seconds).
    seek Seeks to a specified time point of the video stream (in ms).
    getCurrentPlaybackTime Gets the current playback time point in seconds.
    getBufferDuration Gets the total buffer duration in seconds.
    getDuration Gets the total video duration in seconds.
    getPlayableDuration Gets the playable video duration in seconds.
    getWidth Gets the video width.
    getHeight Gets the video height.
    setAutoPlay Sets whether to start VOD automatically after call of startPlay. VOD starts automatically by default.
    setStartTime Sets the playback start time.
    setToken Sets the token for HLS encryption.
    getEncryptedPlayKey Gets the encrypted playback key.
    setLoop Sets whether to loop the video.
    isLoop Returns the loop playback status.

    Video APIs

    API Description
    enableHardwareDecode Enables/Disables video hardware decoding.
    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 horizontally.
    setRate Sets the VOD playback speed. Default value: 1.0.
    getBitrateIndex Returns the current playback bitrate index.
    getSupportedBitrates Returns the supported bitrates (definitions) if the playback address is HLS.
    setBitrateIndex Sets the current playback bitrate index for seamless definition switch. You may need to wait momentarily to switch the definition.
    setRenderMode Sets the image fill mode.
    setRenderRotation Sets the image rendering angle.

    Audio APIs

    API Description
    setMute Sets whether to mute the player.
    setAudioPlayoutVolume Sets the volume level. Value range: 0–100.
    setRequestAudioFocus Sets whether to get the audio focus automatically. The audio focus is gotten automatically by default.

    Event notification APIs

    API Description
    setPlayListener Sets the player callback (this API has been deprecated, and we recommend you use setVodListener).
    setVodListener Sets the player callback.

    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
    attachTRTC Binds VOD to TRTC.
    detachTRTC Unbinds VOD from TRTC.
    publishVideo Starts pushing the video stream.
    unpublishVideo Cancels pushing the video stream.
    publishAudio Starts pushing the audio stream.
    unpublishAudio Cancels pushing the audio stream.

    ITXVodPlayListener

    VOD callback notifications.

    Basic SDK callback APIs

    API Description
    onPlayEvent VOD playback event notification. For more information, see the playback event list and event parameters.
    onNetStatus VOD player network status notification.

    TXVodPlayConfig

    VOD player configuration class.

    Basic configuration APIs

    API Description
    setConnectRetryCount Sets the maximum number of player reconnection attempts.
    setConnectRetryInterval Sets the player reconnection interval in seconds.
    setTimeout Sets the player connection timeout period in seconds.
    setCacheFolderPath Sets the VOD cache directory, which takes effect for MP4 and HLS files.
    This API has been deprecated and is not recommended.
    setMaxCacheItems Sets the maximum number of cached files.
    This API has been deprecated and is not recommended.
    setPlayerType Sets the player type.
    This API has been deprecated and is not recommended.
    setHeaders Sets custom HTTP headers.
    setEnableAccurateSeek Sets whether to enable accurate seek. Default value: true.
    setAutoRotate 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
    setSmoothSwitchBitrate Sets whether to enable smooth switching for multi-bitrate HLS streams. Default value: false.
    setCacheMp4ExtName Sets the cached MP4 file extension.
    setProgressInterval Sets the progress callback interval in ms.
    setMaxBufferSize Sets the maximum preloading buffer size in MB.
    setMaxPreloadSize Sets the maximum preloading buffer size in MB.
    setExtInfo Sets the extended information.
    setPreferredResolution 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.
    setOverlayKey Sets the HLS security hardening encryption and decryption key.
    setOverlayIv Sets the HLS security hardening encryption and decryption IV.
    setEnableRenderProcess Sets whether to allow postrendering and postproduction features.
    setMediaType Sets the media asset type, which is auto by default.

    TXPlayerGlobalSetting

    Global configuration of the VOD player.

    API Description
    setCacheFolderPath Sets the cache directory of the playback engine. After setting, this directory will be first read and written during downloading, predownloading, and player use.
    setMaxCacheSize 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
    getInstance Gets the TXVodPreloadManager instance object in singleton mode.
    startPreload Sets the playback engine cache directory before starting predownloading.
    stopPreload Stops predownloading.

    ITXVodPreloadListener

    The callback for video predownloading.

    API Description
    onComplete Video predownloading is completed.
    onError An error occurred during video predownload.

    TXVodDownloadManager

    Video download API class of the VOD player. Currently, only non-nested M3U8 videos can be downloaded. SimpleAES-encrypted videos will be encrypted again with Tencent Cloud's private encryption algorithm to improve the security.

    API Description
    getInstance Gets the TXVodDownloadManager instance object in singleton mode.
    setHeaders Sets download HTTP headers.
    setListener Sets the download callback method, which must be set before download.
    startDownloadUrl Starts downloading the video at the specified URL.
    startDownload Starts downloading the video of the specified fileid.
    stopDownload Stops the download. If ITXVodDownloadListener.onDownloadStop is called back, the download stops successfully.
    deleteDownloadMediaInfo Deletes the download information.
    getDownloadMediaInfoList Gets the download lists of all users.
    getDownloadMediaInfo Gets the download information.
    getDownloadMediaInfo Gets the download information.

    ITXVodDownloadListener

    VOD download notifications.

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

    TXVodDownloadDataSource

    Tencent Cloud video fileid download source, which can be passed in as a parameter during download.

    API Description
    TXVodDownloadDataSource Builds a function to pass in parameters such as appid, fileid, quality, psign, and username.
    getAppId Gets the appid that is passed in.
    getFileId Gets the fileid that is passed in.
    getPSign Gets the psign that is passed in.
    getQuality Gets the quality that is passed in.
    getUserName Gets the userName that is passed in, which is default by default.
    getToken Gets the token that is passed in.
    getOverlayKey Gets the overlayKey that is passed in.
    getOverlayIv Gets the overlayIv that is passed in.

    Definition ID constants

    Code Constant Definition Description
    0 QUALITY_OD Original
    1 QUALITY_FLU LD
    2 QUALITY_SD SD
    3 QUALITY_HD HD
    4 QUALITY_FHD FHD
    5 QUALITY_2K 2K
    6 QUALITY_4K 4K
    1000 QUALITY_UNK Undefined

    TXVodDownloadMediaInfo

    Class to get VOD download information such as download progress and playback link.

    API Description
    getDataSource Gets the download source specified by the fileid passed in for video download by fileid.
    getDuration Gets the total duration of the downloaded video.
    getPlayableDuration Gets the playable duration of the downloaded video.
    getSize Gets the total size of the file being downloaded. This API takes effect only for download by fileid.
    getDownloadSize Gets the size of the downloaded file. This API takes effect only for download by fileid.
    getProgress Gets the current download progress.
    getPlayPath Gets the current playback path, which can be passed in to TXVodPlayer for playback.
    getDownloadState Gets the download status.
    isDownloadFinished Determines whether the download is completed.

    Static attributes

    Code Attribute Definition Description
    0 STATE_INIT Download was initialized.
    1 STATE_START Download started.
    2 STATE_STOP Download stopped.
    3 STATE_ERROR An error occurred during download.
    4 STATE_FINISH Download was completed.

    TXPlayerAuthBuilder

    The configuration for encrypted video playback through fileId.

    API Description
    setAppId The application's appId.
    setFileId The file ID.
    setTimeout The encrypted link timeout timestamp.
    setExper The preview duration.
    setUs The unique request ID.
    setSign The hotlink protection signature.
    setHttps Whether to use HTTPS requests.

    TXBitrateItem

    The video bitrate information.

    API Description
    index The number of the stream 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.
    compareTo Whether the bitrates of two streams are the same.

    TXImageSprite

    The image sprite parsing class.

    API Description
    TXImageSprite Constructor.
    setVTTUrlAndImageUrls Sets the image sprite URL.
    getThumbnail Gets a thumbnail.
    release This API must be called after use; otherwise, memory leaks will occur.

    TXPlayerDrmBuilder

    The DRM playback information.

    API Description
    TXPlayerDrmBuilder Constructs a DRM playback information object.
    setProvisionUrl Sets the URL of the certificate provider.
    setKeyLicenseUrl Sets the URL of the decryption key.
    setPlayUrl Sets the URL of the media file to be played back.

    TXPlayInfoParams

    Parameters for video playback through fileId.

    API Description
    TXPlayInfoParams Constructor.
    getAppId Gets the application's appId.
    getFileId Gets the file ID.
    getPSign Gets the encryption signature of a video.

    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

    The following constants are made available through TXVodConstants starting from v10.0:

    Image fill mode

    Code Event Definition Description
    0 RENDER_MODE_FULL_FILL_SCREEN The video image is scaled proportionally to fill the entire screen.
    1 RENDER_MODE_ADJUST_RESOLUTION The video image is scaled proportionally to fit the screen.

    Image rendering angle

    Code Event Definition Description
    0 RENDER_ROTATION_PORTRAIT Normal portrait mode.
    270 RENDER_ROTATION_LANDSCAPE Landscape mode (90-degree clockwise rotation).

    Playback event list

    Code Event Definition Description
    2003 VOD_PLAY_EVT_RCV_FIRST_I_FRAME The network received the first renderable video data packet (IDR).
    2004 VOD_PLAY_EVT_PLAY_BEGIN Video playback started.
    2005 VOD_PLAY_EVT_PLAY_PROGRESS The video playback progress was changed.
    2006 VOD_PLAY_EVT_PLAY_END Video playback ended.
    2007 VOD_PLAY_EVT_PLAY_LOADING The video is loading.
    2008 VOD_PLAY_EVT_START_VIDEO_DECODER The decoder started.
    2009 VOD_PLAY_EVT_CHANGE_RESOLUTION The video resolution changed.
    2010 VOD_PLAY_EVT_GET_PLAYINFO_SUCC Obtained the VOD file information successfully.
    2011 VOD_PLAY_EVT_CHANGE_ROTATION The video is rotated.
    2013 VOD_PLAY_EVT_VOD_PLAY_PREPARED The video is loaded.
    2014 VOD_PLAY_EVT_VOD_LOADING_END Loading ended.
    2026 VOD_PLAY_EVT_RCV_FIRST_AUDIO_FRAME The audio is played back for the first time.
    2103 VOD_PLAY_WARNING_RECONNECT Network disconnected. Automatic reconnection has been enabled.
    -2301 VOD_PLAY_ERR_NET_DISCONNECT The network was disconnected and could not be reconnected after multiple retries.
    -2303 VOD_PLAY_ERR_FILE_NOT_FOUND The file does not exist.
    -2304 VOD_PLAY_ERR_HEVC_DECODE_FAIL Failed to decode with H.265.
    -2305 VOD_PLAY_ERR_HLS_KEY Failed to get the HLS decryption key.
    -2306 VOD_PLAY_ERR_GET_PLAYINFO_FAIL Failed to get the VOD file information.
    2106 VOD_PLAY_WARNING_HW_ACCELERATION_FAIL Failed to start the hardware decoder, and the software decoder was used instead.
    -5 VOD_PLAY_ERR_INVALID_LICENSE The license was invalid, and playback failed.

    Playback event parameters

    Event Definition Description
    EVT_UTC_TIME The UTC time
    EVT_TIME The event occurrence time
    EVT_DESCRIPTION The event description
    EVT_PARAM1 Event parameter 1
    EVT_PARAM2 Event parameter 2
    EVT_PLAY_COVER_URL The video thumbnail
    EVT_PLAY_URL The video URL
    EVT_PLAY_NAME The video name
    EVT_PLAY_DESCRIPTION The video description
    EVT_PLAY_PROGRESS_MS The playback progress in milliseconds
    EVT_PLAY_DURATION_MS The total playback duration in milliseconds
    EVT_PLAY_PROGRESS The playback progress
    EVT_PLAY_DURATION The total playback duration
    EVT_PLAYABLE_DURATION_MS The playable duration of the VOD file in milliseconds
    EVT_PLAYABLE_RATE The playback speed
    EVT_PLAYABLE_DURATION The playable duration of the VOD file
    EVT_IMAGESPRIT_WEBVTTURL The download URL of the image sprite WebVTT file
    EVT_IMAGESPRIT_IMAGEURL_LIST The download URL of the image sprite
    EVT_DRM_TYPE The encryption type
    EVT_CODEC_TYPE The video codec type
    EVT_KEY_FRAME_CONTENT_LIST The video keyframe description
    EVT_KEY_FRAME_TIME_LIST The keyframe time

    Playback network status notification parameters

    Event Definition Description
    NET_STATUS_CPU_USAGE The CPU utilization
    NET_STATUS_VIDEO_WIDTH The resolution's width
    NET_STATUS_VIDEO_HEIGHT The resolution's height
    NET_STATUS_VIDEO_FPS The current video frame rate
    NET_STATUS_VIDEO_GOP The current video GOP
    NET_STATUS_VIDEO_BITRATE The bitrate of the video data
    NET_STATUS_AUDIO_BITRATE The bitrate of the audio data
    NET_STATUS_NET_SPEED The network speed
    NET_STATUS_AUDIO_CACHE The number of audio frames
    NET_STATUS_VIDEO_CACHE The number of video frames
    NET_STATUS_AUDIO_INFO The audio information of the current stream
    NET_STATUS_NET_JITTER The network jitter status
    NET_STATUS_SERVER_IP The connected server IP
    NET_STATUS_VIDEO_DPS The current frame rate of the video output by the decoder
    NET_STATUS_QUALITY_LEVEL The network quality

    Player asset types

    Code Event Definition Description
    0 MEDIA_TYPE_AUTO The auto type
    1 MEDIA_TYPE_HLS_VOD The HLS VOD media asset for adaptive bitrate streaming
    2 MEDIA_TYPE_HLS_LIVE The HLS live stream media asset for adaptive bitrate streaming

    Uncategorized variables

    Code Event Definition Description
    -1 INDEX_AUTO The index for adaptive bitrate
    </string,object>
    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 avaliable.

    7x24 Phone Support