ApsaraVideo VOD:Aliplayer API reference

Name

Type

Description

id

String

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

source

String

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

vid

String

The media ID in 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 applicable to the VidAuth playback method 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 can effectively mitigate carrier hijacking risks and significantly improve playback stability and success rate.

playConfig

JSON

A custom settings field for Vid-based playback (VidAuth and VidSts). The settings are passed through to the VOD API. For information about the supported custom fields and their descriptions, see Custom media playback settings (PlayConfig). The following code provides a value example:

{"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 that 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 500px and automatically adjusts the height based on the actual video aspect ratio.

Alternatively, you can specify `height: '500px', autoSize: 'width'`. The player maintains a height of 500px and automatically adjusts the width based on the actual video 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

The player automatically loads the video.

cover

String

The default thumbnail of the player. Enter 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. If it is, the player prevents users from dragging the progress bar. The default value is false. Set this to true when playing a live stream.

autoplay

Boolean

Specifies whether the player autoplays the video. The autoplay property is not effective on mobile devices. Valid values:

• true: Enables autoplay.

• false (default): Disables autoplay.

autoplayPolicy

Object

The adaptive muted autoplay policy for the player. This property takes effect only when autoplay is set to true. The following code provides a configuration example:

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

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 on some Android browsers.

skinRes

Url

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

skinLayout

Array | Boolean

The layout configuration for functional components. If you do not specify this field, 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. The following code provides a configuration example:

skinLayoutIgnore: [
  'bigPlayButton', // Hides the large play button.
  'controlBar.fullScreenButton' // Hides the full screen button on the control bar (selects a sub-component using dot notation).
]

controlBarVisibility

String

The implementation of the control panel. The valid values are:

• click: Clicks the player area.

• hover (default): Moves to the player area.

• always: The control bar is always displayed.

• never: Hides the entire control bar.

showBarTime

Number

The time in milliseconds before the control bar automatically hides.

enableSystemMenu

Boolean

Specifies whether to show the system's right-click menu. 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 when you use the `vid` playback method. 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 when you use the Vid + PlayAuth playback method. 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)

• HD (high definition)

• HD (Ultra High Definition)

• OD (Original Quality)

• 2K (2K)

• 4K (4K)

defaultDefinition

String

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

• FD (Low Definition)

• LD (Standard Definition)

• HD (high definition)

• HD (Ultra High Definition)

• OD (Original Quality)

• 2K (2K)

• 4K (4K)

autoPlayDelay

Number

The delay before playback starts. Unit: seconds.

language

String

The language for 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: Enables the plugin.

• false (default): Disables the plugin.

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): Enables the cache.

• false: Disables the cache.

stashInitialSizeForFlv

Number

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

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

loadDataTimeout

Number

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

waitingTimeout

Number

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

diagnosisButtonVisible

Boolean

Specifies whether to display the diagnosis button. Valid values:

• true (default): Displays the button.

• false: Does not display the button.

disableSeek

Boolean

Disables seeking on the progress bar. Valid values:

• true: Disables seeking.

• false (default): Does not disable.

encryptType

Number

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

• 0: Plays unencrypted videos.

• 1: Plays privately encrypted videos.

progressMarkers

Array

An array of content for marking the progress bar. 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 streaming mode, specifies whether to enable frame synchronization. Valid values:

• true: Enables frame synchronization.

• false (default): Disables frame synchronization.

chasingFirstParagraph

Number

The duration of the first frame synchronization segment. Unit: seconds. The default is 20 seconds.

chasingSecondParagraph

Number

The duration of the second frame synchronization segment. Unit: seconds. The default is 40 seconds.

chasingFirstSpeed

Number

The playback speed for the first frame synchronization segment. The default is 1.1x.

chasingSecondSpeed

Number

The playback speed for the second frame synchronization segment. The default is 1.2x.

hlsOption.maxLiveSyncPlaybackRate

Number

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

• Configuration example:

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

• Example meaning: When the live streaming latency is greater than the duration of 3 segments, the player plays at 1.5x speed to catch up to a latency of 3 segments. Because the player needs a certain buffer to handle network fluctuations, modify the value of liveSyncDurationCount with caution. A value that is too small may cause stuttering.

flvFrameChasing

Boolean

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

• true: Enables frame synchronization.

• false: Disables frame synchronization.

The default value is false.

keyShortCuts

Boolean

Specifies whether to enable keyboard shortcuts. Valid values:

• true: Enables keyboard shortcuts.

• false: Disables keyboard shortcuts.

The default value is false.

keyFastForwardStep

Number

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

rtsFallback

Boolean

When the browser does not support RTS or RTS stream pulling fails, the player automatically tries to fall back to FLV or HLS for playback. It prioritizes FLV for 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 are HLS or FLV. If you do not pass this parameter, the player automatically selects a protocol. It prioritizes FLV for lower latency. If the browser does not support FLV, it falls back to HLS.

rtsFallbackSource

String

We recommend that you use 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 own unique user identifier. Pass the `traceId` to the public instrumentation for tracking reported logs. By default, the Web Player SDK has log reporting enabled. Passing a `traceId` helps you identify users. If you do not pass it, 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 WebVTT external captions. The following code provides an 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 aspect 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 parts of the UI. For example, to change the display text for the HD resolution, which defaults to 高清 (High Definition), you can change it to 1080p as follows:

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

speedLevels

Array

Sets a custom playback speed list array. `key` represents the speed value, and `text` represents the UI text. If not passed, the default list is used. The following code provides a parameter value example:

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 a custom logo image. The following code provides an 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/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 (Old Version), 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:

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

mute

Boolean

Sets whether to play the video on mute. When browsers prohibit autoplay, you can configure this parameter for muted autoplay. For more information, see Advanced features.

clickPause

Boolean

Click the video screen to pause or play.

• true: Enabled.

• false: Disabled.

The default value is `true` on PCs and `false` on mobile devices. Do not use this property with the `dbClickSkip` property to avoid interaction conflicts.

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, allowing playback and seeking only within the specified start and end times.

Unit: seconds

watchEndTime

Number

Used with `watchStartTime` to enable range playback, allowing playback and seeking only within the specified 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 a separate video. For example, for a 60-second video, setting `start:10` and `end:30` results in a video with a displayed duration of 20 seconds, starting playback 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 a separate video. For example, for a 60-second video, setting `start:10` and `end:30` results in a video with a displayed duration of 20 seconds, starting playback from the 10-second mark of the original video.

dbClickFullscreen

Boolean

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

longPressFastForward

Boolean

The long-press for fast-forward feature (mobile only). Valid values:

• true (default): Enabled.

• false: Disabled.

dbClickSkip

Boolean

The double-click to skip feature (mobile only), where double-clicking the left area fast-backwards and the right area fast-forwards. Valid values:

• true (default): Enabled.

• false: Disabled.

Do not use this property with the `clickPause` property to avoid interaction conflicts.

enableMockFullscreen

Boolean

Web page full screen feature. The player calls the browser's full screen API by default. On iOS browsers and some Android browsers, full screen mode is taken over by the system player, which can cause issues like the UI disappearing. To prevent this, you can enable this parameter to implement a pseudo-full screen using CSS. The default value is false.

Name

Parameter type

Required

Description

showPlayButton

Boolean

No

Specifies whether to show the play button.

Name

Parameter type

Required

Description

time

number

Yes

The time to seek to. Unit: seconds.

Name

Parameter 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

Parameter type

Required

Description

quiet

boolean

No

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

Name

Parameter type

Required

Description

quiet

boolean

No

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

Name

Parameter type

Required

Description

url

string

Yes

The URL of the video to switch to.

seconds

number

No

The starting position after switching.

autoPlay

boolean

No

Specifies whether to autoplay after switching.

Name

Parameter type

Required

Description

vid

string

Yes

The video ID.

playauth

string

Yes

The playback credential.

Name

Parameter type

Required

Description

mediaAuth

string

Yes

The playback credential.

Name

Parameter type

Required

Description

name

string

Yes

For the names of built-in components (such as `fullScreenButton`), see Configure the skinLayout property. Each component supports `hide()` and `show()` methods to control its visibility.

Name

Parameter type

Required

Description

width

string

Yes

Sets the player size. Valid values:

• 400px

• 60%

height

string

Yes

Name

Parameter type

Required

Description

speed

number

Yes

Supports playback speeds from 0.5x to 2x.

Name

Parameter type

Required

Description

traceId

string

Yes

A unique identifier.

Name

Parameter type

Required

Description

width

number

Yes

The height and width are in px. The screenshot quality is a number between 0 and 1, with a default of 1. For detailed information about video screenshots, see Video screenshots.

height

number

Yes

rate

number

Yes

Name

Parameter type

Required

Description

start

string

Yes

start is the start time of the live stream.

end

string

Yes

end is the end time of the live stream.

Name

Parameter 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

Parameter type

Required

Description

type

string

Yes

Valid values:

• horizon: Horizontal.

• vertical: Vertical.

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

Name

Parameter type

Required

Description

coverUrl

string

Yes

The thumbnail URL.

Name

Parameter type

Required

Description

markers

Array<markers>

Yes

markers: A collection of marker data. Required.

marker.time: The time of the marker. Required.

marker.text: The text for the marker. Required.

For more information, see the `progressMarkers` parameter.

Name

Parameter type

Required

Description

time

number

Yes

Unit: seconds. For more information, see Preview.

Name

Parameter type

Required

Description

textTracks

Array<object>

Yes

The following code provides an 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

Parameter type

Required

Description

logoList

Array<object>

Yes

The following code provides an 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

Parameter type

Required

Description

start

string

Yes

start is the start time.

end

string

Yes

end is the end time.

Name

Parameter type

Required

Description

start

string

Yes

start is the start time.

end

string

Yes

end is the end time.

Name

Parameter type

Required

Description

start

string

Yes

start is the start time.

end

string

Yes

end is the end time.

Name

Parameter type

Required

Description

start

string

Yes

start is the start time.

end

string

Yes

end is the end time.

Name

Parameter type

Description

time

string

The time of the snapshot.

base64

string

The base64 content of the snapshot.

binary

string

The snapshot content as a binary string.

error

Error

Details of the snapshot exception.