tencent cloud


TCPlayer Integration Guide

Last updated: 2024-06-25 11:48:28
    This document introduces the Web Player SDK (TCPlayer) tailored for both VOD and live streaming. It can be quickly integrated with your own web application to enable video playback features. TCPlayer comes with a default set of UI elements, which you can use as needed.


    The web player utilizes the <video> tag of HTML5 and Flash for video playback. It offers a uniform video playback experience across different platforms when browsers do not natively support video playback. In conjunction with Tencent's Video on Demand service, it provides hotlink protection and features for playing standard encrypted HLS videos.

    Supported protocols

    Audio/Video Protocol
    URL Format
    PC Browser
    Mobile Browser
    VOD playback
    Live stream
    VOD playback
    Live stream
    Partially supported
    VOD playback
    Partially supported
    Live stream
    Only H.264 encoding is supported.
    The player is compatible with mainstream browsers and can automatically select the optimal playback scheme depending on the browser.
    In some browser environments, HLS and FLV video playback depends on Media Source Extensions.
    If a browser does not support WebRTC, a WebRTC URL passed in will be converted automatically to better support playback.

    Supported Features

    QQ Browser
    Mac Safari
    iOS Safari
    Android Chrome
    IE 11
    Player dimension configuration
    Resuming playback
    Playback speed change
    Preview thumbnails
    Changing `fileID` for playback
    Flipping videos
    Progress bar marking
    HLS adaptive bitrate
    Referer hotlink protection
    Definition change notifications
    Playing HLS videos encrypted using standard schemes
    Playing HLS videos encrypted using private protocols
    iOS: -
    Video statistics
    Video data monitoring
    Custom UI messages
    Custom UI
    On-screen comments
    Ghost watermark
    Frame sync under poor network conditions
    Only H.264 encoding is supported.
    Chrome and Firefox for Windows and macOS are supported.
    Chrome, Firefox, Edge, and QQ Browser need to load hls.js to play HLS.
    The Referer hotlink protection feature is based on the Referer field of HTTP request headers. Some HTTP requests initiated by Android browsers do not carry the Referer field.
    The player is compatible with mainstream browsers and can automatically select the optimal playback scheme depending on the browser used. For example, for modern browsers such as Chrome, the player uses the HTML5 technology for playback, and for mobile browsers, it uses the HTML5 technology or the browser’s built-in capabilities.


    From version 5.0.0, the TCPlayer SDK for Web (TCPlayer) requires access to a License authorization for use. If you don't need the new premium functions, you can apply for a basic License to try TCPlayer for free; if you want to use the newly added premium functions, you need to purchase a premium License. The detailed information is as follows:
    TCPlayer feature
    Feature Scope
    Required License
    Authorization Unit
    Basic Functions
    Includes all features provided in versions prior to 5.0.0, see Product Features for details
    Web Player Basic Version License
    0 CNY
    An exact domain (1 License can authorize up to 10 exact domains)
    Premium Functions
    Basic Version Features, VR Playback, Security Check
    Web Player Premium Version License
    399 CNY/month Buy Now
    Wildcard Domain (1 License can authorize up to 1 wildcard domain)
    1. Web Player Basic Version License can be applied for free, with a default validity of 1 year; if the remaining validity period is less than 30 days, it can be renewed for free.
    2. To facilitate local development, the player won't authenticate localhost or; hence, these types of local service domain names need not be applied for when requesting a License.

    Integration Guide

    By following these steps, you can add a video player to your website.

    Step 1. Import files into the page

    The Player SDK supports two integration methods: CDN and NPM:

    1. Integration through CDN

    Create a new index.html file in your local project and import the player style and script files into the HTML page.
    It is recommended to deploy resources on your own when using the Player SDK, click Download player resources. Deploy the unzipped folder without altering its directory structure to prevent cross-referencing issues between resources. If the deployment address is aaa.xxx.ccc, import the player style and script files at the appropriate places. When deploying on your own, you need to manually reference the dependency files under the libs folder of the resource package, otherwise, the Tencent Cloud CDN files will be requested by default.
    <link href="aaa.xxx.ccc/tcplayer.min.css" rel="stylesheet"/>
    <!--To play HLS format videos in modern browsers like Chrome and Firefox through H5, hls.min.x.xx.m.js must be included before tcplayer.vx.x.x.min.js.-->
    <script src="aaa.xxx.ccc/libs/hls.min.x.xx.m.js"></script>
    <!--Player script file-->
    <script src="aaa.xxx.ccc/tcplayer.vx.x.x.min.js"></script>

    2. Integration through npm

    First, install the tcplayer npm package:
    npm install tcplayer.js
    Import the SDK and style files:
    import TCPlayer from 'tcplayer.js';
    import 'tcplayer.js/dist/tcplayer.min.css';

    Step 2. Place the player container

    Add the player container to the location on the page where the player is to be displayed. For example, add the following code in index.html (the container ID and dimensions can be custom defined).
    <video id="player-container-id" width="414" height="270" preload="auto" playsinline webkit-playsinline>
    The player container must be a <video> tag.
    In the example, player-container-id is the ID of the player container, which you can set yourself.
    We recommend you set the size of the player container zone through CSS, which is more flexible than the attribute and can achieve effects such as fit to full screen and container adaption.
    The preload attribute in the example specifies whether to load the video after the page is loaded. It is usually set to auto for faster video playback. Other options are: meta (to only load metadata after the page loads) and none (to not load the video after the page loads). Videos will not automatically load on mobile devices due to system restrictions.
    The attributes playsinline and webkit-playsinline are used to achieve inline playback in standard mobile browsers without hijacking video playback. This is just an example, please use as needed.
    Setting the x5-playsinline attribute in the TBS kernel will utilize the X5 UI player.

    Step 3. Initialize the player

    After page initialization, you can play video resources. The player supports both video on demand (VOD) and live streaming playback scenarios as follows:
    VOD playback: The player can play Tencent Video on Demand media resources through FileID. For the specific VOD process, please refer to the Using the Player for Playback document.
    Live playback: The player can pull a live audio/video stream for playback by passing in a URL. For information on generating a Tencent Cloud Streaming Services URL, see Splicing Live Streaming URLs.
    URL playback (VOD and live)
    File ID playback (VOD)
    After page initialization, call the method in the player instance to pass in the URL to the method.
    // `player-container-id` is the player container ID, which must be the same as in HTML
    var player = TCPlayer('player-container-id', {
    sources: [{
    src: 'Please replace with your playback URL',
    licenseUrl: 'Please replace with your licenseUrl', // License URL, see the preparation section. You can obtain the licenseUrl after applying for a license in the RT-Cube console
    language: 'Please replace with your Setting language', // Setting language en | zh-CN
    // player.src(url); // URL playback address
    In the initialization code on the index.html page, add the following initialization script. Pass in the video ID and appID obtained during the preparation phase from the fileID (in Media Management) and (peek in Account Information > Basic Information).
    var player = TCPlayer('player-container-id', { // player-container-id is the player container ID, which must be the same as that in HTML
    fileID: 'Please enter your fileID', // Enter the fileID of the video to be played
    appID: 'Please enter your appID', // Enter the appID of your VOD account
    // Enter the player Signature psign, for information on the Signature and how to generate it see the link: https://www.tencentcloud.com/document/product/266/42436?from_cn_redirect=1
    psign: 'Please enter your player Signature psign',
    licenseUrl: 'Please enter your licenseUrl', // Refer to the preparation section. You can obtain the licenseUrl after applying for a license in the RT-Cube console
    language: 'Please replace with your Setting language', // Setting language en | zh-CN
    Please Note:
    Not all videos can be played successfully in a browser. We recommend you use Tencent Cloud’s services to transcode a video before playing it.

    Step 4. Implement more features

    You can utilize the server-side capabilities of Video on Demand (VOD) for advanced features, such as automatic switching of adaptive streams, video thumbnail previews, and adding video marker information. These features are detailed in Play back a long video, which you can refer to for implementation.
    Additionally, the player offers more features. For a list of features and instructions on how to use them, please see the Feature Demonstration page.
    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