API operations

Parameter

Type

Description

id

String

The ID of the DOM element for the external container of the player.

source

String

The video playback URL.

vid

String

The media ID for media transcoding.

playauth

String

The video playback credential. For more information, see GetVideoPlayAuth.

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 more information about the supported fields, see PlayConfig: specifies the custom configurations for media playback. Sample code:

{"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 that if you configure autoSize: true, the system scales the video height based on the aspect ratio of the source video.

videoWidth

String

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

videoHeight

String

The height of the video. For more information, see Specify 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 autoplay 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. You must set this parameter to true for live streaming.

autoplay

Boolean

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

• true

• false (default)

autoplayPolicy

Object

Specifies whether to enable adaptive mute autoplay. This parameter takes effect only when you set autoplay to true. Sample code:

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

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 player skin image. We recommend that you do not change the value of this parameter unless it is necessary. For more information about how to change the player skin image, see Configure 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 attribute.

skinLayoutIgnore

Array

The UI component that you want to hide. For more information about components, see Property description. Sample code:

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

controlBarVisibility

String

Specifies how to display the control bar. Valid values:

• click: The control bar is displayed when you click on the playback section.

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

• always: The control panel is always displayed.

• never: The control panel is hidden.

showBarTime

Number

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

enableSystemMenu

Boolean

Specifies whether to display the shortcut menu upon a right click. The default value is false.

format

String

The streaming URL format. Valid values:

• mp4

• hls or m3u8

• flv

• mp3

By default, no data is returned.

mediaType

String

The media type of the returned content. This parameter is supported only by VID-based playback. The default value is video. Valid values:

• video: video files.

• audio: video files that contain only audio. For example, MP4 files.

qualitySort

String

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

• desc: descending order.

• asc: ascending order.

Default value: asc.

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: low definition

• LD: standard definition

• SD: high definition

• HD: ultra high definition

• OD: original quality

• 2K

• 4K

defaultDefinition

String

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

• FD: low definition

• LD: standard definition

• SD: high definition

• HD: ultra high definition

• OD: original quality

• 2K

• 4K

autoPlayDelay

Number

The playback delay, in seconds.

language

String

The language that is used by the player. The default value is 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, such as {jp:{Play:"Play"}}. For more information, see JSON format.

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

• false (default)

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)

• false

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)

• false

disableSeek

Boolean

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

• true

• false (default)

encryptType

Number

Specifies whether to play videos encrypted by using Alibaba Cloud proprietary cryptography. Default value: 0. Valid values:

• 0: does not play videos that are encrypted by using Alibaba Cloud proprietary cryptography.

• 1: plays videos encrypted by using Alibaba Cloud proprietary cryptography.

progressMarkers

Array

The content array of the marker on the progress bar. For more information, see Mark on the progress bar.

vodRetry

Number

The number of retries when VOD playback fails. Default value: 3.

liveRetry

Number

The number of retries when live stream playback fails. Default value: 5.

hlsFrameChasing

Boolean

Specifies whether to enable frame synchronization for HLS-based playback. Valid values:

• true

• false (default)

chasingFirstParagraph

Number

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

chasingSecondParagraph

Number

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

chasingFirstSpeed

Number

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

chasingSecondSpeed

Number

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

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

• In this case, when the latency of live streaming exceeds the duration of three segments, the player plays the stream at 1.5x to catch up to the current playback position. We recommend that you do not specify a small value for the liveSyncDurationCount parameter. Otherwise, stuttering may occur when the player fast forwards a stream.

flvFrameChasing

Boolean

Specifies whether to enable frame synchronization for FLV-based live streaming. Valid values:

• true

• false (default)

keyShortCuts

Boolean

Specifies whether to enable shortcut keys. Valid values:

• true

• false (default)

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.

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 (en-US)', src: 'Subtitle URL'', srclang: 'en-US' }
],

ratio

Number

The fixed aspect ratio at which the player is resized. For example, if the aspect ratio of the video is 16:9 and you specify width: "100%", ratio: 16/9, the aspect ratio of the player is the same as the video and can be proportionally resized based on the aspect ratio.

extLanguageTexts

Object

ApsaraVideo Player SDK has a set of built-in UI. You can specify this parameter to change the UI content. For example, HD is displayed for High Definition by default. You can change the resolution name from HD to 1080p. Sample code:

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

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

Specifies a custom logo image. Sample code:

    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-right

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

license

Object

To use value-added features such as playback quality monitoring, single-point tracing, and H.265 and H.266 video playback, you must submit a request on Yida to apply for a license. For more information, see Playback quality monitoring, Single-point tracing, and Play H.265 and H.266 videos. After a license is issued, integrate the license by using the following sample code:

// Set domain to the domain name that you specified when you apply for the license.
// 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 the video image.

disablePip

Boolean

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

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.

Event

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.

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.

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

The event that is called when a playback error occurs.

startSeek

The event that is triggered when seeking starts. The return value is the position in the video where seeking starts.

completeSeek

The event that is triggered when seeking ends. The return value is the position in the video where seeking ends.

resolutionChange

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

seiFrame

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

rtsFallback

This event is triggered when a degraded protocol is used for playback. reason indicates the degradation cause and fallbackUrl indicates the alternate URL.

settingSelected

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

/**
 * For example, the event is triggered when you change the playback speed to 1.25x. Sample code:
 * {name: 'Playback speed', type: 'speed', text: '1.25x', key: 1.25}
 */

rtsTraceId

The event that is triggered when an RTS stream is pulled. Listen for the event to obtain the TraceId. In the data.paramData parameter in the displayed log, 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);
})

autoplay

This event is triggered when autoplay succeeds or fails. If true is returned for the event.paramData parameter in the callback, the autoplay is successful. If false is returned for the event.paramData parameter in the callback, the autoplay failed. In this case, you need to manually trigger the playback.

mutedAutoplay

The event that is triggered when a video is automatically played in the mute mode. To automatically play videos in the mute mode, set autoplayPolicy.fallbackToMute to true.

videoUnavailable

The event that 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.