All Products
Search
Document Center

ApsaraVideo VOD:Aliplayer API description

Last Updated:Jul 09, 2025

This document provides detailed descriptions of the properties, methods, and events supported by Aliplayer.

Note

If you encounter issues during use, you can refer to Web player FAQ or Troubleshooting playback issues.

Properties

When initializing Aliplayer, you can set various properties, including license authorization, playback resource information, player style information, and playback behavior.

Name

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 than 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.

  • URL-based playback supports multiple resolutions. You can specify the URLs of streams with different resolutions by using the source parameter. For more information, see Multi-resolution playback. Example:

    source:'{"HD":"address1","SD":"address2"}'

vid

String

The media ID for media transcoding.

playauth

String

The playback credential. For information about how to obtain a playback credential, see Obtain a playback credential for audio and video.

customVodServer

String

The custom VOD proxy domain (applicable to VidAuth playback method in version 2.32.0 and later). You need to deploy a dedicated request proxy service. When the default VOD domain (*.aliyuncs.com) is inaccessible, the player automatically falls back to your proxy service, effectively avoiding ISP hijacking risks and significantly improving playback stability and success rate.

playConfig

JSON

The custom parameter that you can specify for VidAuth or VidSts-based playback. This parameter is passed to the ApsaraVideo VOD API. For information about the custom fields and parameters that you can set, see Custom media playback settings PlayConfig. Example:

{"PlayDomain":"vod.test_domain","PreviewTime":"20","MtsHlsUriToken":"yqCD7******oVjslp5Q"}

authTimeout

Number

The validity period of the playback URL obtained when the video is played by using VidAuth or VidSts. Unit: seconds. Default value: 7200.

The validity period must be longer than the actual duration of the video. Otherwise, the playback URL expires before the playback is complete.

height

String

The height of the player. Valid values:

  • 100%

  • 100px

width

String

The width of the player. Valid values:

  • 100%

  • 100px

autoSize

Boolean | String

Specifies whether to use the automatic scaling feature by configuring the height and width parameter.

For example, if you configure width: '500px', autoSize: 'height', the width of your video is 500 pixels and the height of the video is scaled based on the aspect ratio of the source video.

If you configure height: '500px', autoSize: 'width', the height of your video is 500 pixels and the width of the video is scaled based on the aspect ratio of the source video

Note: autoSize: true is equivalent to autoSize: 'height', which means that the height is automatically adjusted by default.

videoWidth

String

The video width. For more information, see Set the display mode.

videoHeight

String

The video height. For more information, see Set the display mode.

preload

Boolean

Specifies whether to enable automatic loading for the player.

cover

String

The default thumbnail of the player. Enter a valid image URL. This parameter takes effect only when the autoplay parameter is set to false.

isLive

Boolean

Specifies whether the playback is live streaming. If the playback is live streaming, you are not allowed to drag the progress bar. Default value: false. If you want to play a live stream, set this parameter to true.

autoplay

Boolean

Specifies whether to enable autoplay. This parameter does not take effect for mobile devices. Valid values:

  • true: enables autoplay.

  • false (default): disables autoplay.

Note

Due to browser restrictions, ApsaraVideo Player SDK for Web may fail to automatically play videos. For more information, see Advanced features.

autoplayPolicy

Object

Specifies whether to enable adaptive mute autoplay. This parameter takes effect only when autoplay is set to true. Examples:

autoplayPolicy: {
  fallbackToMute: true, // Specifies whether to play the video in the mute mode when audio failed to be played during autoplay. Default value: false.
  showUnmuteBtn: true, // Specifies whether to display the large mute button in the middle of the view when videos are being automatically played in the mute mode. Default value: true.
}
Note
  • The mutedAutoplay event is triggered when mute autoplay succeeds.

  • When autoplay is enabled (autoplay is set to true) and adaptive mute autoplay is enabled (autoplayPolicy.fallbackToMute is set to true), the player first attempts to play the video with audio. If the attempt fails, the player attempts to play the video in the mute mode. Autoplay may fail even after the player tries to play the video in the mute mode.

rePlay

Boolean

Specifies whether to enable automatic loop playback.

useH5Prism

Boolean

Specifies that the HTML5 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 skin image. We recommend that you do not modify this parameter. If you want to modify this parameter, see Set the player skin.

skinLayout

Array | Boolean

The layout of the components. If you do not set this parameter, the default layout is used for components. false indicates that all feature components are hidden. For more information, see Configure the skinLayout property.

skinLayoutIgnore

Array

The UI component that you want to hide. For information about component names, see Description of VOD component parameters. Examples:

skinLayoutIgnore: [
  'bigPlayButton', // Hide the big playback button
  'controlBar.fullScreenButton' // Hide the full screen button on the control bar. You can use the dot operator to select the subcomponent.
]
Note

The skinLayoutIgnore configuration takes precedence over the skinLayout configuration.

controlBarVisibility

String

Specifies how to display the control bar. Valid values:

  • click: The control bar is displayed when you click the player area.

  • hover (default): The control bar is displayed when you move the pointer over the player area.

  • always: The control bar is always displayed.

  • never: The entire control bar is hidden.

showBarTime

Number

The length of time during which the control bar is automatically hidden, in milliseconds.

enableSystemMenu

Boolean

Specifies whether to allow the system right-click menu to be displayed. Default value: false.

format

String

The streaming URL format. Valid values:

  • mp4

  • hls or m3u8

  • flv

  • mp3

By default, this field is empty.

mediaType

String

Specifies whether to return audio or video. This parameter is supported only for playback based on VID. Default value: video. Valid values:

  • video: video

  • audio: video formats that contain only audio, such as MP4 audio

qualitySort

String

The sorting method. This parameter is supported only for playback based on VID and PlayAuth. Valid values:

  • desc: sorts in descending order (from high to low).

  • asc: sorts in ascending order (from low to high).

Default value: asc.

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. Valid values:

  • FD (fluent)

  • LD (low definition)

  • SD (standard definition)

  • HD (high definition)

  • OD (original quality)

  • 2K (2K)

  • 4K (4K)

defaultDefinition

String

The default video resolution. The value is the resolution of the stream corresponding to the VID. Valid values:

  • FD (fluent)

  • LD (low definition)

  • SD (standard definition)

  • HD (high definition)

  • OD (original quality)

  • 2K (2K)

  • 4K (4K)

autoPlayDelay

Number

The playback delay, in seconds.

language

String

The language. 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 information about custom values, see JSON structure.

snapshotWatermark

Object

The snapshot watermark in HTML5.

useHlsPluginForSafari

Boolean

Specifies whether to enable the HLS plug-in for playback in Safari. This parameter is not supported for Safari 11. Valid values:

  • true: enables the HLS plug-in.

  • false (default): disables the HLS plug-in.

enableStashBufferForFlv

Boolean

Specifies whether to enable buffering when FLV videos are played in the HTML5 player. This parameter takes effect only for live streaming. Valid values:

  • true (default): enables buffering.

  • false: disables buffering.

stashInitialSizeForFlv

Number

The initial cache size for FLV playback in HTML5. 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 to display a message prompting users to switch to a lower resolution. The unit is seconds. Default value: 20.

waitingTimeout

Number

The maximum buffer duration, in seconds. After the specified duration, an error message appears. Default value: 60.

diagnosisButtonVisible

Boolean

Specifies whether to display the detection button. Valid values:

  • true (default): displays the button.

  • false: does not display the button.

disableSeek

Boolean

Specifies whether to disable the seeking feature of the progress bar. Valid values:

  • true: disables the seeking feature.

  • false (default): does not disable the seeking feature.

encryptType

Number

Specifies whether to play encrypted videos in Alibaba Cloud (private encryption). Default value: 0. Valid values:

  • 0: plays unencrypted videos.

  • 1: plays privately encrypted videos.

Note
  • Private encryption uses the VID + PlayAuth method for playback.

  • Standard encryption for the web uses URL-based playback. For more information, see Play encrypted videos.

progressMarkers

Array

The array of markers on the progress bar. For more information, see Progress bar markers.

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. Valid values:

  • true: enables frame synchronization.

  • false (default): disables frame synchronization.

Note

This parameter is supported only in ApsaraVideo Player SDK for Web V2.21.0 or earlier. If you want to enable frame synchronization for HLS-based live streaming in V2.21.0 or later, see the hlsOption.maxLiveSyncPlaybackRate parameter.

chasingFirstParagraph

Number

The latency after which frame synchronization of phase 1 is enabled. Unit: seconds. Default value: 20.

Note

This parameter is supported only in ApsaraVideo Player SDK for Web V2.21.0 or earlier. If you want to enable frame synchronization for HLS-based live streaming in V2.21.0 or later, see the hlsOption.maxLiveSyncPlaybackRate parameter.

chasingSecondParagraph

Number

The latency after which frame synchronization of phase 2 is enabled, in seconds. The default value is 40.

Note

This parameter is supported only in ApsaraVideo Player SDK for Web V2.21.0 or earlier. If you want to enable frame synchronization for HLS-based live streaming in V2.21.0 or later, see the hlsOption.maxLiveSyncPlaybackRate parameter.

chasingFirstSpeed

Number

The playback speed when frame synchronization of phase 1 is enabled. Default value: 1.1.

Note

This parameter is supported only in ApsaraVideo Player SDK for Web V2.21.0 or earlier. If you want to enable frame synchronization for HLS-based live streaming in V2.21.0 or later, see the hlsOption.maxLiveSyncPlaybackRate parameter.

chasingSecondSpeed

Number

The playback speed when frame synchronization of phase 2 is enabled. Default value: 1.2.

Note

This parameter is supported only in ApsaraVideo Player SDK for Web V2.21.0 or earlier. If you want to enable frame synchronization for HLS-based live streaming in V2.21.0 or later, see the hlsOption.maxLiveSyncPlaybackRate parameter.

hlsOption.maxLiveSyncPlaybackRate

Number

The playback speed when frame synchronization is enabled for HLS-based live streaming. Default value: 1, which specifies that frame synchronization is not enabled.

  • Sample code:

    hlsOption: {
      maxLiveSyncPlaybackRate: 1.5, // Configure the playback speed when frame synchronization is enabled.
      liveSyncDurationCount: 3 // Set the maximum number of delayed segments allowed. For example, you can set liveSyncDurationCount to 3.
    }
  • Example meaning: When the live streaming latency is greater than the duration of three segments, the player plays the video at 1.5 times the normal speed to catch up to three segments (considering that the player needs a certain buffer to cope with network changes, please be cautious when modifying the value of liveSyncDurationCount, as a value that is too small may cause stuttering).

Note

This parameter is supported only in ApsaraVideo Player SDK for Web V2.21.0 or later.

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: enables shortcut keys.

  • false: disables shortcut keys.

Default value: false.

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 time range for the fast forward and rewind operations. Unit: seconds. Default value: 10.

rtsFallback

Boolean

Specifies whether to enable the RTS playback degradation feature. After you enable this feature, the system automatically plays the stream over a degraded protocol such as HTTP Live Streaming (HLS) or HTTP Flash Video (HTTP-FLV) when your browser does not support RTC or stream pulling over RTS fails. FLV-based playback has a higher priority because it imposes lower latency than HLS-based playback. HLS-based playback is used when your browser does not support RTC or FLV.

This feature is enabled by default. To disable this feature, specify false for this parameter.

rtsFallbackType

String

The alternative RTS URL, such as a playback URL in the HLS or FLV format. By default, this parameter is left empty. In this case, the default policy is used and the system tries to play the stream over FLV first. If your browser does not support FLV, the system plays the stream over HLS.

rtsFallbackSource

String

We recommend that you use the default playback degradation policy. If you want to pull the stream from a specific URL, specify this parameter.

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 saves 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:

textTracks: [
  { kind: 'subtitles', label: 'Chinese', src: 'Subtitle URL', srclang: 'zh-CN', default: true },
	{ kind: 'subtitles', label: 'English (US)', src: 'Subtitle URL', srclang: 'en-US' }
],

The following items describe the fields:

  • 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.

  • default: specifies whether to display subtitles by default. Valid values: true and false. This parameter is supported only in ApsaraVideo Player SDK V2.15.7 or later.

Note
  • This parameter is supported for ApsaraVideo Player SDK for Web V2.12.0 and later.

  • WebVTT external subtitles are not supported in the following browsers:

    • IE

    • QQ Browser, OPPO Browser, and the system browser of OnePlus

    • Other browsers that hijack the video tag

  • For detailed information about subtitle attributes, see HTML specification.

  • For more information about advanced subtitle settings, see External subtitles.

ratio

Number

The fixed aspect ratio at which the player is resized. For example, if the aspect ratio of a video is 16:9, you can set the player parameters to width: "100%", ratio: 16/9. This way, the player maintains the same aspect ratio as the video content and automatically scales proportionally as the page is resized.

extLanguageTexts

Object

ApsaraVideo Player SDK has a set of built-in UI. You can specify this parameter to change the UI content. For example, to change the display text for resolution: HD is displayed as High Definition by default, but you can change it to display as 1080p using the following method:

extLanguageTexts: {
    'zh-cn': {
      'HD': "1080p"
    }
}

speedLevels

Array

The custom playback speed. key specifies the speed and text specifies the UI content. If you leave this parameter empty, the default settings are used. Example:

speedLevels: [
  {"key": 0.25, "text": "0.25"},
  {"key": 0.5, "text": "0.5"},
  {"key": 1, "text": "Original"},
  {"key": 1.25, "text": "1.25"},
  {"key": 1.5, "text": "1.5"},
  {"key": 2,"text": "2"}
]

logo

Array

The custom logo image. Example:

    logo: [{
      width: 30,
      position: 'bottom-right',
      origin: 'content',
      src: 'a.png'
    },
    {
      width: 20,
      position: 'bottom-right',
      offsetY: -20,
      origin: 'content',
      src: 'b.png'
    }]

The following items describe the fields:

  • src: The URL of the logo image.

  • origin: The object reference. Valid values:

    • box: player

    • content: video content

  • width/height: The width and height of the logo image in percentage. If you specify either the width or the height, the other parameter is specified based on the aspect ratio of the source image.

  • position: The position of the logo image relative to the object reference. Valid values:

    • top-left

    • top-right

    • bottom-left: bottom left

    • bottom-right

  • offsetX/offsetY: The offset of the logo image relative to the object reference in percentage.

license

Object

If you want to use value-added features such as playback quality monitoring, single-point tracking, and playback of H.265/H.266 encoded video streams, please first fill out the Web Player SDK Value-added Service Application Form to apply for a License authorization, and then integrate the License as follows:

// domian is the domain name you filled in when applying for License authorization
// Set key to the key file of the license.
license: {
    domain: "example.com",
    key: "example-key"
  }

mute

Boolean

Specifies whether to play videos in the mute mode. If autoplay is disabled in the browser, configure this parameter to mute autoplay. For more information, see Advanced features.

clickPause

Boolean

Specifies whether to pause or play the video when you click on the video image.

disablePip

Boolean

Specifies whether to hide the built-in Picture-in-Picture (PiP) button on browsers.

Note
  • This parameter is supported only in ApsaraVideo Player SDK for Web V2.20.0 or later.

  • You can hide the PiP button only on Firefox V116 or later.

env

String

Specifies whether to upload the event tracking data of the player to data centers in the Chinese mainland. This is the default setting. If you have compliance requirements for data outside the Chinese mainland, configure env: 'SEA' to upload your data to the Singapore region.

watchStartTime

Number

The point in time at which a video clip starts to be played when the watchEndTime parameter is not used.

If the watchEndTime parameter is used at the same time, the range playback feature is enabled. You can play the video clip and drag the progress bar only within the time range specified by the watchStartTime and watchEndTime parameters.

Unit: seconds

watchEndTime

Number

This parameter is used with the watchStartTime parameter to enable the range playback feature. You can play the video clip and drag the progress bar only within the time range specified by the watchStartTime and watchEndTime parameters.

If the value of this parameter is smaller than the value of the watchStartTime parameter, the watchStartTime parameter becomes invalid.

Unit: seconds

start

Number

This parameter is used with the end parameter to cut a portion of a video clip as a separate video clip. For example, if the length of the original video clip is 60 seconds and you set the start parameter to 10 and the end parameter to 30, the length of the new video clip is 20 seconds and the playback starts from the 10th second of the original video clip.

end

Number

This parameter is used with the start parameter to cut a portion of a video clip as a separate video clip. For example, if the length of the original video clip is 60 seconds and you set the start parameter to 10 and the end parameter to 30, the length of the new video clip is 20 seconds and the playback starts from the 10th second of the original video clip.

dbClickFullscreen

Boolean

Specifies whether to enable double-click full screen. This feature is enabled by default.

longPressFastForward

Boolean

Long press speed feature (supported only on mobile devices). Valid values:

  • true (default): enabled.

  • false: disabled.

dbClickSkip

Boolean

Double-click the left area to rewind and double-click the right area to fast forward (supported only on mobile devices). Valid values:

  • true (default): enabled.

  • false: disabled.

Methods

Methods provided by a player can be called only after the ready event is complete. You can call methods in the callback function of the constructor that is used to create a player. Example:

// Method 1:
var player = new Aliplayer({}, function (player) {
  player.play();
});

// Method 2:
var player = new Aliplayer({});
function handleReady(player) {
  player.play();
};
player.on('ready', handleReady);

The following methods can be called by an Aliplayer instance:

play()

Plays a video.

Function definition

() => Player

pause()

Pauses a video.

(showPlayButton?: boolean) => Player

Parameters

Name

Parameter type

Required

Description

showPlayButton

Boolean

No

Specifies whether to display the playback button.

replay()

Replays a video.

Function definition

() => Player

seek()

Seeks to the video image at a specific point in time to start the playback.

Function definition

(time: number) => Player 

Parameters

Name

Parameter type

Required

Description

time

number

Yes

The point in time to which you want to jump. Unit: seconds.

dispose()

Destroys a player.

Function definition

() => void

getCurrentTime()

Obtains the current playback time, in seconds.

Function definition

() => number

getDuration()

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.

Function definition

() => number

getVolume()

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.

Function definition

() => number | undefined

setVolume()

Sets the volume.

Function definition

(volume: number) => void

Parameters

Name

Parameter type

Required

Description

volume

number

Yes

vol is a real number ranging from 0 To 1. This method does not take effect on iOS devices and specific Android devices.

mute()

Sets the player to mute mode.

Function definition

(quiet?: boolean) => Player

Parameters

Name

Parameter type

Required

Description

quiet

boolean

No

Specifies whether to hide the text prompt in the lower-left corner when muted.

unMute()

Unmutes the player.

Function definition

(quiet?: boolean) => Player

Parameters

Name

Parameter type

Required

Description

quiet

boolean

No

Specifies whether to hide the text prompt in the lower-left corner when unmuted.

getPlayTime()

Obtains the actual playback duration, which excludes the paused duration. If the video is played at a changed speed, the actual duration of the played video is counted. Unit: seconds.

Function definition

() => number

loadByUrl()

Switches videos. You can switch between video streams in the same format. The MP4, FLV, and HLS formats are supported. If you want to switch between different formats, you need to destroy the instance and create one.

Function definition

(url: string, seconds?: number, autoPlay?: boolean) => void

Parameters

Name

Parameter type

Required

Description

url

string

Yes

The URL of the video that you want to switch.

seconds

number

No

The starting position after the switch.

autoPlay

boolean

No

Specifies whether to enable autoplay after the switch.

replayByVidAndPlayAuth()

Switches between videos of the same format in ApsaraVideo VOD.

Function definition

(vid: string, playauth: string) => void

Parameters

Name

Parameter type

Required

Description

vid

string

Yes

The ID of the source file.

playauth

string

Yes

The playback credential.

replayByVidAndAuthInfo()

Switches between videos of the same format in Media Processing (MPS).

Function definition

(vid: string, accId: string, accSecret: string, stsToken: string, authInfo: string, domainRegion: string) => void

For more information, see MPS playback.

replayByMediaAuth()

Switches between videos of the same format in General Media Services.

Function definition

(mediaAuth: string) => void

Parameters

Name

Parameter type

Required

Description

mediaAuth

string

Yes

The playback credential.

setPlayerSize()

Sets the player size.

Function definition

(width: string, height: string) => void

Parameters

Name

Parameter type

Required

Description

width

string

Yes

Sets the player sizer. Valid values:

  • 400px

  • 60%

height

string

Yes

setSpeed()

Sets the playback speed. This method may not take effect for apps on mobile devices, such as WeChat for Android. By default, the UI for playback speed control is enabled.

Function definition

(speed: number) => void

Parameters

Name

Parameter type

Required

Description

speed

number

Yes

Supports 0.5 to 2 times speed playback.

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.

  • You can call the hack method to disable playback speed control by overwriting the CSS style:

    .prism-setting-speed {
       display: none !important;
     }

setTraceId()

Passes in a public tracking point for log tracing.

Function definition

(traceId: string) => void

Parameters

Name

Parameter type

Required

Description

traceId

string

Yes

The unique identifier.

Note

This method is supported for ApsaraVideo Player SDK for Web V2.10.0 and later.

setSanpshotProperties()

Sets the parameters for snapshots.

Function definition

(width: number, height: number, rate: number) => void

Parameters

Name

Parameter type

Required

Description

width

number

Yes

The unit of the height and width is pixel. The value of the rate parameter is a number ranging from 0 and 1. The default value is 1. For more information about video snapshots, see Video snapshots.

height

number

Yes

rate

number

Yes

fullscreenService.requestFullScreen()

Sets full screen in the player.

Function definition

() => Player

fullscreenService.cancelFullScreen()

Exits full-screen mode. This method does not take effect on iOS devices.

Function definition

() => Player

fullscreenService.getIsFullScreen()

Obtains the full screen status of the player.

Function definition

() => boolean

getStatus()

Obtains the player status. The value is of the string type. Valid values:

  • init: initialization.

  • ready: ready.

  • loading: loading.

  • play: play.

  • pause: pause.

  • playing: playing.

  • waiting: waiting for buffering.

  • error: error.

  • ended: ended.

Function definition

() => string

liveShiftSerivce.setLiveTimeRange()

Sets the start time and end time of live streaming. This method can be called only for time shifting during live streaming.

Function definition

(start: string, end: string) => void

Parameters

Name

Parameter type

Required

Description

start

string

Yes

start: the start time of live streaming.

end

string

Yes

end: the end time of live streaming.

Example

player.liveShiftSerivce.setLiveTimeRange('2025/03/21 12:43:00', '2025/03/21 23:31:00')

setRotate()

Specifies the rotation angle in the player.

Function definition

(rotate: number) => void

Parameters

Name

Parameter type

Required

Description

rotate

number

Yes

A positive value specifies a clockwise rotation and a negative value specifies an anticlockwise rotation. Example: setRotate(90). For more information, see Set the display mode.

getRotate()

Obtains the rotation angle of the player.

Function definition

() => number

For more information, see Set the display mode.

setImage()

Sets the image.

Function definition

(type: string) => void

Parameters

Name

Parameter type

Required

Description

type

string

Yes

Valid values:

  • horizon: horizontal.

  • vertical: vertical.

Example: setImage('horizon'). For more information, see Set the display mode.

setCover()

Sets the thumbnail URL.

Function definition

(coverUrl: string) => void

Parameters

Name

Parameter type

Required

Description

coverUrl

string

Yes

The thumbnail URL.

setProgressMarkers()

Sets markers.

Function definition

(markers: Array<{ time: number, text: string }>) => void

Parameters

Name

Parameter type

Required

Description

markers

Array<markers>

Yes

marker: the marker dataset. This field is required.

marker.time: the time of the marker. This field is required.

marker.text: the text of the marker. This field is required.

For more information, see description of the progressMarkers parameter.

setPreviewTime()

Sets the preview duration.

Function definition

(time: number) => void

Parameters

Name

Parameter type

Required

Description

time

number

Yes

Unit: seconds. For more information, see Preview.

getPreviewTime()

Obtains the preview duration.

Function definition

() => number

isPreview()

Specifies whether to enable the preview feature.

Function definition

() => boolean

getCurrentPDT()

Obtains the ProgramDateTime value in real time for HLS videos.

Function definition

() => number | undefined

setTextTracks()

Sets WebVTT external subtitles.

Function definition

(textTracks: Array<{ kind: string, label: string, src: string, srclang: string }>) => void

Parameters

Name

Parameter type

Required

Description

textTracks

Array<object>

Yes

Example:

player.setTextTracks([ { kind: 'subtitles', label: 'Chinese', src: 'Subtitle URL', srclang: 'zh-CN' },{ kind: 'subtitles', label: 'English (US)', src: 'Subtitle URL', srclang: 'en-US' }])
Note

This method is supported for ApsaraVideo Player SDK for Web V2.12.0 and later.

setLogo()

Sets the custom logo image.

Function definition

(logoList: Array<{ width: number, position: string, origin: string, src: string }>) => void

Parameters

Name

Parameter type

Required

Description

logoList

Array<object>

Yes

Example:

player.setLogo([{
      width: 30,
      position: 'bottom-right',
      origin: 'content',
      src: 'a.jpg'
    },
    {
      width: 20,
      position: 'bottom-right',
      offsetY: -20,
      origin: 'content',
      src: 'b.jpg'
    }])

For more information about the fields, see the logo section in the Parameters table.

setWatchTime()

Dynamically updates the watchStartTime and watchEndTime parameters for the current video clip.

Function definition

(start: number, end: number) => void

Parameters

Name

Parameter type

Required

Description

start

string

Yes

start: the start time.

end

string

Yes

end: the end time.

setNextWatchTime()

Sets the watchStartTime and watchEndTime parameters for the next video clip. If you want to call the loadByUrl or replayByVidAndPlayAuth operation to switch a video clip whose playback range is different from that of the current video clip, you can call the setNextWatchTime operation to set the playback range of the next video clip.

Function definition

(start: number, end: number) => void

Parameters

Name

Parameter type

Required

Description

start

string

Yes

start: the start time.

end

string

Yes

end: the end time.

setStartEnd()

Dynamically updates the start and end parameters for the current video clip.

Function definition

(start: number, end: number) => void

Parameters

Name

Parameter type

Required

Description

start

string

Yes

start: the start time.

end

string

Yes

end: the end time.

setNextStartEnd()

Sets the start and end parameters for the next video clip. If you want to call the loadByUrl or replayByVidAndPlayAuth operation to switch a video clip whose playback range is different from that of the current video clip, you can call the setNextStartEnd operation to set the playback range of the next video clip.

Function definition

(start: number, end: number) => void

Parameters

Name

Parameter type

Required

Description

start

string

Yes

start: the start time.

end

string

Yes

end: the end time.

takeSnapshot()

Takes a snapshot. The returned base64-encoded file can be directly loaded by img.src. You can call the setSanpshotProperties operation to set the snapshot quality and the snapshotWatermark operation to set the snapshot watermark.

Note: You cannot use the snapshot feature in some mobile browsers that hijack the video tag, such as UC Browser and QQ Browser.

Function definition

() => { time: number, base64: string, binary: string, error: Error | null }

Return value

Name

Parameter type

Description

time

string

The point in time at which the snapshot is captured.

base64

string

The content of the screenshot is in the base64 format.

binary

string

The content of the screenshot is a binary string.

error

Error

The details of the screenshot is abnormal.

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 called when a paused video is played again.

pause

The event that is called 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 called during playback. This event can be called multiple times.

ended

The event that is called after the video playback is complete.

liveStreamStop

The event that is called 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 live streams are interrupted or the video needs to be loaded again.

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 called when an HLS stream is interrupted. This event is called only once for each live stream interruption.

hideBar

The event that is called to automatically hide the control bar.

showBar

The event that is called to automatically display the control bar.

waiting

The data caching event.

timeupdate

The event that is called when the playback position changes. You can obtain the current playback time by using the getCurrentTime method.

snapshoted

The event that is called when a snapshot is captured.

requestFullScreen

The event that is called to enable full-screen mode.

cancelFullScreen

The event to exit the full-screen mode. This event is not invoked on iOS terminals.

error

Fault event.

startSeek

When a drag operation starts, a parameter returns the time of the drag point.

completeSeek

When the drag operation is complete, a parameter returns the time of the drag point.

resolutionChange

The event that is called when the video resolution is changed during live streaming.

seiFrame

The event that is called when Supplemental Enhancement Information (SEI) message is received for HLS or FLV.

rtsFallback

This event is triggered when a degraded protocol is used for playback. The reason parameter indicates the reason for degradation, and the fallbackUrl parameter indicates the URL to which the playback is degraded.

settingSelected

The event that is triggered when playback settings such as the speed, definition, and subtitles are changed.

Note

If you want to configure the playback speed by using open source plug-ins, you need to write code and recompile the project because the settings of the player and open source plug-ins are not synchronized. You can define an event listener. If you want to use the settingSelected event of the player, you must remove the plug-in.

/**
 * 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. The traceId field in the data.paramData parameter in the printed log is the TraceId for stream pulling. The source field is the playback URL of the current RTS stream.

player.on('rtsTraceId', function(data) {
  console.log('[EVENT]rtsTraceId', data.paramData);
})

autoplay

This parameter is returned when autoplay succeeds or fails. If event.paramData is set to true, autoplay succeeds. If false is returned, autoplay fails and user interaction is required for playback.

mutedAutoplay

This event is triggered when mute autoplay succeeds after autoplayPolicy.fallbackToMute is set to true.

videoUnavailable

This event is triggered when black screen occurs during playback because the encoding format of the video is not supported. For example, this event is triggered when you play videos on a browser that does not support H.265 videos. In this case, only audio is played and the black screen occurs.

Subscribe to events

  • You can subscribe to an event by using the on method of a player instance. Example:

    function handleReady() {};
    player.on('ready', handleReady);
    // Some events are frequently triggered. You can call the player.one method to listen only once.
    player.one('canplay', () => {});
  • You can unsubscribe from an event by using the off method of a player instance. Example:

    player.off('ready',handleReady);