tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Video on Demand
    Documentation
    Download PDF

    Web

    Last updated: 2024-04-11 16:18:08
    Download PDF
      This document is an introduction to the parameters and API of the Web Player (TCPlayer) suitable for live and on-demand playback. It is intended for developers with a basic understanding of JavaScript.

      Parameters initialization

      Initializing the player requires two parameters: the first is the player's container ID, and the second is the feature parameter object.
      var player = TCPlayer('player-container-id', options);

      Options parameter list

      The configurable parameters for the options object are as follows:
      Name
      Type
      Default Value
      Description
      appID
      String
      No
      Mandatory when playing on-demand media files through fileID, as it corresponds to the appID of the Tencent Cloud account
      fileID
      String
      No
      Mandatory when playing on-demand media files through fileID, as it is the ID of the on-demand media file
      psign
      String
      No
      Player Signature, required when playing through fileID. For more details, see Player Signature
      licenseUrl
      String
      No
      Player License address, peek at Player License
      sources
      Array
      No
      Player playback address, format: [{ src: '//path/to/video.mp4', type: 'video/mp4' }]
      width
      String/Number
      No
      Player zone width, in pixels, set as needed. The player size can be controlled through CSS.
      height
      String/Number
      No
      Player zone height, in pixels, set as needed. The player size can be controlled through CSS.
      controls
      Boolean
      true
      Whether to show the player's control bar.
      poster
      String
      No
      Set the full address of the cover image (if the uploaded video has a generated cover image, it will be used preferentially. For details, please see Video on Demand - Manage Videos).
      autoplay
      Boolean
      false
      Whether to autoplay.
      playbackRates
      Array
      [0.5,1,1.25,1.5,2]
      Set the adjustable-speed playback options, only valid in HTML5 playback pattern.
      loop
      Boolean
      false
      Whether to loop playback.
      muted
      Boolean
      false
      Whether to mute playback.
      preload
      String
      auto
      Whether preloading is needed, with 3 attributes: "auto", "meta", and "none". Due to system restrictions on mobile devices, setting auto is ineffective.
      swf
      String
      No
      URL of the Flash player's SWF file
      posterImage
      Boolean
      true
      Whether to display the cover.
      bigPlayButton
      Boolean
      true
      Whether to display a centered play button (the browser hijacked embedded play button cannot be removed).
      language
      String
      "zh-CN"
      Setting language, the options are "zh-CN"/"en"
      languages
      Object
      No
      Setting multilingual dictionary.
      controlBar
      Object
      No
      Setting the parameter combination for control bar properties, see controlBar parameter list.
      reportable
      Boolean
      true
      Setting whether to enable data reporting.
      fakeFullscreen
      Boolean
      false
      Setting up pseudo-full screen through style control to achieve the full screen effect.
      plugins
      Object
      No
      Setting the parameter combination for plugin feature attributes, see plugins plugin parameter list.
      hlsConfig
      Object
      No
      HLS.js startup configuration, for detailed content, please see the official documentation hls.js.
      webrtcConfig
      Object
      No
      WebRTC startup configuration, see webrtcConfig parameter list.
      xp2pConfig
      Object
      No
      P2P startup configuration, see xp2pConfig parameter list. For P2P feature details, see X-P2P.
      Note:
      The parameters controls, playbackRates, loop, preload, posterImage will be ineffective when the browser hijacks playback.
      For issues with browser hijacking video playback, see FAQs Description.

      controlBar parameter list

      controlBar parameters can configure the player's control bar features, with supported properties as listed in the following table:
      Name
      Type
      Default Value
      Description
      playToggle
      Boolean
      true
      Whether to display the play/pause toggle button.
      progressControl
      Boolean
      true
      Whether to display the progress bar.
      volumePanel
      Boolean
      true
      Whether to display volume control.
      currentTimeDisplay
      Boolean
      true
      Whether to show the current time of the video.
      durationDisplay
      Boolean
      true
      Whether to display the video duration.
      timeDivider
      Boolean
      true
      Whether to display the time separator.
      playbackRateMenuButton
      Boolean
      true
      Whether to display the playback speed selection button.
      fullscreenToggle
      Boolean
      true
      Whether to display the full-screen button.
      QualitySwitcherMenuButton
      Boolean
      true
      Whether to display the definition switch menu.
      Please Note:
      The controlBar parameter will be ineffective when the browser hijacks playback.
      For issues with browser hijacking video playback, see FAQs Description.

      plugins plugin parameter list

      plugins parameters can configure the player's plugin features, supported properties include:
      Name
      Type
      Default Value
      Description
      ContinuePlay
      Object
      No
      Controlling the resume playback feature, supported properties are as follows:
      auto:Boolean Whether it automatically resumes playback.
      text:String Prompt text.
      btnText:String Button text.
      VttThumbnail
      Object
      No
      Controlling thumbnail display, supported properties are as follows:
      vttUrl:String Absolute address of vtt file, required.
      basePath:String Image path, optional. If not provided, the path of vttUrl will be used.
      imgUrl:String Absolute image address, optional.
      ProgressMarker
      Boolean
      No
      Controlling the display of the progress bar.
      DynamicWatermark
      Object
      No
      Controlling the display of dynamic watermarks, supporting text and images. The supported properties are:
      type:String Watermark type can be text or image, with values text | image, default text, optional.
      content:String Text watermark content, required.
      speed:Number Watermark movement speed, value range 0-1, default value 0.2, optional.
      opacity:Number Text watermark opacity, value range 0-1, optional.
      fontSize:String Font size, default 12px, optional.
      color: String Text color, optional.
      left:String Text position, supports percentage and px units. When setting this field, the speed field is ineffective, optional.
      top,right,bottom: Description same as left.
      width:String Image watermark width, optional.
      height:String Image watermark height, optional.
      ContextMenu
      Object
      No
      Valid values are as follows:
      mirror:Boolean Controls whether mirroring display is supported.
      statistic:Boolean Controls whether displaying the data panel is supported.
      levelSwitch:Object Controls the prompt text when switching definition.
       {
        open: Boolean Whether to enable notifications
        switchingText: String, Prompt text when starting to switch definition
        switchedText: String, Prompt text when the switch is successful
        switchErrorText: String, Prompt text when the switch fails
       }
      PlayList
      Object
      No
      Setting the playlist, supported properties are as follows:
      {
          // Collection of video information to be played
          data: [{
            fileID: String,
            appID: String,
            duration: Number, // Video duration 
            text: String, // Video name
            psign: String, // Player signature
            img: String, // Cover image
          }],
          title: String, // List title
          loop: Boolean, // Whether to loop playback
      }
      
      VR
      Object
      No
      Advanced Edition License support, for details see Web advanced feature - VR Playback Plugin (TCPlayerVRPlugin)
      SafeCheck
      Object
      No
      Advanced Edition License support, for details see Web advanced feature - Security Check Plugin (TCPlayerSafeCheckPlugin)

      webrtcConfig parameter list

      webrtcConfig parameters control the behavior during WebRTC playback, with the following attributes supported:
      Name
      Type
      Default Value
      Description
      connectRetryCount
      Number
      3
      Number of reconnections between the SDK and the server
      connectRetryDelay
      Number
      1
      Delay in reconnection between SDK and server
      receiveVideo
      Boolean
      true
      Whether to fetch video stream
      receiveAudio
      Boolean
      true
      Whether to fetch audio stream
      showLog
      Boolean
      false
      Should logs be printed in the console

      xp2pConfig parameter list

      Before using X-P2P, you need to apply for activation. Please go to X-P2P and click to apply. After applying, our dedicated product support staff will contact you.
      For more detailed information, please refer to the X-P2P Product Documentation.
      Common Parameters
      Name
      Type
      Default Value
      Description
      useXP2P
      Boolean
      false
      Whether to enable XP2P
      format
      String
      No
      Specify the media protocols that P2P needs to support based on the current video format. The valid values are as follows:
      flv
      hls
      webrtc
      tencentCloudAppId
      Number
      No
      In your Tencent Cloud account's APPID (Console peek path: Account Center > Account Information > Basic Information > APPID)
      xp2pAppId
      String
      No
      X-P2P assigned ID, provided by our email
      xp2pAppKey
      String
      No
      X-P2P assigned Key, provided by our email
      xp2pPackage
      String
      No
      X-P2P assigned Package, provided by our email
      Additional parameters for the flv protocol
      Name
      Type
      Default Value
      Description
      bizId
      String
      No
      Provided by our email
      xp2pPlayDomain
      String
      No
      FLV protocol streaming domain name, provided by our email
      authMode
      String
      No
      Authentication pattern, provided by our email
      debug
      Boolean
      false
      Debug switch
      Additional parameters for the HLS protocol
      Name
      Type
      Default Value
      Description
      videoType
      String
      VOD
      Please specify whether the current HLS playback is live or on-demand accurately. The valid values are as follows:
      LIVE
      VOD
      channelId
      String
      Automatically generated
      You can proactively generate an ID for the current resource. If not specified, it defaults to internal automatic generation. See the generation rules as follows HLS Resource ID Generation Rules
      channelIdWithHost
      Boolean
      true
      Defaults to true, with an optional configuration, usually no need to modify this configuration. For a detailed explanation, see the following HLS Resource ID Generation Rules
      channelIdWithSearch
      Boolean
      false
      Defaults to false, with an optional configuration, usually no need to modify this configuration. For a detailed explanation, see the following HLS Resource ID Generation Rules
      
      HLS Resource ID Generation Rules
      
      The Resource ID is the unit of P2P sharing; only nodes with the same Resource ID can share with each other via P2P. Different videos must ensure different Resource IDs, otherwise, streams will be crossed.
      1.1 Proactively Input
      By using the Setting parameter channelId field, you can proactively assign a Resource ID for the current video, ensuring it uniquely identifies the file to avoid stream crossing.
      1.2 Default Generation
      If the channelId field is not input, the sdk will by default generate an ID for each url; IDs that are the same will share with each other via P2P. The ID generation rule is as follows:
      (Default) Intercept the host and path parts to generate an MD5 checksum.
      For example: https://a.b.com/p1/p2/p3.m3u8?m=1&n=2, then the ID = MD5('a.b.com/p1/p2/p3.m3u8')
      1.3 Input parameters control the default generation rule
      (Optional, default is true) By entering the channelIdWithHost parameter, true indicates that the ID includes the host part.
      (Optional, default is false) By entering the channelIdWithSearch parameter, false indicates it includes the search part.
      For example: https://a.b.com/p1/p2/p3.m3u8?m=1&n=2
      If { channelIdWithHost: true, channelIdWithSearch: true } is passed, then the ID = MD5('a.b.com/p1/p2/p3.m3u8?m=1&n=2')
      If { channelIdWithHost: false, channelIdWithSearch: false } is passed, then the ID = MD5('/p1/p2/p3.m3u8')
      Note:
      You can generate different Resource IDs for video URLs that cannot share P2P, and the same Resource ID for URLs that can, based on your own business URL generation rules.
      1.4 Multi-bitrate M3U8 Explanation
      If the video being played is multi-bitrate M3U8, we ensure that nodes of different bitrates do not P2P with each other.
      X-P2P Protocol Support
      Audio/Video Protocol
      Use
      PC Browser
      Android
      iOS
      FLV
      Live stream
      Supported
      chrome 55+
      firefox 65+
      safari 11+
      Supported
      chrome 55+
      firefox 65+
      Weixin browser
      Not supported
      HLS
      Live streaming, video on demand
      Supported
      chrome 55+
      firefox 65+
      safari 11+
      Supported
      chrome 55+
      firefox 65+
      Weixin browser
      Not supported
      WebRTC
      Live stream
      Partially supported
      Chrome 94+
      edge 94+
      Partially supported
      Chrome 94+
      edge 94+
      Not supported

      Object methods

      Methods list returned by initialize player object:
      Name
      Parameters and Types
      Return Value and Types
      Description
      src()
      (String)
      No
      Setting the playback address.
      loadVideoByID()
      (Object)
      No
      When playing with fileID, you can switch videos using this method. The parameter is an object consisting of fileID, appID, psign.
      ready(function)
      (Function)
      No
      Setting the callback after player initialization is complete.
      play()
      No
      No
      Play and resume playback.
      pause()
      No
      No
      Pauses playback.
      currentTime(seconds)
      (Number)
      (Number)
      Access the current playback time, or set the playback time, which cannot exceed the video duration.
      duration()
      No
      (Number)
      Access video duration.
      volume(percent)
      (Number)[0,1][Optional]
      (Number)/ No return when setting
      Access or set the player volume.
      muted()
      (Boolean)
      (Boolean)
      Access or set whether the player is muted
      playbackRate()
      (Number)[0, 1]
      (Number)
      Access or set the playback speed
      poster(src)
      (String)
      (String)/ No return when setting
      Access or set the player thumbnail.
      requestFullscreen()
      No
      No
      Enter full screen mode pattern.
      exitFullscreen()
      No
      No
      Exit full screen mode pattern.
      isFullscreen()
      No
      Boolean
      Return whether full screen mode pattern has been entered.
      on(type,listener)
      (String, Function)
      No
      Listening to events.
      one(type,listener)
      (String, Function)
      No
      Listening to events, the event handler executes no more than once.
      off(type,listener)
      (String, Function)
      No
      Unbind event listener.
      buffered()
      No
      TimeRanges
      Returns the video buffer range.
      bufferedPercent()
      No
      Value range [0,1]
      Returns the buffer length as a percentage of video duration.
      width()
      (Number)[Optional]
      (Number)/ No return when setting
      Access or set the player zone width. If the player size is set via CSS, this method will be ineffective.
      height()
      (Number)[Optional]
      (Number)/ No return when setting
      Access or set the player zone height. If the player size is set via CSS, this method will be ineffective.
      videoWidth()
      No
      (Number)
      Access video resolution width.
      videoHeight()
      No
      (Number)
      Access video resolution height.
      dispose()
      No
      No
      Terminate the player.
      Note
      Object methods cannot be called synchronously; they need to be called after the corresponding event (such as loadedmetadata) is triggered, except for ready, on, one, and off.

      Event

      The player can perform event listening through the objects returned by the initialization, for example:
      var player = TCPlayer('player-container-id', options);
      // player.on(type, function);
      player.on('error', function(error) {
         // Do some processing
      });
      Among them, type is the event type, supported events include:
      Name
      Features
      play
      Playback has started, triggered by calling the play() method or setting autoplay to true and it takes effect, with the paused attribute being false.
      playing
      Triggered when playback resumes after being paused or stopped for buffering, with the paused attribute being false. This event is commonly used to mark the real start of video playback, as the play event only indicates the initiation of playback without actual video rendering.
      loadstart
      Triggered when starting to load data.
      durationchange
      Triggered when the video's duration data changes.
      loadedmetadata
      The video's metadata has been loaded.
      loadeddata
      This event is triggered when the data for the current frame is loaded, but there is not enough data to play the next frame of the video.
      progress
      Triggered when accessing media data.
      canplay
      Triggered when the player is able to start playing the video.
      canplaythrough
      Triggered when the player estimates it can play through the specified video without stopping for buffering.
      error
      Triggered when an error occurs during video playback.
      pause
      Triggered when paused.
      blocked
      Triggered when autoplay is blocked by the browser.
      ratechange
      Triggered when the playback speed changes.
      seeked
      Triggered when the search for a specified playback position ends.
      seeking
      Triggered when the search for a specified playback position begins.
      timeupdate
      Triggered when there is a change in the current playback position, which can be understood as a change in currentTime.
      volumechange
      Triggered when the volume setting or muted property value changes.
      waiting
      Triggered when playback stops, and the next frame of content is unavailable.
      ended
      Triggered when video playback has ended. At this point, the value of currentTime is equal to the maximum value of the media resource.
      resolutionswitching
      Definition switch in progress.
      resolutionswitched
      Definition switch completed.
      fullscreenchange
      Triggered during full screen status toggle.
      webrtcevent
      Event set during webrtc playback.
      webrtcstats
      Statistics during webrtc playback.
      webrtcfallback
      Triggered degradation during webrtc playback

      WebrtcEvent list

      The player can access all events during webrtc playback through webrtcevent, for example:
      var player = TCPlayer('player-container-id', options);
      player.on('webrtcevent', function(event) {
         // Access event status code and related data from the callback parameter event
      });
      webrtcevent status codes are as follows
      Status Code
      Callback parameters
      Features
      1001
      No
      Start pulling stream
      1002
      No
      Connected to server
      1003
      No
      Video playback starts
      1004
      No
      Stop pulling stream, end video playback
      1005
      No
      Failed to connect to server. Auto-reconnect initiated to recover
      1006
      No
      Access stream data is empty
      1007
      localSdp
      Starting signaling server request
      1008
      remoteSdp
      Signaling server request succeeded
      1009
      No
      Streaming lagging, buffering in progress
      1010
      No
      Streaming lag ended, playback resumed

      Error code

      When the player triggers an error event, the listener function returns an error code, with those having three or more digits being media data interface error codes. Error code list:
      Name
      Description
      -1
      The player did not detect an available video address.
      -2
      Access to video data timed out.
      1
      Video data loading was interrupted.
      Possible reasons:
      Network interrupted.
      Browser abnormal interruption.
      Solution:
      Peek at the network request information in the web console to confirm if network requests are normal.
      Restart the playback process.
      2
      Video loading failed due to network issues.
      Possible cause: Network interrupts.
      Solution:
      Peek at the network request information in the web console to confirm if network requests are normal.
      Restart the playback process.
      3
      An error occurred during video decoding.
      Possible cause: Abnormal video data, decoder failed to decode.
      Solution:
      Try re-transcoding and then play it again to eliminate issues introduced by the transcoding process.
      Confirm whether the original video is normal.
      Please contact technical support and provide play parameters for troubleshooting.
      4
      The video cannot be loaded due to unsupported format or server/network issues.
      Possible reasons:
      Cannot access video data, CDN resource does not exist or does not return video data.
      The current playback environment does not support this video format.
      Solution:
      Peek at the network request information in the browser console to confirm if the video data request is normal.
      Confirm whether the playback script for the corresponding video format has been loaded as per the documentation.
      Confirm whether the current browser and page environment support the video format to be played.
      Please contact technical support and provide play parameters for troubleshooting.
      5
      An error occurred during video decryption.
      Possible reasons:
      The decryption key is incorrect.
      The request for the key API returned an exception.
      The current playback environment does not support the video decryption feature.
      Solution:
      Confirm whether the key is correct and whether the key API returns normally.
      Please contact technical support and provide play parameters for troubleshooting.
      10
      The VOD media data interface request timed out. When accessing media data, if the player retries 3 times without any response, this error will be thrown.
      Possible reasons:
      The current network environment cannot connect to the media data interface, or the media data interface has been hijacked.
      Media data interface error.
      Solution:
      Try opening the demo page we provided to see if it can play normally.
      Please contact technical support and provide play parameters for troubleshooting.
      11
      The VOD media data interface did not return any data. When accessing media data, if the player retries 3 times without any data returned, this error will be thrown.
      Possible reasons:
      The current network environment cannot connect to the media data interface, or the media data interface has been hijacked.
      Media data interface error.
      Solution:
      Try opening the demo page we provided to see if it can play normally.
      Please contact technical support and provide play parameters for troubleshooting.
      12
      The VOD media data interface returns abnormal data. When accessing media data, if the player retries 3 times and still returns data that cannot be parsed, this error will be thrown.
      Possible reasons:
      The current network environment cannot connect to the media data interface, or the media data interface has been hijacked.
      The play parameters are incorrect; the media data interface cannot process them.
      Media data interface error.
      Solution:
      Try opening the demo page we provided to see if it can play normally.
      Please contact technical support and provide play parameters for troubleshooting.
      13
      The player did not detect video data that can be played on the current player; please transcode this video.
      14
      Playing HLS under the HTML5 + hls.js pattern encounters a network error. Details can be peeked at in event.source. For a detailed introduction, please see the official hls.js documentation Network Errors.
      15
      Playing HLS under the HTML5 + hls.js pattern encounters a Multimedia error. Details can be peeked at in event.source. For a detailed introduction, please see the official hls.js documentation Media Errors.
      16
      Playing HLS under the HTML5 + hls.js pattern encounters a multiplexing exception. Details can be peeked at in event.source. For a detailed introduction, please see the official hls.js documentation Mux Errors.
      17
      Playing HLS under the HTML5 + hls.js pattern encounters other exceptions. Details can be peeked at in event.source. For a detailed introduction, please see the official hls.js documentation Other Errors.
      1013
      Player Signature is missing the contentInfo field
      10008
      The media data service did not find media data corresponding to the play parameters, please confirm that the appID and fileID request parameters are correct, and that the corresponding media data has not been deleted.
      -2002
      Live Event Broadcasting pull stream interface returns an error in the backend (for example, the stream does not exist, authentication failure, etc.)
      -2006
      Live Event Broadcasting multi-resolution smooth switching interface request failed
      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