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.
ParameterTypeDescription
idStringThe ID of the Dom element for the external container of the player.
sourceStringThe 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"}'
vidStringThe media ID for media transcoding.
playauthStringThe video playback credential. For more information, see GetVideoPlayAuth.
heightStringThe 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.
widthStringThe 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.
videoWidthStringThe width of the video. This parameter is supported only for the HTML5 player. For more information, see Specify the display mode.
videoHeightStringThe height of the video. This parameter is supported only for the HTML5 player. For more information, see Specify the display mode.
preloadBooleanSpecifies whether to enable automatic loading for the player. This parameter is supported only for the HTML5 player.
coverStringThe 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.
isLiveBooleanSpecifies 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.
autoplayBooleanSpecifies 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.
rePlayBooleanSpecifies whether to enable automatic loop playback.
useH5PrismBooleanSpecifies that the HTML5 player is used.
useFlashPrismBooleanSpecifies that the Flash player is used.
playsinlineBooleanSpecifies whether videos are played inline in the HTML5 player. This parameter does not take effect for specific browsers for Android.
skinResUrlThe 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.
skinLayoutArray | BooleanThe 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.
controlBarVisibilityStringSpecifies 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.
showBarTimeStringThe period of time elapsed before the control bar is automatically hidden. Unit: milliseconds.
extraInfoStringThe 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.
enableSystemMenuBooleanSpecifies whether to display the shortcut menu upon a right click. Default value: false.
formatStringThe 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.
mediaTypeStringThe 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.
qualitySortStringThe 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.
definitionStringThe 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
defaultDefinitionStringThe 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_typeStringSpecifies 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_fullscreenBooleanSpecifies 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_positionStringThe 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_orientationStringThe video orientation supported by TBS. Valid values:
  • landscape
  • portrait
For more information, see How do I enable the immersive mode for the HTML5 player?.
x5LandscapeAsFullScreenStringSpecifies 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.
autoPlayDelayNumberThe playback delay. Unit: seconds. For more information, see Configure the playback delay.
autoPlayDelayDisplayTextStringThe text message that notifies users of the playback delay. For more information, see Configure the playback delay.
languageStringThe 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
languageTextsJSONThe custom language text in JSON format. The value is a key:value pair. Example: {jp:{Play:"Play"}}. For more information, see JSON format.
snapshotBooleanSpecifies whether to enable the snapshot feature for the Flash player. Default value: false. Valid values:
  • true
  • false
snapshotWatermarkObjectThe snapshot watermark for the HTML5 player.
useHlsPluginForSafariBooleanSpecifies 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
enableStashBufferForFlvBooleanSpecifies 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
stashInitialSizeForFlvNumberThe 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.

loadDataTimeoutNumberThe buffer duration that is required before the system prompts the user to switch to a lower resolution. Unit: seconds. Default value: 20.
waitingTimeoutNumberThe maximum buffer duration. An error message appears after the maximum buffer duration elapses. Unit: seconds. Default value: 60.
diagnosisButtonVisibleBooleanSpecifies whether to display the diagnosis button. Valid values:
  • true
  • false
Default value: true.
disableSeekBooleanSpecifies whether to disable the seeking feature. Valid values:
  • true
  • false
Default value: false.
Note This parameter is supported only for the Flash player.
encryptTypeNumberSpecifies 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.
progressMarkersArrayThe content array of the marker on the progress bar. For more information, see Mark the progress bar.
vodRetryNumberThe number of retries when VOD playback fails. Default value: 3.
liveRetryNumberThe number of retries when live stream playback fails. Default value: 5.
hlsFrameChasingBooleanSpecifies whether to enable frame synchronization for HLS-based live streaming. Default value: false. Valid values:
  • true
  • false
chasingFirstParagraphNumberThe latency after which frame synchronization of phase 1 is enabled. Unit: seconds. Default value: 20.
chasingSecondParagraphNumberThe latency after which frame synchronization of phase 2 is enabled. Unit: seconds. Default value: 40.
chasingFirstSpeedNumberThe playback speed when frame synchronization of phase 1 is enabled. Default value: 1.1.
chasingSecondSpeedNumberThe playback speed when frame synchronization of phase 2 is enabled. Default value: 1.2.
flvFrameChasingBooleanSpecifies whether to enable frame synchronization for FLV-based live streaming. Valid values:
  • true: enables frame synchronization.
  • false: disables frame synchronization.
Default value: false.
keyShortCutsBooleanSpecifies 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.
keyFastForwardStepNumberThe time range for the fast forward and rewind operations. Unit: seconds. Default value: 10.
rtsFallbackSourceStringThe 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.

rtsLoadDataTimeoutNumberThe RTS timeout period. The system retries to pull streams from RTS after the timeout period elapses. Unit: milliseconds. Default value: 3000.
traceIdStringThe 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.
textTracksArrayThe 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();
     });
NameParameterDescription
playNonePlays a video.
pauseNonePauses a video.
replayNoneReplays a video.
seektimeSeeks to the video image at a specific point in time to start the playback. Unit: seconds.
getCurrentTimeNoneObtains the current playback time. Unit: seconds.
getDurationNoneObtains 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.
getVolumeNoneObtains 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.
setVolumeNoneSpecifies 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.
loadByUrlurl and timeObtains 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.
replayByVidAndPlayAuthvid: 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).

replayByVidAndAuthInfoThis 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.
setPlayerSizew and hSpecifies 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.
setSpeedspeedSpecifies 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;
      }
setSanpshotPropertieswidth: the width of the snapshot. height: the height of the snapshot. rate: the quality of the snapshot.Sets the parameters for snapshots.
fullscreenService.requestFullScreenNoneEnables full-screen mode. This method is supported only for the HTML5 player.
fullscreenService.cancelFullScreenNoneExits full-screen mode. This method does not take effect on iOS devices. This method is supported only for the HTML5 player.
fullscreenService.getIsFullScreenNoneObtains the full screen status of the player. This method is supported only for the HTML5 player.
getStatusNoneObtains 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.
setRotaterotate: 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.
getRotateNoneObtains the rotation angle. For more information, see Specify the display mode.
setImageimage: 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.
disposeNoneDestroys a player.
setCovercover: the thumbnail URL.Specifies the thumbnail URL.
setProgressMarkersmarker: the marker dataset.Specifies markers.
setPreviewTimetime: the preview duration.Sets the preview duration. Unit: seconds. For more information, see the Preview (URL) component on the Aliplayer website.
getPreviewTimeNoneObtains the preview duration.
isPreviewNoneSpecifies whether to enable the preview feature.
getCurrentPDTNoneYou can obtain the ProgramDateTime value in real time for HLS videos.
setTraceIdtraceId: the public tracking pointThe 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.
setTextTrackstextTracksSets 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

NameDescription
readyThe 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.
playThe event that is triggered when a paused video is played again.
pauseThe event that is triggered when a video is paused.
canplayThe 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.
playingThe event that is triggered during playback. This event can be triggered multiple times.
endedThe event that is triggered after the video playback is complete.
liveStreamStopThe 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.
onM3u8RetryThe retry event that is triggered when an HLS stream is interrupted. This event is triggered only once for each live stream interruption.
hideBarThe event that is triggered to automatically hide the control bar.
showBarThe event that is triggered to automatically display the control bar.
waitingThe data caching event.
timeupdateThe 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.
snapshotedThe event that is triggered when a snapshot is captured.
requestFullScreenThe event that is triggered to enable full-screen mode. This event is supported only for the HTML5 player.
cancelFullScreenThe 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.
errorThe event that is triggered when a playback error occurs.
startSeekThe event that is triggered when seeking starts. The return value is the position in the video where seeking starts.
completeSeekThe event that is triggered when seeking ends. The return value is the position in the video where seeking ends.
resolutionChangeThe event that is triggered when the video resolution is changed during live streaming.
seiFrameThe 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}
 */
rtsTraceIdThe 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

CodeDescription
4001The error message returned because the parameter is invalid.
4002The error message returned because the playback credential has expired.
4003The error message returned because the URL is invalid.
4004The error message returned because the URL does not exist.
4005The 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.
4006The error message returned because an error has occurred when the player started to download metadata.
4007The error message returned because a playback error has occurred.
4008The error message returned because the loading has timed out. Check the network connectivity and whether the playback URL is accessible.
4009The error message returned because a data request error has occurred. Check the network connectivity and whether the playback URL is accessible.
4010The error message returned because videos encrypted by using Alibaba Cloud propriety cryptography cannot be played.
4011The error message returned because the video format is not supported.
4012The error message returned because the playauth parameter failed to be parsed.
4013The error message returned because the playback data failed to be decoded. Check whether the browser supports the video format.
4014The error message returned because the network is unavailable.
4015The error message returned because data retrieving is aborted.
4016The error message returned because data loading failed due to a network error.
4017The error message returned because the returned playback URL is empty.
4100The error message returned because the signaling request failed.
4110The error message returned because WebRTC is not supported.
4111The error message returned because the browser is not supported.
4112The error message returned because the browser version is outdated.
4113The error message returned because H.264 is not supported.
4114The error message returned because the offer fails to be created.
4115The error message returned because autoplay failed.
4116The error message returned because the playback URL uses an invalid protocol.
4118The error message returned because the specified HTML element is not an audio or a video stream.
4200The error message returned because the playback failed.
4400The 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.
4500The error message returned because a server request failed. View the specific error message of the VOD request.