tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Video on Demand
    Documentation
    Download PDF

    iOS

    Last updated: 2024-04-11 16:11:38
    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).

      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.
      
      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
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy