tencent cloud

Feedback

Last updated: 2024-06-06 10:34:01
    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.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support