This topic describes the parameters, methods, events, and error codes for ApsaraVideo Player SDK for Web and provides sample code of API operations used in ApsaraVideo Player SDK for Web.
Parameters
Parameter | Type | Description |
---|---|---|
id | String | The ID of the Dom element for the external container of the player. |
source | String | The video playback URL. Note
|
vid | String | The media ID for media transcoding. |
playauth | String | The video playback credential. For more information, see GetVideoPlayAuth. |
height | String | The height of the player. Valid values:
Note The size of the Flash player in Google Chrome cannot be smaller than 397 × 297 pixels. |
width | String | The width of the player. Valid values:
Note The size of the Flash player in Google Chrome cannot be smaller than 397 × 297 pixels. |
videoWidth | String | The width of the video. This parameter is supported only for the HTML5 player. For more information, see Specify the display mode. |
videoHeight | String | The height of the video. This parameter is supported only for the HTML5 player. For more information, see Specify the display mode. |
preload | Boolean | Specifies whether to enable automatic loading for the player. This parameter is supported only for the HTML5 player. |
cover | String | The default thumbnail of the player. Enter a valid image URL. This parameter takes effect only when autoplay is set to false. For the Flash player, you must also enable the cross-origin resource sharing (CORS) feature for this parameter to take effect. For more information, see Configure CORS. |
isLive | Boolean | Specifies whether a live stream is being played. Live streams cannot be advanced or rewound. Default value: false. You must set this parameter to true for live streaming. |
autoplay | Boolean | Specifies whether to enable autoplay. This parameter does not take effect on mobile devices. Note By default, Safari 11 does not allow autoplay. To allow autoplay in Safari 11, right-click the address bar and choose . |
rePlay | Boolean | Specifies whether to enable automatic loop playback. |
useH5Prism | Boolean | Specifies that the HTML5 player is used. |
useFlashPrism | Boolean | Specifies that the Flash player is used. |
playsinline | Boolean | Specifies whether videos are played inline in the HTML5 player. This parameter does not take effect for specific browsers for Android. |
skinRes | Url | The player skin image. We recommend that you do not change the value of this parameter unless it is necessary. For more information, see Configure the player skin. |
skinLayout | Array | Boolean | The layout of the feature components. If you leave this parameter empty, the default layout is used. false indicates that all feature components are hidden. For more information, see Configure skinLayout. |
controlBarVisibility | String | Specifies how to display the control bar. Default value: hover. Valid values:
|
showBarTime | String | The period of time elapsed before the control bar is automatically hidden. Unit: milliseconds. |
extraInfo | String | The custom parameter. The value is a JSON string. This parameter is supported only for the Flash player. Valid values:
|
enableSystemMenu | Boolean | Specifies whether to display the shortcut menu upon a right click. Default value: false. |
format | String | The format of the playback URL. This parameter is supported only for video playback based on VID. Valid values:
|
mediaType | String | The media type of the returned content. This parameter is supported only for video playback based on VID. Default value: video. Valid values:
|
qualitySort | String | The sorting method. This parameter is supported only for playback based on VID and PlayAuth. Valid values:
|
definition | String | The resolution of the video. Separate different resolutions with commas (,), such as 'FD,LD'. The value is a subset of resolutions supported for the video specified by VID. This parameter is supported only for the HTML5 player. Valid values:
|
defaultDefinition | String | The default video resolution. The value is the resolution of the video specified by VID. This parameter is supported only for the HTML5 player. Valid values:
|
x5_type | String | Specifies that the immersive mode of the HTML5 player is used. The value is h5. For more information, see How do I enable the immersive mode for the HTML5 player?. |
x5_fullscreen | Boolean | Specifies whether to enable full-screen playback in Tencent Browsing Service (TBS) when the video is played. Valid values:
For more information, see How do I enable the immersive mode for the HTML5 player?. |
x5_video_position | String | The position of the video displayed on the screen. Default value: center. Valid values:
|
x5_orientation | String | The video orientation supported by TBS. Valid values:
|
x5LandscapeAsFullScreen | String | Specifies whether to enable the landscape mode for full-screen playback in TBS. Default value: true. Valid values:
|
autoPlayDelay | Number | The playback delay. Unit: seconds. For more information, see Configure the playback delay. |
autoPlayDelayDisplayText | String | The text message that notifies users of the playback delay. For more information, see Configure the playback delay. |
language | String | The language used by the player. Default value: zh-cn. If this parameter is left empty, the language of the browser is used. Valid values:
|
languageTexts | JSON | The custom language text in JSON format. The value is a key:value pair. Example: {jp:{Play:"Play"}}. For more information, see JSON format. |
snapshot | Boolean | Specifies whether to enable the snapshot feature for the Flash player. Default value: false. Valid values:
|
snapshotWatermark | Object | The snapshot watermark for the HTML5 player. |
useHlsPluginForSafari | Boolean | Specifies whether to enable the HLS plug-in for playback in Safari. This parameter is not supported for Safari 11. Default value: false. Valid values:
|
enableStashBufferForFlv | Boolean | Specifies whether to enable buffering when FLV videos are played in the HTML5 player. This parameter takes effect only for live streaming. Default value: true. Valid values:
|
stashInitialSizeForFlv | Number | The initial buffer size for FLV playback in the HTML5 player. This parameter takes effect only for live streaming. Default value: 32. Unit: KB. If you specify a small buffer size, the live stream can be loaded and played within a short period of time. However, shuttering may quickly occur if the value is too small. |
loadDataTimeout | Number | The buffer duration that is required before the system prompts the user to switch to a lower resolution. Unit: seconds. Default value: 20. |
waitingTimeout | Number | The maximum buffer duration. An error message appears after the maximum buffer duration elapses. Unit: seconds. Default value: 60. |
diagnosisButtonVisible | Boolean | Specifies whether to display the diagnosis button. Valid values:
|
disableSeek | Boolean | Specifies whether to disable the seeking feature. Valid values:
Note This parameter is supported only for the Flash player. |
encryptType | Number | Specifies whether to play videos encrypted by using Alibaba Cloud proprietary cryptography. Default value: 0. Valid values:
Note
|
progressMarkers | Array | The content array of the marker on the progress bar. For more information, see Mark the progress bar. |
vodRetry | Number | The number of retries when VOD playback fails. Default value: 3. |
liveRetry | Number | The number of retries when live stream playback fails. Default value: 5. |
hlsFrameChasing | Boolean | Specifies whether to enable frame synchronization for HLS-based live streaming. Default value: false. Valid values:
|
chasingFirstParagraph | Number | The latency after which frame synchronization of phase 1 is enabled. Unit: seconds. Default value: 20. |
chasingSecondParagraph | Number | The latency after which frame synchronization of phase 2 is enabled. Unit: seconds. Default value: 40. |
chasingFirstSpeed | Number | The playback speed when frame synchronization of phase 1 is enabled. Default value: 1.1. |
chasingSecondSpeed | Number | The playback speed when frame synchronization of phase 2 is enabled. Default value: 1.2. |
flvFrameChasing | Boolean | Specifies whether to enable frame synchronization for FLV-based live streaming. Valid values:
|
keyShortCuts | Boolean | Specifies whether to enable shortcut keys. Valid values:
Note The left and right arrow keys enable fast forward and rewind, the up and down arrow keys enable volume increase and volume decrease, and the space bar enables the pause and play of the video. |
keyFastForwardStep | Number | The time range for the fast forward and rewind operations. Unit: seconds. Default value: 10. |
rtsFallbackSource | String | The alternative RTS URL, such as a playback URL in the HLS or FLV format. When you use a playback URL in the RTS format but your browser does not support RTS or stream pulling over RTS fails, the video specified in this URL is automatically played. |
rtsLoadDataTimeout | Number | The RTS timeout period. The system retries to pull streams from RTS after the timeout period elapses. Unit: milliseconds. Default value: 3000. |
traceId | String | The unique user identifier. You can use traceId as the public tracing point to track logs. By default, the event tracking logs are uploaded and traceId is specified for user identification. If you do not specify traceId, ApsaraVideo Player SDK for Web automatically generates a UUID and save the UUID to the browser cache. Note This parameter is supported for ApsaraVideo Player SDK for Web 2.10.0 and later. |
textTracks | Array | The WebVTT external subtitles. Sample code:
The following items describe the parameters:
Note
|
Methods
- For the HTML5 player, use the following sample code:
// HTML5 player var player = new Aliplayer({},function(player) { player.play(); });
- For the Flash player, use the following sample code:
// Flash player player.on('ready',function(e) { player.play(); });
Name | Parameter | Description |
---|---|---|
play | None | Plays a video. |
pause | None | Pauses a video. |
replay | None | Replays a video. |
seek | time | Seeks to the video image at a specific point in time to start the playback. Unit: seconds. |
getCurrentTime | None | Obtains the current playback time. Unit: seconds. |
getDuration | None | Obtains the total duration of a video. Unit: seconds. The value can be obtained only after the video is loaded and the play event is complete. |
getVolume | None | Obtains the current volume. The return value is a real number ranging from 0 to 1. This method does not take effect on iOS devices and specific Android devices. |
setVolume | None | Specifies the volume. The value is a real number ranging from 0 to 1. This method does not take effect on iOS devices and specific Android devices. |
loadByUrl | url and time | Obtains the streaming URL. You can choose whether to specify the time parameter. The unit of the time parameter is second. You can switch between video streams in the same format. The MP4, FLV, and HLS formats are supported. You cannot switch between Real-Time Messaging Protocol (RTMP) streams. |
replayByVidAndPlayAuth | vid: the video ID. playauth: the playback credential. | This parameter is supported only for the HTML5 player. You cannot swtich between video streams in different formats. You cannot switch between RTMP streams. You can call this method to switch between on-demand Digital Rights Management (DRM) streams. Syntax: |
replayByVidAndAuthInfo | This method is available only for ApsaraVideo Media Processing (MPS) users. Specify parameters in the following sequence: vid, accId, accSecret, stsToken, authInfo, domainRegion. | This parameter is supported only for the HTML5 player. You cannot swtich between video streams in different formats. You cannot switch between RTMP streams. |
setPlayerSize | w and h | Specifies the size of the player. Valid values:
|
setSpeed | speed | Specifies the playback speed. Plaback speeds ranging from 0.5 to 2 are supported. This parameter is supported only for the HTML5 player. This method may not take effect for apps on mobile devices, such as WeChat for Android. By default, the user interface (UI) of playback speed control is enabled. Note How to disable playback speed control:
|
setSanpshotProperties | width: the width of the snapshot. height: the height of the snapshot. rate: the quality of the snapshot. | Sets the parameters for snapshots. |
fullscreenService.requestFullScreen | None | Enables full-screen mode. This method is supported only for the HTML5 player. |
fullscreenService.cancelFullScreen | None | Exits full-screen mode. This method does not take effect on iOS devices. This method is supported only for the HTML5 player. |
fullscreenService.getIsFullScreen | None | Obtains the full screen status of the player. This method is supported only for the HTML5 player. |
getStatus | None | Obtains the player status. Valid values:
|
setRotate | rotate: the rotation angle. | Specifies the rotation angle. A positive value specifies a clockwise rotation and a negative value specifies a anticlockwise rotation. Example: setRotate(90). For more information, see Specify the display mode. |
getRotate | None | Obtains the rotation angle. For more information, see Specify the display mode. |
setImage | image: the mirroring mode. | Specifies the mirroring mode. Valid values:
|
dispose | None | Destroys a player. |
setCover | cover: the thumbnail URL. | Specifies the thumbnail URL. |
setProgressMarkers | marker: the marker dataset. | Specifies markers. |
setPreviewTime | time: the preview duration. | Sets the preview duration. Unit: seconds. For more information, see the Preview (URL) component on the Aliplayer website. |
getPreviewTime | None | Obtains the preview duration. |
isPreview | None | Specifies whether to enable the preview feature. |
getCurrentPDT | None | You can obtain the ProgramDateTime value in real time for HLS videos. |
setTraceId | traceId: the public tracking point | The public tracking point used to track logs. You can call player.setTraceId(traceId); to set traceId. Note This parameter is supported for ApsaraVideo Player SDK for web 2.10.0 and later. |
setTextTracks | textTracks | Sets WebVTT external subtitles. Sample code:
Note This method is supported for ApsaraVideo Player SDK for Web 2.12.0 and later. |
Events
Player events
Name | Description |
---|---|
ready | The event that is triggered when the video initialization button of the player is rendered. Initialize the player UI settings after the ready event is complete to prevent the UI from being overwritten during initialization. Note Methods provided by a player can be called only after the ready event is complete. |
play | The event that is triggered when a paused video is played again. |
pause | The event that is triggered when a video is paused. |
canplay | The event that is triggered when an audio or video file is ready for playback. This event can be triggered multiple times and is supported only for the HTML5 player. |
playing | The event that is triggered during playback. This event can be triggered multiple times. |
ended | The event that is triggered after the video playback is complete. |
liveStreamStop | The event that is triggered when live streams are interrupted. This event is triggered after the player fails to play an HLS stream for five consecutive times. This event indicates that the live stream is interrupted or the video needs to be reloaded. Note If an HLS stream is interrupted or an error occurs during live streaming, the player automatically tries to reload the stream for five times. You do not need to configure a retry logic. |
onM3u8Retry | The retry event that is triggered when an HLS stream is interrupted. This event is triggered only once for each live stream interruption. |
hideBar | The event that is triggered to automatically hide the control bar. |
showBar | The event that is triggered to automatically display the control bar. |
waiting | The data caching event. |
timeupdate | The event that is triggered when the playback position changes. This event is supported only for the HTML5 player. You can call the getCurrentTime method to obtain the current playback time. |
snapshoted | The event that is triggered when a snapshot is captured. |
requestFullScreen | The event that is triggered to enable full-screen mode. This event is supported only for the HTML5 player. |
cancelFullScreen | The event that is called to exit full-screen mode. This event is supported only for the HTML5 player and is not triggered on iOS devices. |
error | The event that is triggered when a playback error occurs. |
startSeek | The event that is triggered when seeking starts. The return value is the position in the video where seeking starts. |
completeSeek | The event that is triggered when seeking ends. The return value is the position in the video where seeking ends. |
resolutionChange | The event that is triggered when the video resolution is changed during live streaming. |
seiFrame | The event that is triggered when Supplemental Enhancement Information (SEI) is received for HLS or FLV-based playback. |
rtsFallback | This event is triggered when a degraded protocol is used for playback. reason indicates the degradation cause and fallbackUrl indicates the alternate URL. |
settingSelected | The event that is triggered when playback settings such as the speed, definition, and subtitles are changed.
|
rtsTraceId | The event that is triggered when an RTS stream is pulled. Listen for the event to obtain the TraceId. In the event callback, traceId indicates the TraceId that is used for stream pulling and source indicates the playback URL of the RTS stream.
|
- You can subscribe to an event by using the on method of a player instance. Sample code:
var handleReady = function(e) { console.log(e); } player.on('ready',handleReady);
- You can unsubscribe from an event by using the off method of a player instance. Sample code:
player.off('ready',handleReady);
Error codes
Code | Description |
---|---|
4001 | The error message returned because the parameter is invalid. |
4002 | The error message returned because the playback credential has expired. |
4003 | The error message returned because the URL is invalid. |
4004 | The error message returned because the URL does not exist. |
4005 | The error message returned because an error has occurred when the player started to download data. Check the network connectivity and whether the playback URL is accessible. |
4006 | The error message returned because an error has occurred when the player started to download metadata. |
4007 | The error message returned because a playback error has occurred. |
4008 | The error message returned because the loading has timed out. Check the network connectivity and whether the playback URL is accessible. |
4009 | The error message returned because a data request error has occurred. Check the network connectivity and whether the playback URL is accessible. |
4010 | The error message returned because videos encrypted by using Alibaba Cloud propriety cryptography cannot be played. |
4011 | The error message returned because the video format is not supported. |
4012 | The error message returned because the playauth parameter failed to be parsed. |
4013 | The error message returned because the playback data failed to be decoded. Check whether the browser supports the video format. |
4014 | The error message returned because the network is unavailable. |
4015 | The error message returned because data retrieving is aborted. |
4016 | The error message returned because data loading failed due to a network error. |
4017 | The error message returned because the returned playback URL is empty. |
4100 | The error message returned because the signaling request failed. |
4110 | The error message returned because WebRTC is not supported. |
4111 | The error message returned because the browser is not supported. |
4112 | The error message returned because the browser version is outdated. |
4113 | The error message returned because H.264 is not supported. |
4114 | The error message returned because the offer fails to be created. |
4115 | The error message returned because autoplay failed. |
4116 | The error message returned because the playback URL uses an invalid protocol. |
4118 | The error message returned because the specified HTML element is not an audio or a video stream. |
4200 | The error message returned because the playback failed. |
4400 | The error message returned because an unknown error has occurred. Resources failed to be loaded due to a server or network error, or the resource format is not supported. |
4500 | The error message returned because a server request failed. View the specific error message of the VOD request. |