tencent cloud

All product documents
Video on Demand
DocumentationVideo on DemandPlayer SDKAPI DocumentationWeb
Web
Download PDF
Last updated: 2024-10-23 11:06:31
Web
Last updated: 2024-10-23 11:06:31
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.
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

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
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

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
Hong Kong, China
+852 800 906 020 (Toll Free)
United States
+1 844 606 0804 (Toll Free)
United Kingdom
+44 808 196 4551 (Toll Free)
Canada
+1 888 605 7930 (Toll Free)
Australia
+61 1300 986 386 (Toll Free)
EdgeOne hotline
+852 300 80699
More local hotlines coming soon