This topic describes the parameters, methods, and events of ApsaraVideo Player SDK for web. This topic also provides sample code of methods 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. |
preventRecord | Boolean | Specifies whether to enable the download prevention feature for encrypted video streams. |
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 the Configure display settings section of the "Basic features" topic. |
videoHeight | String | The height of the video. This parameter is supported only for the HTML5 player. For more information, see the Configure display settings section of the "Basic features" topic. |
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 if the autoplay parameter 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 support 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 whether to use the HTML5 player. |
useFlashPrism | Boolean | Specifies whether to use the Flash player. |
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. A value of false indicates that all feature components are hidden. For more information, see Configure skinLayout. |
controlBarVisibility | String | The mode 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: millisecond. |
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:
By default, this parameter is left empty. If you specify a value for this parameter, it takes effect only for the HTML5 player. |
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:
Default value: asc. This parameter is supported only for the HTML5 player. |
definition | String | The resolution of the video. Separate different resolutions with commas (,). Example: '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:
|
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 the 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. 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. Valid values:
|
enableStashBufferForFlv | Boolean | Specifies whether to enable buffering when Flash Video (FLV) videos are played in the HTML5 player. This parameter takes effect only for live streaming. 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, stuttering 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:
Default value: true. |
disableSeek | Boolean | Specifies whether to disable the seeking feature. Valid values:
Default value: false. Note This parameter is supported only for the Flash player. |
encryptType | Number | Specifies whether to play videos that are 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 video-on-demand (VOD) playback fails. Default value: 3. |
liveRetry | Number | The number of retries when live streaming fails. Default value: 5. |
hlsFrameChasing | Boolean | Specifies whether to enable frame synchronization for HLS-based live streaming. 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:
Default value: false. |
keyShortCuts | Boolean | Specifies whether to enable shortcut keys. Valid values:
Default value: false. 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 Real-Time Streaming (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: millisecond. Default value: 3000. |
traceId | String | The unique user identifier. You can use the value of this parameter as the public tracing point to track logs. By default, the event tracking logs are uploaded and the traceId parameter is specified for user identification. If you do not specify the traceId parameter, 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 V2.10.0 and later. |
textTracks | Array | The WebVTT external subtitles. Sample code: The following section describes the parameters:
Note
|
Methods
You can call methods after the ready event is complete or in the ready callback for creating the player. In the HTML5 player, methods can be called in the callback function of the constructor that is used to create a player. Examples:
The following sample code shows how to call methods on the HTML5 player:
// HTML5 player var player = new Aliplayer({},function(player) { player.play(); });The following sample code shows how to call methods on the Flash player:
// Flash player player.on('ready',function(e) { player.play(); });
Method | 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. Unit: seconds. 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 switch 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 for 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 switch between video streams in different formats. You cannot switch between RTMP streams. |
setPlayerSize | w and h | Specifies the size of the player. Valid values:
The size of the Flash player in Google Chrome cannot be smaller than 397 × 297 pixels. |
setSpeed | speed | Specifies the playback speed. Playback 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) for playback speed control is enabled. Note To disable playback speed, perform the following operations:
|
setSanpshotProperties | width: the width of the snapshot. height: the height of the snapshot. rate: the quality of the snapshot. | Specifies 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 indicates a clockwise rotation and a negative value indicates an anticlockwise rotation. Example: setRotate(90). For more information, see the Configure display settings section of the "Basic features" topic. |
getRotate | None | Obtains the rotation angle. For more information, see the Configure display settings section of the "Basic features" topic. |
setImage | image: the mirroring mode. | Specifies the mirroring mode. Valid values:
Example: setImage('horizon'). For more information, see the Configure display settings section of the "Basic features" topic. |
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. | Specifies 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 the Note This parameter is supported for ApsaraVideo Player SDK for web V2.10.0 and later. |
setTextTracks | textTracks | Specifies WebVTT external subtitles. Sample code: Note This parameter is supported for ApsaraVideo Player SDK for web V2.12.0 and later. |
Events
Player events
Event | 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 called 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 triggered 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 from which seeking starts. |
completeSeek | The event that is triggered when seeking ends. The return value is the position in the video to which 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. The |
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, the value of the traceId parameter indicates the TraceId that is used for stream pulling and the value of the source parameter indicates the playback URL of the RTS stream. |
Subscribe to events
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);