tencent cloud



Last updated: 2022-03-21 12:45:42

    Feature Description

    This document describes how to use the Web Player (Web SDK) of Tencent Cloud VOD service, which allows users to directly use the proven video playback capability. Through flexible APIs, the SDK can be easily integrated with self-built Web Apps to achieve the playing with desktop Apps. At the same time, the Web SDK provides the capability of uploading videos at Web end.

    The file formats supported by the SDK are limited by the global hotlink protection feature. For more information, please see FAQs on the official website. This document is intended for developers who want to use Tencent Cloud VOD player Web SDK for development and have basics knowledge in JavaScript.

    Supported Features

    Playback Format

    The following table lists the video formats supported by Web SDK:

    Playback Format PC Browser Mobile Browser
    HLS (m3u8) Yes Yes
    MP4 Yes Yes
    FLV No No

    Android system compatibility: Unlike iPhones that only use a Safari browser, a wide range of native browsers may come with Android phones. For this reason, compatibility of Android browsers has become a problem that plagues the industry. Therefore, the above table does not apply to all Android phones.

    Upload format

    Video formats supported by the SDK for upload are as follows:

    Standard Detailed Format
    Microsoft WMV, WM, ASF, ASX
    Others MOV, 3GP, MP4, MP4V, M4V, MKV, AVI, FLV, F4V

    Transcode service of the VOD platform: Since MP4 and HLS (m3u8) formats are relatively widely supported for both PC and mobile browsers, Tencent Cloud VOD platform always publishes the uploaded videos in these formats.

    Platform compatibility

    It requires excessive effort to create two sets of codes for smartphone browser and PC browser. However, by using this player, the same code will adapt itself to PC browser/smartphone browser, which means the player will automatically choose the optimal playback method according to the platform it runs on. For example: On PC, the service will use Flash player as first priority in order to cope with various video formats. On smartphone, the service will use HTML5 technology to play videos instead.


    Step 1: Activate the service

    Sign up for a Tencent Cloud account at Tencent Cloud official website, and activate the VOD service.

    Step 2: Upload files

    After the VOD service is activated, go to VOD Video Management to upload new video files. Since the document is meant to introduce how to use the player, this operation can help you obtain your own online video address. You are unable to enter this page if you haven't activated VOD service.

    Step 3: Obtain an ID

    After the video is uploaded, you can find the file ID (the most basic information for the player to play videos) in the Video Management page. The player also includes Quality Statistics feature. You need to verify your APPID which can be queried in the Video Management page before using the player. In the figure below, the ID on the left is the video file ID, while the other one is your APPID.

    Step 4: Prepare pages

    Introduce the initialization script to the page in which you want to play videos (including PC or H5):

    <script src="//qzonestyle.gtimg.cn/open/qcloud/video/h5/h5connect.js" charset="utf-8"></script>;

    Local file restriction: You cannot play local files using the player due to cross-domain issues. You must access the player through an IP or domain--this is why we asked you to upload a video file first and acquire its online playback address.

    Adding Player

    You can add a video player into your page by following the two simple steps below.

    Step 1: Add a player container

    Place a player container in the page where you want to display the player. For example, add the following code into index.html. The container ID, width and height can be customized.

    <div id="id_video_container" style="width:100%; height:auto;"></div>;

    Step 2: Create a Player object

    Next, create a player object in the introduced JavaScript using a player constructor.

    var player = new qcVideo.Player("id_video_container", {
       "file_id": "1465197896261041838",
       "app_id": "125132611",

    The constructor is used to generate a player object and find the corresponding video to play based on file_id and app_id. You can control the player with the player object. For more information, please see Overview of API Methods for the parameter options of player object.

    Complete sample code

    <!DOCTYPE html>
       <meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1" />
       <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
       <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=0, minimum-scale=1.0, maximum-scale=1.0"/>
    <div id="id_video_container" style="width:100%; height:auto;"></div>
    <script src="//qzonestyle.gtimg.cn/open/qcloud/video/h5/h5connect.js" charset="utf-8"></script>
    <script type="text/javascript">
       (function () {
           var player = new qcVideo.Player("id_video_container", {
               "file_id": "1465197896261041838",
               "app_id": "125132611",

    Other Cases

    case 1: How do I play a video if I have the video address but not the file_id and app_id?

    Video playback address need to be passed, in which case file_id and app_id are not required. JS example:

       var option = {
       "width": 640,
       "height": 480,
       //...You may use other custom attributes
       "third_video": {
               20 : "http://208.vod.myqcloud.com/204.mp4"//This is only an example. Please replace this with actual video address
    var player = new qcVideo.Player("id_video_container", option);

    The "urls" attribute of the "third_video" parameter is an Object, where you can pass multiple video addresses with different video definitions. Detailed parameter descriptions can be found in Overview of API Methods.

    "urls" should include at least one video address

    case 2: How to use "On-screen Comment"?

    After the initialization of player, you can add on-screen comments for videos by calling the addBarrage(barrage) method of player object. For more information on parameters, please see Overview of API Methods. For example, add two on-screen comments for the video that is being played:

    var barrage = [
    {"type":"content", "content":"hello world", "time":"1"},
    {"type":"content", "content":"Center", "time":"1", "style":"C64B03;30","position":"center"}

    On-screen comment is only implemented at the frontend. Backend support should be self-developed. This feature only applies to Flash players on PC, but not supported in H5.

    Case 3: How do I perform some operations at the end of the video, such as video recommendation?

    Use the listener parameter and pass a callback function for the playStatus event. This function will be called when the playback status changes. For description on the specific callback function parameters, please see API Overview.

    For example:

    var option ={
      //...You may use other custom attributes
    var listener = {
      playStatus: function (status){
    var player = new qcVideo.Player("id_video_container", option, listener);

    Case 4: How to make the player remember video playback progress and start playing the video from the same point the next time?

    In "option", set the parameter "remember" to 1. The player records the time point when the video was stopped in the previous playback, and continues from this point upon the next playback. For example:

    var option ={
       //...You may use other custom attributes
    var player = new qcVideo.Player("id_video_container", option);

    Case 5: How to make the player adjust its size automatically along with the web page?

    Use the player object method "resize(width, height)" to modify player size dynamically.

    player.resize(640, 480);

    Case 6: How to play videos that have been configured with passwords from Cloud Video Management?

    Just like playing normal videos, SDK automatically displays a password input window. Playback starts after the password is entered.

    Password feature is only available when playing videos by passing video IDs.

    Example (please replace the appid and fileid in the link with actual IDs):


    Case 8: How to specify video playback definition?

    Use the "definition" parameter to specify the definition with which the video is played (on condition that the definition is available for this video). This is available for two playback methods: play with video ID and play with address. See Parameter Description link for more information. For example:

    var option ={
    var player = new qcVideo.Player("id_video_container", option);

    Overview of API Methods


    qcVideo.Player(id, option, listener);

    ID: String; Required; This parameter indicates the ID of the container where the player is located in the page and can be customized.
    option: Object ; Required.
    This parameter indicates the options that can be set for player's parameters. The options are as follows:

    Parameter Type Default Value Description
    file_id String None Unique ID of the VOD file. This is Required when playing video by video ID
    app_id String None The parameter is Required if the live streaming video is played using video ID. For the videos under the same account, this parameter remains the same.
    width Number None Required, used to configure player width (in pixel). Example: 640
    height Number None Required, used to configure player height (in pixel). Example: 480
    auto_play Number 0 Whether auto playback is allowed. 0: Disable; 1: Enable
    Note: This parameter only applies to Flash players on PC.
    disable_full_screen Number 0 Whether full-screen mode is allowed. 0: Enable; 1: Disable
    Note: This parameter only applies to Flash players on PC.
    disable_drag Number 0 Whether users are allowed to drag the video progress bar. 0: Allow; 1: Disallow
    Note: This parameter only applies to Flash players on PC.
    stretch_full Number 0 Whether the video is scaled up to the same size as the player. 0: Do not scale up. 1: Scale up to full screen
    Note: This parameter only applies to Flash players on PC.
    stop_time Number None Trial mode. For example, if you set it to "60", the video playback stops in 60 seconds, and the "playStatus" event is triggered at the same time
    remember Number 0 Whether to remember last played position. 0: No. 1: Yes. If enabled, the time point when the video was stopped in the previous playback will be recorded and the next playback will start from this position.
    Note: This parameter only applies to Flash players on PC.
    playbackRate Number 1 Playback speed. For example,"2" means the video will be played at double speed, while "0.5" means half speed.
    Note: This option is only applies to H5 players
    hide_h5_setting Boolean false Whether to hide the H5 Settings button. true: Hide. false: Do not hide
    hide_h5_error Boolean false Whether to hide error messages prompted by H5.
    Note: This parameter only applies to H5 players.
    WMode String window When in window mode, you cannot put other page elements over the Flash player. You can change this into opaque or parameter values for other flash wmode if required.
    Note: This parameter only applies to Flash players on PC.
    stretch_patch Boolean false If configured as "true", the video ad that is displayed when the video starts, ends or pauses will be enlarged to cover the whole player.
    definition Number None Used to specify the definition with which the video will be played. The configured definition must be available for the video. Available values: 10, 20, 30, 40, 210, 220, 230, 240. For more information about the relation between these values and video types, see the parameter descriptions for third_video.
    videos Array None When hotlink protection is enabled, you can achieve player playback by configuring an accessible video address for "videos". The definition type is obtained by matching the URL with the URL prefix queried through the backend. For more information, please see User Guide on Hotlink Protection.
    For example: [http://xxx.myqcloud.com/xxxyy\_f220.m3u8?**sign**=xxx,
    third_video Object None This option is only used when playing videos by using video addresses.
    Parameter Example:
    {'duration': 20, //Video duration (in sec). Optional parameter. If not passed, the video duration will be automatically updated when MetaData is loaded.
    Note: This parameter is required in case of MP4 playback.
    'urls': { // (At least one address must be included. Be careful about the video format)
    10: "address for mp4 mobile videos",
    20: "address for mp4 SD videos",
    30: "address for mp4 HD videos",
    40: "address for mp4 ultra high definition videos",
    210: "address for hls mobile videos",
    220: "address for hls SD videos",
    230: "address for hls HD videos",
    240: "address for hls ultra high definition videos"
    Note: If you simulate a mobile device in Chrome or other PC browsers, please use an address for MP4 videos.

    listener: Object; Optional; List of callback functions in case of playing status change.

    Function Name Type Description
    fullScreen function Triggered when entering/exiting full-screen mode. Callback function parameter: isFullScreen: Boolean
    Returned value: true: enter full screen, false: exit full screen

    Note: This event only applies to PC Platform Flash Player
    playStatus function Triggered when playback status changes. Callback function parameter "status": String
    Returned value: ready: "Player is ready"; seeking: "Search"; suspended: "Pause"; playing: "Playback in progress"; playEnd: "Playback ended"; stop: "Triggered by the end of trial duration"; error: "Triggered in case of H5 playback error"
    Example: function(status, msg){ ... }
    dragPlay function Triggered when you drag and change the progress bar; second: Number
    Returned value: Final progress bar position (in sec)

    Note: This event only applies to PC Platform Flash Player

    Obtain parameter and status

    Here are the methods for obtaining parameters and statuses for player object that is returned by the constructor

    Method Returned Value Description
    getVolume Number. Value range: 0-1 Obtain the current volume
    getDuration Number (in sec) Obtain the total duration of the current video
    getCurrentTime Number (in sec) Obtain the current playback position
    isSeeking Boolean ; true indicates "loading" Whether the current playback status is "loading"
    isSuspended Boolean ; true indicates "paused" Whether the current playback status is "paused"
    isPlaying Boolean ; true indicates "playing" Whether the current playback status is "playing"
    isPlayEnd Boolean ; true indicates "playback ended" Whether the current playback status is "playback ended"
    getWidth Number(int) Get the width of current player
    getHeight Number(int) Get the height of current player
    getClarity Number(int) (1: "Mobile", 2: "Standard definition", 3: "High definition", 4: "Ultra high definition") Get the current video definition
    getAllClaritys Array<int> ( 1: "Mobile", 2: "Standard definition", 3: "High definition", 4: "Ultra high definition") Get all available definitions for the current video

    Settings and actions

    The player objects returned by the constructors can be set using the following methods:

    Method Description
    resize(width,height) Parameter: width: int; height: int
    Function: Set the width and height for current player.
    Returned value: none
    play(second) Parameter: second: int (in sec)
    Function: Start playback. You can specify a time point at which the video starts to play
    Returns: int Error Codes
    Note: "second" can only be a null value or 0 when you play a video by using a video address
    pause() Function: Pause the playback of current video
    Returned value: int Error codes
    resume() Funtion: Resume playback.
    Returned value: int Error codes
    setClarity(clarity) Parameter: clarity, int definition. Value range: (1: "Mobile", 2: "Standard definition", 3: "High definition", 4: "Ultra high definition")
    Function: Change video definition
    Returned value: Int Error Codes
    Note: Make sure that the definition is available for the current video before configuring it using "clarity", otherwise the player may choose a definition based on the default player rules
    changeVideo(opt) Parameter: opt Object; Contains the basic information of the video to be played. This is nearly identical to the "second" parameter of the constructor. For more information, please see Constructor Instruction
    Function: Change video dynamically
    Returned value: int Error Codes
    addBarrage(barrage) Parameter: barrage, array barrage information
    "type":"content", // Message type, content: plain text (Required)
    "content":"hello world", // Text message (required)
    "time":"1.101" ,//The time length (in sec) between the moment when the current method is called for adding a caption and the moment when the caption is displayed. (Required)
    "style": "C64B03;35" ,// Separated by semicolons; the first is color value, and the second is font size (optional)
    "postion":"center" // Location
    center: center, bottom: bottom, up: top (optional) }, ... ]
    Function: Add on-screen comments
    Returned value: int Error Codes
    Note: On-screen comment is only implemented at frontend, and backend functions should be self-developed. This function only applies to Flash players on PC.
    closeBarrage() Function: disable on-screen comment. Call addBarrage again to re-enable the feature.
    Returned value: int Error codes
    Note: On-screen comment is only implemented at frontend, and backend functions should be self-developed. This function only applies to Flash players on PC.
    The common error codes of the above methods are as follows:
    Error Code Description
    --------- ---------
    200 Operation successful
    0 Player not fully initialized
    -1 Failed to change video dynamically. Required parameter is missing
    -2 Unknown operation command
    -3 Playback time is beyond valid playback range

    Video File Upload

    Users can use VOD Web SDK to upload videos. Tencent Cloud Video users can therefore upload video files using Web. The SDK supports uploading via HTML5, but it's not possible for browsers that do not support HTML5.

    For more information on how to proceed, see Cloud VOD Web Upload SDK.

    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