ApsaraVideo VOD:Aliplayer API reference

Name

Type

Description

id

String

The DOM element ID of the player's outer container.

source

String

When you use URL-based playback, use the source property to specify the video playback URL.

vid

String

The media ID from ApsaraVideo Media Processing.

playauth

String

The playback credential. To obtain a playback credential, see Obtain audio and video playback credentials.

customVodServer

String

A custom VOD proxy domain name. This property is available for VidAuth playback in versions 2.32.0 and later. You must deploy a dedicated request proxy service. If the default VOD domain name (*.aliyuncs.com) is inaccessible, the player automatically falls back to your proxy service. This helps prevent carrier hijacking and significantly improves playback stability and success rate.

playConfig

JSON

Custom setting field for Vid-based playback (VidAuth and VidSts). The value is passed through to the VOD API. For information about the supported custom fields and their parameters, see Custom media playback settings (PlayConfig). Example value:

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

authTimeout

Number

The validity period of the video playback URL obtained through Vid-based playback (VidAuth and VidSts). Unit: seconds. Default value: 7200.

Make sure this period is longer than the actual video duration to prevent the playback URL from expiring before playback is complete.

height

String

The player height. Valid values:

• 100%

• 100px

width

String

The player width. Valid values:

• 100%

• 100px

autoSize

Boolean | String

The player size automatically adapts to the video content. Valid values: 'height', 'width'.

For example, you can specify `width: '500px', autoSize: 'height'`. The player maintains a width of 500 px and automatically adjusts the height based on the video's aspect ratio.

Alternatively, you can specify `height: '500px', autoSize: 'width'`. The player maintains a height of 500 px and automatically adjusts the width based on the video's aspect ratio.

Note: `autoSize: true` is equivalent to `autoSize: 'height'`, which means the height is adaptive 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 the player automatically loads the video.

cover

String

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

isLive

Boolean

Specifies whether the content is a live stream. When playing a live stream, users are prevented from dragging the progress bar. The default value is false. Set this to true when you play a live stream.

autoplay

Boolean

Specifies whether the player plays the video automatically. The autoplay feature may not work on mobile devices. Valid values:

• true: Enables autoplay.

• false (default): Disables autoplay.

autoplayPolicy

Object

The adaptive muted autoplay policy. This property takes effect only when autoplay is set to true. Example configuration:

autoplayPolicy: {
  fallbackToMute: true, // Specifies whether to fall back to muted autoplay if autoplay with sound fails. Default: false.
  showUnmuteBtn: true, // Specifies whether to display a large unmute button in the center during muted autoplay. Default: true.
}

rePlay

Boolean

Specifies whether the player automatically loops the playback.

useH5Prism

Boolean

Specifies whether to use the H5 player.

playsinline

Boolean

Specifies whether to play the video inline in H5. This may not work in some Android browsers.

skinRes

Url

The skin image. We recommend that you do not modify this field. To, see Set the player skin.

skinLayout

Array | Boolean

The layout configuration of functional components. If you do not set this property, the default layout is used. A value of false hides all functional components. For more information, see Configure the skinLayout property.

skinLayoutIgnore

Array

The UI components to hide. For component names, see VOD component parameters. Example configuration:

skinLayoutIgnore: [
  'bigPlayButton', // Hide the large play button
  'controlBar.fullScreenButton' // Hide the full screen button on the control bar (use dot notation to select sub-components)
]

controlBarVisibility

String

The behavior of the control bar. Valid values:

• click: The control bar appears when a user clicks the player area.

• hover (default): The control bar appears when a user moves the pointer over the player area.

• always: The control bar is always visible.

• never: The entire control bar is hidden.

showBarTime

Number

The time in milliseconds before the control bar automatically hides.

enableSystemMenu

Boolean

Specifies whether to allow the system's right-click context menu to be displayed. The default value is false.

format

String

Specifies the format of the playback URL. Valid values:

• mp4

• hls or m3u8

• flv

• mp3

The default value is empty.

mediaType

String

Specifies whether to return audio or video. This is supported only for Vid-based playback. The default value is video. Valid values:

• video: Video.

• audio: For video formats that contain only audio, such as an MP4 audio file.

qualitySort

String

Specifies the sorting order. This is supported only for Vid+PlayAuth playback. Valid values:

• desc: Sorts in descending order (from largest to smallest).

• asc: Sorts in ascending order (from smallest to largest).

Default value: asc.

definition

String

The video definitions to display, separated by commas (,), for example, 'FD,LD'. This value is a subset of the definitions available for the `vid`. Valid values:

• FD (Low Definition)

• LD (Standard Definition)

• SD (High Definition)

• HD (Ultra High Definition)

• OD (Original Quality)

• 2K (2K)

• 4K (4K)

defaultDefinition

String

The default video definition. This value is one of the definitions available for the `vid`. Valid values:

• FD (Low Definition)

• LD (Standard Definition)

• SD (High Definition)

• HD (Ultra High Definition)

• OD (Original Quality)

• 2K (2K)

• 4K (4K)

autoPlayDelay

Number

The delayed playback time. Unit: seconds.

language

String

Internationalization. The default value is zh-cn. If not set, the browser's language is used. Valid values:

• zh-cn: Chinese.

• en-us: English.

languageTexts

JSON

A JSON object for custom internationalization text. The key must correspond to the value of the `language` property. Example: {jp:{Play:"Play"}}. For the JSON structure, see JSON structure.

snapshotWatermark

Object

Sets a watermark for screenshots in H5.

useHlsPluginForSafari

Boolean

Specifies whether to enable the HLS plugin for playback in Safari browsers, except for Safari 11. Valid values:

• true: Enable.

• false (default): Disable.

enableStashBufferForFlv

Boolean

When playing FLV streams in H5, specifies whether to enable the playback cache. This works only for live streaming. Valid values:

• true (default): Enable.

• false: Disable.

stashInitialSizeForFlv

Number

When playing FLV streams in H5, this sets the initial cache size. This works only for live streaming. The default value is 32 KB.

A smaller value can speed up the initial playback, but a value that is too small may cause stuttering after a short period of playback.

loadDataTimeout

Number

The buffering duration in seconds after which the user is prompted to switch to a lower definition. The default value is 20 seconds.

waitingTimeout

Number

The maximum buffering timeout period. If this time is exceeded, an error is prompted. Unit: seconds. The default value is 60 seconds.

diagnosisButtonVisible

Boolean

Specifies whether to display the diagnosis button. Valid values:

• true (default): Display the button.

• false: Do not display the button.

disableSeek

Boolean

Disables seeking on the progress bar. Valid values:

• true: Disable.

• false (default): Do not disable.

encryptType

Number

Specifies whether to play Alibaba Cloud-encrypted (private encryption) videos. The default value is 0. Valid values:

• 0: Play non-encrypted videos.

• 1: Play privately encrypted videos.

progressMarkers

Array

An array of content for progress bar markers. For more information, see Progress bar markers.

vodRetry

Number

The number of retry attempts for failed VOD playback. The default is 3.

liveRetry

Number

The number of retry attempts for failed live playback. The default is 5.

hlsFrameChasing

Boolean

In HLS live mode, specifies whether to enable frame synchronization. Valid values:

• true: Enable frame synchronization.

• false (default): Disable frame synchronization.

chasingFirstParagraph

Number

The first stage of frame synchronization. Unit: seconds. The default is 20 seconds.

chasingSecondParagraph

Number

The second stage of frame synchronization. Unit: seconds. The default is 40 seconds.

chasingFirstSpeed

Number

The playback speed for the first stage of frame synchronization. The default is 1.1×.

chasingSecondSpeed

Number

The playback speed for the second stage of frame synchronization. The default is 1.2×.

hlsOption.maxLiveSyncPlaybackRate

Number

In HLS live mode, sets the playback speed for frame synchronization. The default value is 1, which means frame synchronization is disabled.

• Example configuration:

  hlsOption: {
    maxLiveSyncPlaybackRate: 1.5, // Set the speed for frame synchronization
    liveSyncDurationCount: 3 // Set the number of delayed segments that triggers frame synchronization
  }

• Example meaning: When the live stream latency exceeds the duration of 3 segments, the player plays at 1.5× speed to catch up to a latency of 3 segments. (To ensure the player has enough buffer for network fluctuations, be cautious when modifying the liveSyncDurationCount value. A value that is too small may cause stuttering.)

flvFrameChasing

Boolean

In FLV live mode, specifies whether to enable frame synchronization. Valid values:

• true: Enable frame synchronization.

• false: Disable frame synchronization.

The default value is false.

keyShortCuts

Boolean

Specifies whether to enable keyboard shortcuts. Valid values:

• true: Enable keyboard shortcuts.

• false: Disable keyboard shortcuts.

The default value is false.

keyFastForwardStep

Number

The duration for fast forward and fast backward. Unit: seconds. The default is 10 seconds.

rtsFallback

Boolean

If the browser does not support RTS or RTS stream pulling fails, the player automatically attempts to fall back to FLV or HLS for playback. It prioritizes FLV due to lower latency. If the browser does not support FLV, it falls back to HLS.

This feature is enabled by default. To disable it, you can pass false.

rtsFallbackType

String

Specifies the protocol to fall back to from RTS. Valid values: HLS, FLV. If you do not set this parameter, the player automatically selects a protocol. It prioritizes the lower-latency FLV protocol. If the browser does not support FLV, it falls back to HLS.

rtsFallbackSource

String

We recommend using the player's default fallback policy. However, if you want to specify a fixed stream pulling URL for fallback, use this parameter.

traceId

String

The `traceId` is your unique user identifier. Pass the `traceId` to the public instrumentation service to track reported logs. By default, the web player SDK has log reporting enabled. Passing a `traceId` helps you identify users. If you do not pass a `traceId`, the web player SDK generates a UUID (a unique identifier generated by the player SDK) and stores it in the browser cache.

textTracks

Array

Sets external WebVTT captions. Example:

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

ratio

Number

Sets the player to scale at a fixed ratio. For example, if a video has a 16:9 aspect ratio, you can set the player parameters to width: "100%", ratio: 16/9. This keeps the player's aspect ratio consistent with the video content and allows it to scale proportionally as the page is resized.

extLanguageTexts

Object

The player SDK has a built-in set of UI text in Chinese and English. You can use this property to customize the display text for some UI elements. For example, to change the display text for a resolution: HD is displayed as High Definition by default. You can change the display text for HD to 1080p as follows.

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

speedLevels

Array

Sets a custom array for the speed level list. `key` represents the speed value, and `text` represents the UI text. If not passed, the default list is used. Example parameter values:

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

logo

Array

Sets custom logo images. Example:

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

Field descriptions:

• src: The logo image URL.

• origin: The reference object for positioning. Valid values:

  • box: The player

  • content: The video content

• width/height: The width and height of the logo as a percentage (calculated based on `origin`). If you specify only one dimension, the other is scaled proportionally based on the image's aspect ratio.

• position: The relative position of the logo, positioned relative to `origin`. Valid values:

  • top-left: Top left

  • top-right: Top right

  • bottom-left: Bottom left

  • bottom-right: Bottom right

• offsetX/offsetY: The offset from the `position`, as a percentage (%) (calculated based on `origin`).

license

Object

To use value-added services such as Playback Quality Monitoring (Legacy), Single-point Tracing, and playing H.265/H.266 encoded video streams, first fill out the Web Player SDK Value-added Service Application Form to apply for a license. Then, integrate the license as follows:

// domain is the domain name you provided when applying for the license.
// Key is the license key.
license: {
    domain: "example.com",
    key: "example-key"
  }

mute

Boolean

Sets whether to play the video on mute. You can configure this parameter for muted autoplay when the browser prohibits autoplay. For more information, see Advanced features.

clickPause

Boolean

Click the video area to pause or play.

disablePip

Boolean

Hides the browser's native Picture-in-Picture (PiP) button.

env

String

The player's instrumentation data is uploaded to the China data center by default. If you have data compliance requirements for regions outside China, pass the parameter env: 'SEA'. The data will be uploaded to the Singapore data center.

watchStartTime

Number

Used alone, it represents the start time of playback.

Used with `watchEndTime`, it enables range playback. Playback and seeking are restricted to the time range between the start and end times.

Unit: seconds

watchEndTime

Number

Used with `watchStartTime` to enable range playback. Playback and seeking are restricted to the time range between the start and end times.

If this parameter's value is less than `watchStartTime`, `watchStartTime` becomes invalid.

Unit: seconds

start

Number

Used with `end` to clip a part of the video and treat it as an independent video. For example, for a 60-second video, if you set `start:10` and `end:30`, the displayed video duration is 20 seconds, and playback starts from the 10-second mark of the original video.

end

Number

Used with `start` to clip a part of the video and treat it as an independent video. For example, for a 60-second video, if you set `start:10` and `end:30`, the displayed video duration is 20 seconds, and playback starts from the 10-second mark of the original video.

dbClickFullscreen

Boolean

Specifies whether to enable double-click for full screen. This is enabled by default on PCs.

longPressFastForward

Boolean

Long-press for fast forward (mobile only). Valid values:

• true (default): Enable.

• false: Disable.

dbClickSkip

Boolean

Double-click the left area to fast backward, double-click the right area to fast forward (mobile only). Valid values:

• true (default): Enable.

• false: Disable.

Name

Type

Required

Description

showPlayButton

Boolean

No

Specifies whether to show the play button.

Name

Type

Required

Description

time

number

Yes

The time to seek to. Unit: seconds.

Name

Type

Required

Description

volume

number

Yes

vol is a real number from 0 to 1. This may not work on iOS and some Android devices.

Name

Type

Required

Description

quiet

boolean

No

Specifies whether to hide the text tip in the lower-left corner when muting.

Name

Type

Required

Description

quiet

boolean

No

Specifies whether to hide the text tip in the lower-left corner when unmuting.

Name

Type

Required

Description

url

string

Yes

The URL of the video to switch to.

seconds

number

No

The start position after switching.

autoPlay

boolean

No

Specifies whether to autoplay after switching.

Name

Type

Required

Description

vid

string

Yes

The video ID.

playauth

string

Yes

The playback credential.

Name

Type

Required

Description

mediaAuth

string

Yes

The playback credential.

Name

Type

Required

Description

name

string

Yes

The name of the built-in component (e.g., `fullScreenButton`). See Configure the skinLayout property. Each component supports `hide()` and `show()` methods to control its visibility.

Name

Type

Required

Description

width

string

Yes

Sets the player size. Valid values:

• 400px

• 60%

height

string

Yes

Name

Type

Required

Description

speed

number

Yes

Supports playback speeds from 0.5× to 2×.

Name

Type

Required

Description

traceId

string

Yes

A unique identifier.

Name

Type

Required

Description

width

number

Yes

The unit of height and width is pixel. The value for screenshot quality is a number ranging from 0 to 1. The default value is 1. For more information about video screenshots, see Video Screenshot.

height

number

Yes

rate

number

Yes

Name

Type

Required

Description

start

string

Yes

start The start time of the live stream.

end

string

Yes

end The end time of the live stream.

Name

Type

Required

Description

rotate

number

Yes

A positive number indicates clockwise rotation, and a negative number indicates counter-clockwise rotation. Example: setRotate(90). For more information, see Set the display mode.

Name

Type

Required

Description

type

string

Yes

Valid values:

• horizon: Horizontal.

• vertical: Vertical.

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

Name

Type

Required

Description

coverUrl

string

Yes

The thumbnail URL.

Name

Type

Required

Description

markers

Array<markers>

Yes

markers: A collection of marker data (required).

marker.time: The time for the marker (required).

marker.text: The text for the marker (required).

For more information, see the progressMarkers parameter.

Name

Type

Required

Description

time

number

Yes

Unit: seconds. For more information, see Preview.

Name

Type

Required

Description

textTracks

Array<object>

Yes

Example:

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

Name

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 detailed descriptions of each field, see the `logo` property.

Name

Type

Required

Description

start

string

Yes

start start time.

end

string

Yes

end end time.

Name

Type

Required

Description

start

string

Yes

start start time.

end

string

Yes

end end time.

Name

Type

Required

Description

start

string

Yes

start start time.

end

string

Yes

end end time.

Name

Type

Required

Description

start

string

Yes

start start time.

end

string

Yes

end end time.

Name

Type

Description

time

string

The time of the snapshot.

base64

string

The snapshot content in base64.

binary

string

The snapshot content as a binary string.

error

Error

Details of the snapshot error.