This topic describes the attributes and events of ApsaraVideo Player SDK for web. This topic also provides the sample code of ApsaraVideo Player methods.
Player attributes
Attribute | Type | Description |
---|---|---|
id | String | The ID of the dom element for the external container of the player. |
source | String | The video playback URL. The URL is a separate URL. By default, a video is played based
on the video ID (VID) and playAuth .
Note Source-based playback has the highest priority. You can use the source attribute to
set multiple resolutions. Example: source:'{"HD":"address1","SD":"address2"}'. For
more information, see Multi-resolution playback.
|
vid | String | The media ID for media transcoding. |
playauth | String | The unique credential for video playback. For more information about how to obtain the playAuth, see GetVideoPlayAuth. |
height | String | The height of the player. Valid values:
Note The size cannot be smaller than 397 × 297 pixels for a Flash player in Google Chrome.
|
width | String | The width of the player. Valid values:
Note The size cannot be smaller than 397 × 297 pixels for a Flash player in Google Chrome.
|
videoWidth | String | The width of the video. This attribute is supported only by HTML5 players. For more information, see Rotation and mirroring. |
videoHeight | String | The height of the video. This attribute is supported only by HTML5 players. For more information, see Rotation and mirroring. |
preload | Boolean | Specifies whether to enable automatic loading for the player. This attribute is supported only by HTML5 players. |
cover | String | The default thumbnail of the player. Enter a valid image URL. This attribute takes effect only when the autoplay attribute is set to false. Cross-origin resource sharing (CORS) must be enabled for the thumbnail when the video is played by Flash players. |
isLive | Boolean | Specifies whether the playback is live streaming. If the playback is live streaming, you are not allowed to drag the progress bar. |
autoplay | Boolean | Specifies whether to enable autoplay. This attribute does not take effect for mobile
terminals.
Note Safari 11 does not automatically enable autoplay.
|
rePlay | Boolean | Specifies whether to enable automatic loop playback. |
useH5Prism | Boolean | Specifies whether to use an HTML5 player for playback. |
useFlashPrism | Boolean | Specifies whether to use a Flash player for playback. |
playsinline | Boolean | Specifies whether to enable HTML5-embedded playback. This attribute does not take effect for specific Android-based web browsers. |
showBuffer | Boolean | Specifies whether to display a buffer icon during playback. The default value is true. |
skinRes | Url | The skin image. Do not modify this attribute unless it is necessary. For more information about how to modify the attribute, see Configure the player skin. |
skinLayout | Array | Boolean | The layout of the components. If you do not set this attribute, the default layout is used for components. If this attribute is set to false, all the functional components are hidden. For more information, see Configure the skinLayout attribute. |
controlBarVisibility | String | The mode to display the control panel. The default value is hover. Valid values:
|
showBarTime | String | The length of time during which the control bar is automatically hidden, in milliseconds. |
extraInfo | String | A JSON string that is used to customize operation information. This attribute is supported
only by Flash players. Valid values:
|
enableSystemMenu | Boolean | Specifies whether to display the shortcut menu upon a right click. The default value is false. |
format | String | The streaming URL format. This attribute is supported only by VID-based playback.
Valid values:
|
mediaType | String | The media type of the returned content. This attribute is supported only by VID-based
playback. The default value is video. Valid values:
|
qualitySort | String | The sorting method. This attribute is supported only by playback based on the VID
and playAuth. Valid values:
|
definition | String | The video resolution. Separate different resolutions with commas (,), such as FD,
LD. The value is a subset of resolutions of the stream corresponding to the VID. Valid
values:
|
defaultDefinition | String | The default video resolution. The value is the resolution of the stream corresponding
to the VID. Valid values:
|
x5_type | String | Declares to use the immersive mode of the HTML5 player. Set this attribute to H5 when you enable the immersive mode of the HTML5 player. For more information, see How do I enable the immersive mode for the HTML5 player?. |
x5_fullscreen | Boolean | Declares whether to enter the full-screen playback by 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 a video player on the screen. The default value is center. Valid values:
|
x5_orientation | String | The orientation of the video that is played by TBS. Valid values:
|
x5LandscapeAsFullScreen | String | Specifies whether to enable the landscape mode for full-screen playback by TBS. The
default value is true. Valid values:
|
autoPlayDelay | Number | The playback delay, in seconds. For more information, see Configure the playback delay. |
autoPlayDelayDisplayText | String | The text that notifies users of the playback delay. For more information, see Configure the playback delay. |
language | String | The language that is used by the player. The default value is zh-cn. If this attribute is empty, the language of the web browser will be applied. Valid
values:
|
languageTexts | JSON | The JSON structure of the custom player language text. The key value must correspond to the value of the language attribute. Example: {jp:{Play:"Play"}}. For more information about custom values, see JSON structure. |
snapshot | Boolean | Specifies whether to enable the snapshot capture feature in Flash players. |
snapshotWatermark | Object | The snapshot watermark in HTML5. |
useHlsPluginForSafari | Boolean | Specifies whether to enable the HTTP Live Streaming (HLS) plug-in for playback in Safari, except for Safari 11. |
enableStashBufferForFlv | Boolean | Specifies whether to enable playback caching during Flash Video (FLV) playback in HTML5. This attribute takes effect only for live streaming. |
stashInitialSizeForFlv | Number | The initial cache size for FLV playback in HTML5. This attribute takes effect only for live streaming. |
loadDataTimeout | Number | The buffering duration that is required to display a message prompting users to switch to a lower resolution. The unit is seconds. The default value is 20. |
waitingTimeout | Number | The maximum buffer duration, in seconds. After the specified duration, an error message appears. The default value is 60. |
diagnosisButtonVisible | Boolean | Specifies whether to display the detection button. Valid values:
|
disableSeek | Boolean | Specifies whether to disable the seeking feature of the progress bar. Valid values:
Note This attribute is supported only by Flash players.
|
encryptType | int | The encryption type. When a video that is encrypted by using Alibaba Cloud proprietary
cryptography is played, the default value is 0. Valid values:
Note
|
progressMarkers | Array | The content array of the marker on the progress bar. For more information, see Mark on the progress bar. |
vodRetry | int | The number of retry times when VOD playback fails. The default value is 3. |
liveRetry | int | The number of retry times when live stream playback fails. The default value is 5. |
hlsFrameChasing | boolean | Specifies whether to enable frame synchronization for HLS-based playback. |
chasingFirstParagraph | number | The latency after which frame synchronization of phase 1 is enabled, in seconds. The default value is 20. |
chasingSecondParagraph | number | The latency after which frame synchronization of phase 2 is enabled, in seconds. The default value is 40. |
chasingFirstSpeed | number | The playback speed when frame synchronization of phase 1 is enabled. The default value is 1.1. |
chasingSecondSpeed | number | The playback speed when frame synchronization of phase 2 is enabled. The default value is 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 fast backward. The up and down
arrow keys enable volume increase and volume decrease. The space bar enables the pause
and replay of the video.
|
keyFastForwardStep | Number | The duration of fast forward and fast backward, in seconds. The default value is 10. |
Player methods
Operations must be used after the ready event occurs or during callback in the player
creation ready state. In HTML5, operations can be called by the callback function
of the constructor that is used to create a player. The following code snippets provide
examples:
- Flash player
// Flash player player.on('ready',function(e) { player.play(); });
- HTML5 player
// HTML5 player var player = new Aliplayer({},function(player) { player.play(); });
Method | Parameter | Description |
---|---|---|
play | N/A | Plays a video. |
pause | N/A | Pauses a video. |
replay | N/A | Replays a video. |
seek | time | Seeks to the video image at the specific point in time to start the playback. The unit of the time parameter is seconds. |
getCurrentTime | N/A | Obtains the current playback time, in seconds. |
getDuration | N/A | Obtains the total duration of a video, in seconds. The value can be obtained only after the video is loaded or after the play event occurs. |
getVolume | N/A | Obtains the current volume. The return value is a real number ranging from 0 to 1. This method does not take effect on iOS terminals and specific Android terminals. |
setVolume | N/A | Sets the volume. The volume value is a real number ranging from 0 to 1. This method does not take effect on iOS terminals and specific Android terminals. |
loadByUrl | url and time | Obtains the URL for video playback. The value of the time parameter is optional and the unit of the time parameter is seconds. Only switching between videos of the same format, such as MP4, FLV, or M3U8, is supported. Switching between live Real-Time Messaging Protocol (RTMP) streams is not supported. |
replayByVidAndPlayAuth | vid: the video ID. playauth: the playback credential. | Only HTML5 players are supported. Switching between videos of different formats is
not supported. Switching between live RTMP streams is not supported.
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 users. Parameters in sequence are vid, accId, accSecret, stsToken, authInfo, and domainRegion. | Only HTML5 players are supported. Switching between videos of different formats is not supported. Switching between RTMP live streams is not supported. |
setPlayerSize | w and h | Sets the size of the player. Valid values:
|
setSpeed | speed | Allows users to manually set the playback speed. Playback speed control is supported only by HTML5 players. This method may not take effect for mobile platforms, such as WeChat for Android. By default, the user interface (UI) of playback speed control is enabled. |
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 | N/A | Enables the full-screen mode of the player. This method is supported only by HTML5 players. |
fullscreenService.cancelFullScreen | N/A | Exits the full-screen mode of a player. This method does not take effect on iOS terminals. This method is supported only by HTML5 players. |
fullscreenService.getIsFullScreen | N/A | Obtains the full screen status of the player. This method is supported only by HTML5 players. |
getStatus | N/A | Obtains the player status. Valid values:
|
setRotate | rotate: the rotation angle. | Sets the rotation angle. A positive value indicates clockwise rotation, whereas a negative value indicates anticlockwise rotation. Example: setRotate(90). For more information, see Rotation and mirroring. |
getRotate | N/A | Obtains the rotation angle. For more information, see Rotation and mirroring. |
setImage | image: the mirroring mode. | Sets the mirroring mode. Valid values:
|
dispose | N/A | Destroys a player. |
setCover | cover: the thumbnail URL. | Sets the thumbnail URL. |
setProgressMarkers | marker: the marker dataset. | Sets markers. |
setPreviewTime | time: the preview duration. | Set the preview duration, in seconds. For more information, see the Preview (URL) component on the Aliplayer website. |
getPreviewTime | N/A | Obtains the preview duration. |
isPreview | N/A | Specifies whether to enable the preview feature. |
Player events
Event | Description |
---|---|
ready | The event that is invoked when the video initialization button of the player is rendered.
Initial setting of the UI must be triggered after this event to prevent the UI from
being overwritten during initialization.
Note The methods that are provided by a player can be called only after this event occurs.
|
play | The event that is invoked when a paused video is played again. |
pause | The event that is invoked when a video is paused. |
canplay | The event that is invoked when an audio or video file is ready for playback. This event can be invoked many times and is supported only by HTML5 players. |
playing | The event that is invoked during playback. This event can be invoked many times. |
ended | The event that is invoked at the end of the current video. |
liveStreamStop | The event that is invoked when live streams are interrupted. For the playback of M3U8,
FLV, and RTMP videos, this event is invoked when the player fails to obtain data after
five consecutive retries. This event indicates that live streams are interrupted or
the video needs to be loaded again.
Note If the live streams of M3U8, FLV, and RTMP videos are interrupted or an error occurs,
the player automatically retries five times. You do not need to set the retry event
for the player.
|
onM3u8Retry | The retry event that is invoked when M3U8 live streams are interrupted. This event is invoked only once when streaming is interrupted. |
hideBar | The event to automatically hide the control bar. |
showBar | The event to automatically display the control bar. |
waiting | The data caching event. |
timeupdate | The event that is invoked when the playback position changes. This event is supported only by HTML5 players. You can obtain the current playback time by using the getCurrentTime method. |
snapshoted | The event that is invoked when a snapshot is captured. |
requestFullScreen | The event to enable the full-screen mode. This event is supported only by HTML5 players. |
cancelFullScreen | The event to exit the full-screen mode. This event is not invoked on iOS terminals. It is supported only by HTML5 players. |
error | The error event. |
startSeek | The event that is invoked when seeking starts. The return value is the start time of seeking. |
completeSeek | The event that is invoked when seeking is complete. The return value is the end time of seeking. |
resolutionChange | The event that is invoked when the resolution is switched during live streaming. |
seiFrame | The event that is invoked when Supplemental Enhancement Information (SEI) is received for HLS or FLV-based playback. |
Event subscription
- You can subscribe to an event by using the on method of a player instance. The following
code provides an example:
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. The
following code provides an example:
player.off('ready',handleReady);
Error code
Code | Description |
---|---|
4001 | The error message returned because the parameter is invalid. |
4002 | The error message returned because the playAuth expired. |
4003 | The error message returned because the streaming URL is invalid. |
4004 | The error message returned because the streaming URL does not exist. |
4005 | The error message returned because an error has occurred when the player starts to download data. Check whether the network or the streaming URL is available. |
4006 | The error message returned because an error has occurred when the player starts 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 whether the network or the streaming URL is available. |
4009 | The error message returned because a data request error has occurred. Check whether the network or the streaming URL is available. |
4010 | The error message returned because encrypted videos are not supported for playback. |
4011 | The error message returned because the format of the video to be played is not supported. |
4012 | The error message returned because a playAuth parsing error has occurred. |
4013 | The error message returned because a playback data decoding error has occurred. Check whether the browser supports the video format. |
4014 | The error message returned because the network is unavailable. |
4015 | The error message returned because retrieving data is aborted. |
4016 | The error message returned because data loading failed due to a network error. |
4017 | The error message returned because the returned streaming URL is empty. |
4100 | The error message returned because a signaling request error occurs. |
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 fails. |
4116 | The error message returned because the streaming URL uses an invalid protocol. |
4118 | The error message returned because the specified HTML element is not an audio stream or a video stream. |
4200 | The error message returned because the playback failed. |
4400 | The error message returned because an unknown error has occurred. Loading resources failed due to a server or network error or an unsupported format. |
4500 | The error message returned because a server request error has occurred. Check the VOD request on the network. |