All Products
Search
Document Center

Attributes and methods

Last Updated: Sep 17, 2019

Player attributes

Name Type Description
id String The ID of the dom element of the player’s external container.
source String The video playback URL:
- A single URL.
- The default playback mode is VID and playAuth.
- Source-based playback enjoys the highest priority.
The player supports multiple resolutions of source:
source:’{“HD”:”address1”,”SD”:”address2”}’. For more information, see Multi-resolution streams.
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 Obtain the playAuth.
height String The height of the player. Its value can be a percentage or a number (in pixel), for example, 100% or 100px.
The value cannot be less than 397x297 for a Flash player in Google Chrome.
width String The width of the player. Its value can be a percentage or a number (in pixel), for example, 100% or 100px.
The value cannot be less than 397x297 for a Flash player in Google Chrome.
videoWidth String The width of the video. This attribute is supported only by HTML5. For more information, see Rotation and mirroring.
videoHeight String The height of the video. This attribute is supported only by HTML5. 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.
cover String The default thumbnail of the player. Enter a correct image URL.
This attribute takes effect only when the preload and autoplay attributes are set to false.
CORS needs to be enabled for the thumbnail when the video is played by Flash.
isLive Boolean Specifies whether the playback is live streaming. If it 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 platforms.
Safari 11 does not automatically enable autoplay. For more information, see How can I enable autoplay for Safari 11.
rePlay Boolean Specifies whether to enable automatic loop playback.
useH5Prism Boolean Specifies whether to use the HTML5 player for playback.
useFlashPrism Boolean Specifies whether to use the Flash player for playback.
playsinline Boolean Specifies whether to enable HTML5 embedded playback. This attribute does not take effect for some Android-based web browsers.
showBuffer Boolean Specifies whether to show a buffer icon during playback. The default value is true.
skinRes URL The skin image. Do not modify this attribute unless necessary. If you need to modify it, see
Customize skin.
skinLayout Array
Boolean The layout of components. If you do not set this attribute, the default layout is used for components.
If this attribute is set to false, all the function components are hidden. For more information, see Customize skin.
controlBarVisibility String The mode to display the control panel. The default value is hover.
Valid values: click, hover, and always.
showBarTime String The length of time during which the control bar is automatically hidden, in milliseconds.
waterMark URL pos
size
alpha Adds a watermark.
Parameters: url
pos size alpha (supported only by Flash)
Example: waterMark: “logo.jpg

TL
0.15 0.5”
- url: the watermark image, in .jpg or .png format.
- pos: the position of the watermark. Valid values: TL, TR, BL, and BR.
- size: the ratio of the watermark width to the player width. Value range: 0 to 1. Default value: 0.2.
- alpha: the transparency. Value range: 0 to 1. Default value: 1.
extraInfo String A JSON string used to customize interface information. Currently, it supports the following parameters:
1. liveRetry: 1
Indicates whether to retry to obtain data when live streams are interrupted.
2. fullTitle: Test page
Indicates that the video title is displayed when the video is played in full-screen mode (supported only by Flash).
3. m3u8BufferLength: 30
Indicates the time duration of buffered TS fragments during the playback of M3U8 videos, in seconds (supported only by Flash).
4. liveStartTime: 2016/08/17 12:00:00
Indicates the start time of live streaming. It is used to indicate that the live streaming has not started (supported only by Flash).
5. liveOverTime: 2016/08/17 14:00:00
Indicates the end time of live streaming. It is used to indicate that the live streaming is over (supported only by Flash).
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 parameter takes effect only for VID-based playback.
Valid values: MP4, M3U8, FLV, and MP3. This attribute is not set by default and supported only by HTML5.
mediaType String The media type of the returned content. This attribute is supported only by VID-based playback.
Valid values: video and audio. The default value is video.
The value is set to audio only when audio files are played, for example, audio files in MP4 format. This attribute is supported only by HTML5.
qualitySort String The sorting method. This attribute is supported only by playback based on the VID and playAuth. Valid values:
desc: indicates descending order, that is, from higher to lower resolutions.
asc: indicates ascending order, that is, from lower to higher resolutions.
The default value is asc. This attribute is supported only by HTML5.
definition String The displayed video resolution. Different resolutions are separated with commas, for example, FD,LD. The value is a subset of resolutions of the stream corresponding to the VID.
Valid values: FD (low definition), LD (standard definition), SD (high definition), HD (ultra high definition), OD (original quality), 2K, and 4K. This attribute is supported only by HTML5.
defaultDefinition String The default video resolution. The value is the resolution of the stream corresponding to the VID.
Valid values: FD (low definition), LD (standard definition), SD (high definition), HD (ultra high definition), OD (original quality), 2K, and 4K. This attribute is supported only by HTML5.
x5_type String Declares to use the immersive mode of the HTML5 player. Set it to ‘h5’ when you enable the immersive mode of the HTML5 player.
For more information, see Immersive mode.
x5_fullscreen Boolean Specifies whether to enter TBS full-screen mode during video playback. The default value is false.
If you need to enable background playback, set this attribute to true.
For more information, see Immersive mode.
x5_video_position String The position of a video player on the screen. The default value is center.
Valid values: top and center.
For more information, see Immersive mode.
x5_orientation String The orientation of the video played by TBS. Valid values:
landscape
portrait
For more information, see Immersive mode.
x5LandscapeAsFullScreen String Specifies whether TBS plays the video in landscape mode during full-screen playback. The default value is true.
autoPlayDelay Number The playback delay, in seconds.
For more information, see Playback delay.
autoPlayDelayDisplayText String The text notifying users of the playback delay.
For more information, see Playback delay.
language String The language used by the player. The default value is zh-cn.
If this attribute is not set, the language of the web browser applies.
Valid values: zh-cn, en-us, and other values.
languageTexts JSON The JSON structure of the custom player language text. The key value must correspond to the value of the language attribute.
For example, {jp:{Play:”Play”}}.
For more information about custom values, see JSON structure.
snapshot Boolean Specifies whether to enable the snapshot capture function in Flash.
snapshotWatermark Object The snapshot watermark in HTML5.
useHlsPluginForSafari Boolean Specifies whether to enable the HLS plug-in for playback in Safari, except Safari 11.
enableStashBufferForFlv Boolean Specifies whether to enable playback caching during FLV video playback in HTML5. This attribute takes effect only for live streaming.
stashInitialSizeForFlv Number The initial cache size for FLV video playback in HTML5. This attribute takes effect only for live streaming.
loadDataTimeout Number The buffer duration required to display a message prompting users to switch to a lower resolution, in seconds. Default value: 20.
waitingTimeout Number The maximum buffer duration, in seconds. Default value: 60.
liveStartTime String The start time of live streaming, in the format of yyyy/MM/dd HH:mm:ss. For example, 2018/01/04 12:00:00. This attribute is used by live streaming time shifting.
liveOverTime String The end time of live streaming, in the format of yyyy/MM/dd HH:mm:ss. For example, 2018/01/04 12:00:00. This attribute is used by live streaming time shifting.
liveTimeShiftUrl String The URL for querying available time shifting for live streaming. For more information, see Live streaming time shifting.
liveShiftSource String The HLS URL for FLV playback. For more information, see Live streaming time shifting.
recreatePlayer Function The method for creating a new player during the switching between FLV live streaming and HLS time shifting. For more information, see Live streaming time shifting.
diagnosisButtonVisible Boolean Specifies whether to display the diagnosis button. The default value is true.
disableSeek Boolean Specifies whether to disable the seeking function of the progress bar. The default value is false. This attribute is supported only by Flash.
encryptType Integer The encryption type. This attribute is set to 1 for VOD playback based on Alibaba Cloud Encryption. The default value is 0.
progressMarkers Array The content array of the marker on the progress bar. For more information, see Mark on the progress bar.
vodRetry Integer The number of retry times when VOD playback fails. Default value: 3.

Player methods

Operations must be used after the ready event or during callback in the player creation ready state. In HTML5, operations can be called by the callback method of the constructor used to create a player.

  1. player.on('ready',function(e) {
  2. player.play();
  3. });
  1. var player = new Aliplayer({},function(player) {
  2. player.play();
  3. });
Name Parameter Description
play Plays a video.
pause Pauses a video.
replay Replays a video.
seek time Seeks to the video image at the specific time point to start playing. The unit is seconds.
getCurrentTime Obtains the current playback time, in seconds.
getDuration Obtains the total duration of a video, in seconds. It can be obtained only after the video is loaded or after the play event.
getVolume Obtains the current volume. The return value is a real number ranging from 0 to 1.
This attribute does not take effect for iOS-based and some Android-based mobile phones.
setVolume Sets the volume. The value of vol is a real number ranging from 0 to 1. This attribute does not take effect for iOS-based and some Android-based mobile phones.
loadByUrl url, time Obtains the URL for video playback. The time is an optional value and its unit is seconds.
Currently, only switching between videos of the same format (MP4, FLV, or M3U8) is supported.
Switching of RTMP live streams is not supported.
replayByVidAndPlayAuth vid: the video ID.
playauth: the playback credential.
Currently, only the HTML5 player is supported.
Switching between videos of different formats is not supported.
Switching of RTMP live streams is not supported.
replayByVidAndAuthInfo This is available for ApsaraVideo for Media Processing (MPS) users only.
Parameters in sequence are vid, accId, accSecret, stsToken, authInfo, and domainRegion.
Currently, only the HTML5 player is supported.
Switching between videos of different formats is not supported.
Switching of RTMP live streams is not supported.
setPlayerSize w, h Sets the size of the player. Both the w and h parameters can be set to 400px or 60%.
The value cannot be less than 397x297 for a Flash player in Google Chrome.
setSpeed speed Manually sets the playback speed. Playback speed control is only supported by the HTML5 player.
It may not take effect for mobile platforms, such as Android-based WeChat.
By default, the UI of playback speed control is enabled.
If the skinLayout attribute is customized, you need to add speedButton to the array.
{name:”speedButton”,align:”tr”,x:10,y:23}
setSanpshotProperties width: the width of the snapshot.
height: the height of the snapshot.
rate: the quality of the snapshot.
Sets parameters for snapshots.
fullscreenService.requestFullScreen Enables the full-screen mode of a player.
fullscreenService.cancelFullScreen Exits full-screen mode of a player. This method does not take effect for iOS.
fullscreenService.getIsFullScreen Obtains the full screen status of a player.
getStatus Obtains the player status, including the following values:
‘init’
‘ready’
‘loading’
‘play’
‘pause’
‘playing’
‘waiting’
‘error’
‘ended’
liveShiftSerivce.setLiveTimeRange Start time
End time
Sets the start time and end time of live streaming. This method can be called only for live streaming time shifting.
For example, player.liveShiftSerivce.setLiveTimeRange(“”, ‘2018/01/04 20:00:00’).
setRotate Sets the rotation angle. A positive value indicates clockwise rotation, whereas a negative value indicates anticlockwise rotation.
For example, setRotate(90). For more information, see Rotation and mirroring.
getRotate Obtains the rotation angle. For more information, see Rotation and mirroring.
setImage image: the mirroring type.
Valid values: horizon and vertical.
Sets the mirroring type. For example, setImage(‘horizon’). For more information, see Rotation and mirroring.
dispose Releases a player.
setCover cover: the thumbnail URL. Sets the thumbnail URL.
setProgressMarkers markers: the marker dataset. Sets markers.
setPreviewTime time: the preview duration. Sets the preview duration, in seconds. For more information, see Preview.
getPreviewTime Obtains the preview duration.
isPreview Specifies whether to enable the preview feature.

Player events

Name Description
ready The event indicating that the video initialization button of the player has been rendered.
Initial setting of the UI must be triggered after this event to prevent the UI from being overwritten by initialization.
The method provided by a player can be called only after this event has occurred.
play The event fired when a paused video is played again.
pause The event fired when a video is paused.
canplay The event fired when an audio or a video is ready for playback. It can be fired many times and is supported only by the HTML5 player.
playing The event fired during playback. It can be fired many times.
ended The event fired at the end of the current video.
liveStreamStop The event fired when live streams are interrupted.
For the playback of M3U8, FLV, and RTMP videos, it is fired when the player fails to obtain data after five consecutive retries.
It indicates that live streams are interrupted or the video needs to be loaded again.
Note: For M3U8 videos, the player keeps retrying automatically. You do not need to set the retry event for the player.
OnM3u8Retry The retry event when M3U8 streams are interrupted. It is fired only once when streaming is interrupted.
hideBar The event to hide the control bar automatically.
waiting The data caching event.
timeupdate The event fired when the playback position changes. It is only supported by the HTML5 player.
You can obtain the current playback time by using the getCurrentTime method.
snapshoted The event for obtaining the video time point of the snapshot.
requestFullScreen The event for entering the full-screen mode.
cancelFullScreen The event for exiting the full-screen mode. This event is not fired in iOS-based mobile phones.
error The error event.
startSeek The event indicating that seeking starts. The return value is the start time of seeking.
completeSeek The event indicating that seeking is complete. The return value is the end time of seeking.

Event subscription

You can subscribe to an event using the on method of a player instance.

  1. var handleReady = function(e)
  2. {
  3. console.log(e);
  4. }
  5. player.on('ready',handleReady);

You can cancel subscription to an event using the off method of a player instance.

  1. 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 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 times 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 (MEDIA_ERR_DECODE). 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 (MEDIA_ERR_ABORTED).
4016 The error message returned because data loading failed due to a network error (MEDIA_ERR_NETWORK).
4017 The error message returned because the returned streaming URL is empty.
4400 The error message returned because an unknown error has occurred (MEDIA_ERR_SRC_NOT_SUPPORTED). 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.