API operations - ApsaraVideo VOD - Alibaba Cloud Documentation Center

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

Note If errors occur when you use ApsaraVideo Player SDK for Web, troubleshoot the errors by following the instructions provided in FAQ about ApsaraVideo Player for Web or Troubleshoot playback errors.


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 URL-based playback has a higher priority over other playback methods. You cannot specify the source parameter when you play a video by using VID and PlayAuth or by using a Security Token Service (STS) token. If you specify this parameter, the player plays the video based on the URL that you specify. We recommend that you use only one playback method. You can use the source parameter to specify the URLs of the streams in multiple definitions. For more information, see Multi-definition playback. Sample code: `source:'{"HD":"address1","SD":"address2"}'`
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: 100% 100px 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: 100% 100px 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 Settings for This Website... > Allow All Autoplay.
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: click: The control bar is displayed when you click on the playback section. hover: The control bar is displayed when you move the pointer over the playback section. always: The control bar is always displayed. never: The control bar is hidden.
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: fullTitle: The video title is displayed when the video is played in full-screen mode on the test page. m3u8BufferLength: the duration of buffered TS files during the playback of HTTP Live Streaming (HLS) videos. Unit: seconds.
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: mp4 hls or m3u8 flv mp3 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: video: returns video files. audio: returns video files that contain only audio, such as MP4 files. You can set this parameter to audio only for the HTML5 player.
qualitySort	String	The sorting method. This parameter is supported only for playback based on VID and PlayAuth. Valid values: desc: descending order. asc: ascending order. Default value: asc. This parameter is supported only for the HTML5 player.
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: FD: low definition LD: standard definition SD: high definition HD: ultra high definition OD: original quality 2K 4K
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: FD: low definition LD: standard definition SD: high definition HD: ultra high definition OD: original quality 2K 4K
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: false: disables background playback. true: enables background playback. Default value: false. 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: center top For more information, see How do I enable the immersive mode for the HTML5 player?.
x5_orientation	String	The video orientation supported by TBS. Valid values: landscape portrait For more information, see How do I enable the immersive mode for the HTML5 player?.
x5LandscapeAsFullScreen	String	Specifies whether to enable the landscape mode for full-screen playback in TBS. Default value: true. Valid values: true: enables the landscape mode. false: enables the portrait mode.
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: zh-cn: Chinese en-us: English
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: true false
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: true: enabled false
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: true false
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: true false Default value: true.
disableSeek	Boolean	Specifies whether to disable the seeking feature. Valid values: true false Default value: false. 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: 0: does not play videos encrypted by using Alibaba Cloud proprietary cryptography. 1: plays videos encrypted by using Alibaba Cloud proprietary cryptography. Note A video that is encrypted by using Alibaba Cloud proprietary cryptography is played based on VID and PlayAuth. A video that is encrypted in HLS encryption mode is played based on the URL. For more information, see Play an encrypted video.
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: true false
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: true: enables frame synchronization. false: disables frame synchronization. Default value: false.
keyShortCuts	Boolean	Specifies whether to enable shortcut keys. Valid values: true false 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 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: `textTracks: [{ kind: 'subtitles', label: 'English (US)', src: 'Subtitle file URL', srclang: 'en-US' }],` The following items describe the parameters: kind: the type of the VTT file. Valid values: subtitles and captions. label: the display name of the subtitle. srclang: the subtitle language. src: the URL of the subtitle file. You need to enable CORS. Note This parameter is supported for ApsaraVideo Player SDK for Web 2.12.0 and later. WebVTT external subtitles are not supported in the following browsers: IE QQ Browser on Android devices, OPPO Browser, and the system browser of OnePlus Other browsers that hijack the video tag.

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. Sample code:

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: `player.replayByVidAndPlayAuth(vid,playauth)`.
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: 400px 60% The player size cannot be smaller than 397 × 297 pixels for a Flash player in Google Chrome.
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: You cannot disable playback speed control or customize a playback speed. However, you can disable the overall settings. Call the hack method to disable playback speed control by overwriting the CSS style. `.prism-setting-speed { display: none !important; }`
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: init: The player is being initialized. ready: The player is ready. loading: The player is loading data. play: The player starts playing. pause: The video in the player is paused. playing: The video in the player is playing. waiting: The video in the player is waiting for buffering. error: An error occurs on the player. ended: The playback ends.
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: horizon: horizontal mirroring vertical: vertical mirroring Example: setImage('horizon'). For more information, see Specify the display mode.
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: `player.setTextTracks([{ kind: 'subtitles', label: 'English (US)', src: 'Subtitle file URL', srclang: 'en-US' }])` 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. `/** * For example, the event is triggered when you change the playback speed to 1.25x. Sample code: * {name: 'Playback speed', type: 'speed', text: '1.25x', key: 1.25} */`
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. `player.on('rtsTraceId', function(data) { console.log('[EVENT]rtsTraceId', data.paramData); })`

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);
```

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.