ApsaraVideo VOD:Aliplayer API Reference

Name

Type

Description

id

String

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

source

String

When using URL-based playback, specify the video URL with this property.

vid

String

The media ID for the ApsaraVideo Media Processing service.

playauth

String

The playback credential. For instructions on obtaining a playback credential, see Obtain a Playback Credential.

customVodServer

String

A custom domain for VOD proxy (supported in VidAuth playback mode version 2.32.0 and later). You must deploy a dedicated request proxy service. When the default VOD domain (*.aliyuncs.com) is unreachable, the player automatically falls back to your proxy service. This avoids ISP hijacking and improves playback stability and success rate.

playConfig

JSON

Custom settings used when playing with Vid (VidAuth or VidSts). These pass through to the VOD API. For supported fields and parameter descriptions, see Custom PlayConfig Settings for Media Playback. Example value:

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

authTimeout

Number

The validity period of the video playback URL obtained using Vid (VidAuth or VidSts). Unit: seconds. Default: 7200.

Ensure this value exceeds the actual video duration to prevent the playback URL from expiring before playback finishes.

height

String

The player height. Valid values:

• 100%

• 100px

width

String

The player width. Valid values:

• 100%

• 100px

autoSize

Boolean | String

Automatically adjust the player size to fit the video content. Valid values: 'height' or 'width'.

For example, set width: '500px' and autoSize: 'height'. The player keeps a fixed width of 500px and adjusts its height based on the video's aspect ratio.

Or set height: '500px' and autoSize: 'width'. The player keeps a fixed height of 500px and adjusts its width based on the video's aspect ratio.

Note: autoSize: true equals autoSize: 'height'. Height auto-sizing is the default.

videoWidth

String

The video width. For more information, see Set Display Mode.

videoHeight

String

The video height. For more information, see Set Display Mode.

preload

Boolean

The player loads automatically.

cover

String

The default cover image for the player. Enter a valid image URL. This setting takes effect only when autoplay is set to false.

isLive

Boolean

Indicates whether the content is live streaming. When enabled, users cannot drag the progress bar. Default: false. Set to true for live streams.

autoplay

Boolean

Enable autoplay for the player. Autoplay fails on mobile devices. Valid values:

• true (default): Enable autoplay.

• false: Disable autoplay.

autoplayPolicy

Object

The player supports an adaptive policy for muted autoplay. This property takes effect only when autoplay is set to true. A configuration example is as follows:

autoplayPolicy: {
  fallbackToMute: true, // Fallback to muted autoplay if audible autoplay fails. Default: false.
  showUnmuteBtn: true, // Show a large unmute button when muted autoplay is active. Default: true.
}

rePlay

Boolean

Enable automatic loop playback.

useH5Prism

Boolean

Use the HTML5 player.

playsinline

Boolean

Enable inline playback for HTML5. Some Android browsers do not support this.

skinRes

Url

The skin image URL. We do not recommend changing this field. To customize the skin, see Customize the Player Skin.

skinLayout

Array | Boolean

Configure the layout of UI components. Omit this property to use the default layout. Set to false to hide all UI components. For more information, see Configure the skinLayout Property.

skinLayoutIgnore

Array

List of UI components to hide. See VOD Component Parameter Reference for component names. Example configuration:

skinLayoutIgnore: [
  'bigPlayButton', // Hide the large play button.
  'controlBar.fullScreenButton' // Hide the full-screen button in the control bar (use dot notation for nested components).
]

controlBarVisibility

String

Control panel implementation. Valid values include the following:

• click: You can click the player area.

• hover (default): Show when the user hovers over the player area.

• always: Always show the control bar.

• Never: Hides the entire control panel.

showBarTime

Number

Time in milliseconds before the control bar hides automatically.

enableSystemMenu

Boolean

Enable the system right-click menu. Default: false.

format

String

Specify the format of the playback URL. Valid values:

• mp4

• hls or m3u8

• flv

• mp3

Default: empty.

mediaType

String

Specify whether to return audio or video. Supported only when using vid-based playback. Default: video. Valid values:

• video: Video.

• audio: Audio-only formats, such as MP4 files containing only audio.

qualitySort

String

Specify the sorting order. Supported only when using Vid + PlayAuth playback. Valid values:

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

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

Default: asc.

definition

String

Define which video definitions to display. Separate multiple definitions with commas (,). Example: 'FD,LD'. This is a subset of definitions available for the specified 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

Set the default video definition. This must be one of the definitions available for the specified vid. Valid values:

• FD (low definition)

• LD (standard definition)

• SD (Standard Definition)

• HD (ultra-high definition)

• OD (original quality)

• 2K (2K)

• 4K (4K)

autoPlayDelay

Number

Delay before playback starts. Unit: seconds.

language

String

Set the language for internationalization. Default: zh-cn. If omitted, the browser language is used. Valid values:

• zh-cn: Chinese

• en-us: English

languageTexts

JSON

Custom internationalization text in JSON format. Keys must match the language property value. Example: {jp:{Play:"Play"}}. For a complete list of keys, see JSON Structure.

snapshotWatermark

Object

Configure screenshot watermarks for HTML5 players.

useHlsPluginForSafari

Boolean

Enable the HLS plugin for Safari browsers, except Safari 11. Valid values:

• true: Enable.

• false (default): Disable.

enableStashBufferForFlv

Boolean

Enable playback caching for FLV in HTML5 players. Applies only to live streaming. Valid values:

• true (default): Enable.

• false: Disable.

stashInitialSizeForFlv

Number

Initial cache size for FLV in HTML5 players. Applies only to live streaming. Default: 32 KB.

A smaller value improves startup speed. However, if too small, playback may stutter after a short time.

loadDataTimeout

Number

Time in seconds before prompting the user to switch to a lower definition due to buffering. Default: 20.

waitingTimeout

Number

Maximum buffering timeout. An error message appears if this time is exceeded. Unit: seconds. Default: 60.

diagnosisButtonVisible

Boolean

Show the diagnosis button. Valid values:

• true (default): Show the button.

• false: Hide the button.

disableSeek

Boolean

Disable seeking with the progress bar. Valid values:

• true: Disable.

• false (default): Does not disable.

encryptType

Number

Enable Alibaba Cloud video encryption (private encryption). Default: 0. Valid values:

• 0: Play unencrypted videos.

• 1: Play privately encrypted videos.

progressMarkers

Array

An array of progress marker objects. For more information, see Progress Bar Markers.

vodRetry

Number

Number of retries for VOD playback failures. Default: 3.

liveRetry

Number

Number of retries for live streaming playback failures. Default: 5.

hlsFrameChasing

Boolean

Enable frame chasing for HLS live streaming. Valid values:

• true: Enable frame chasing.

• false (default): Disable frame chasing.

chasingFirstParagraph

Number

Duration of the first frame-chasing segment. Unit: seconds. Default: 20.

chasingSecondParagraph

Number

Duration of the second frame-chasing segment. Unit: seconds. Default: 40.

chasingFirstSpeed

Number

Playback speed for the first frame-chasing segment. Default: 1.1×.

chasingSecondSpeed

Number

Playback speed for the second frame-chasing segment. Default: 1.2×.

hlsOption.maxLiveSyncPlaybackRate

Number

Set the playback speed for frame chasing in HLS live streaming. Default: 1 (no frame chasing).

• Example configuration:

  hlsOption: {
    maxLiveSyncPlaybackRate: 1.5, // Set the frame-chasing playback speed.
    liveSyncDurationCount: 3 // Set the number of segments that trigger frame chasing.
  }

• Example meaning: When live streaming latency exceeds the duration of 3 segments, the player plays at 1.5× speed to catch up to 3 segments behind (because the player needs a buffer to handle network fluctuations, you should modify the liveSyncDurationCount value with caution — setting this value too low may cause stuttering).

flvFrameChasing

Boolean

Enable frame chasing for FLV live streaming. Valid values:

• true: Enable frame chasing.

• false: Disable frame chasing.

Default: false.

keyShortCuts

Boolean

Enable keyboard shortcuts. Valid values:

• true: Enable keyboard shortcuts.

• false: Disable keyboard shortcuts.

Default: false.

keyFastForwardStep

Number

Time interval for fast forward and rewind. Unit: seconds. Default: 10.

rtsFallback

Boolean

When the browser does not support RTS or RTS stream pulling fails, the player automatically falls back to FLV or HLS. It prefers 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, set this parameter to false.

rtsFallbackType

String

Specify the protocol to fall back to from RTS. Valid values: HLS or FLV. By default, the player selects automatically, preferring FLV for lower latency. If the browser does not support FLV, it falls back to HLS.

rtsFallbackSource

String

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

traceId

String

Your unique user identifier. Pass this value to public instrumentation points to track log reporting. By default, the Web Player SDK enables log reporting. Passing traceId helps identify users. If omitted, the Web Player SDK generates and stores a UUID in the browser cache.

textTracks

Array

Configure 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

Set the player to scale at a fixed aspect ratio. For example, given a video aspect ratio of 16:9, set the player parameters to width: "100%", ratio: 16/9. This keeps the player's aspect ratio consistent with the video content and enables it to automatically scale proportionally as the page scales.

extLanguageTexts

Object

The Web Player SDK includes built-in Chinese and English UI text. Use this property to customize text for specific UI elements. For example, to change the display of HD from high definition to 1080p:

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

speedLevels

Array

Customize the playback speed list. Each object contains a key (speed value) and text (UI label). If omitted, the default list is used. 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

Configure 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: Logo image URL.

• origin: Reference point for positioning. Valid values:

  • box: Player container

  • content: Video content

• width/height: Logo dimensions as a percentage (calculated relative to origin). If only one dimension is specified, the other scales proportionally.

• position: Relative position within origin. Valid values:

  • top-left: Top-left corner

  • top-right: Top-right corner

  • bottom-left: Bottom-left corner

  • bottom-right: Bottom-right corner

• offsetX/offsetY: Offset from position, as a percentage (calculated relative to origin).

license

Object

To use value-added features such as Playback Quality Monitoring (Legacy), Single-point Troubleshooting, or H.265/H.266 Video Playback, first submit the Web Player SDK Value-added Services Application Form to obtain a license. Then integrate the license as follows:

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

mute

Boolean

Enable muted playback. Configure this parameter to enable muted autoplay when browsers block autoplay. For details, see Advanced Features.

clickPause

Boolean

Click the video area to pause or resume playback.

• true: Enable.

• false: Disable.

Default: true on desktop, false on mobile. Do not use with dbClickSkip to avoid interaction conflicts.

disablePip

Boolean

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

env

String

By default, player telemetry data uploads to the China data center. If you have compliance requirements for data outside China, set env: 'SEA' to upload data to the Singapore data center.

watchStartTime

Number

Use alone to set the start time for playback.

Use with watchEndTime to enable time-range playback. Users can only play and seek within the specified time range.

Unit: seconds

watchEndTime

Number

Use with watchStartTime to enable time-range playback. Users can only play and seek within the specified time range.

If this value is less than watchStartTime, watchStartTime is ignored.

Unit: seconds

start

Number

Use with end to extract a segment from the video. For example, if the original video is 60 seconds long and you set start: 10 and end: 30, the player displays a 20-second video starting from the 10th second of the original video.

end

Number

Use with start to extract a segment from the video. For example, if the original video is 60 seconds long and you set start: 10 and end: 30, the player displays a 20-second video starting from the 10th second of the original video.

dbClickFullscreen

Boolean

Enable double-click to enter full screen. Enabled by default on desktop.

longPressFastForward

Boolean

Enable long-press fast forward (mobile only). Valid values:

• true (default): Enable.

• false: Disable.

dbClickSkip

Boolean

Double-click left side to rewind, double-click right side to fast forward (mobile only). Valid values:

• true (default): Enable.

• false: Disable.

Do not use with clickPause to avoid interaction conflicts.

enableMockFullscreen

Boolean

Enable CSS-based pseudo-fullscreen. By default, the player calls the browser's fullscreen API. On iOS and some Android browsers, the system player takes over full screen, causing UI issues. Enable this parameter to avoid takeover. Default: false.

watermark

Object

Configure dynamic watermarks. Example:

watermark: {
  enable: true,
  text: 'Copyright ©2026',
  mode: 'BULLET'
}

Field descriptions:

• enable: Enable dynamic watermark.

• text: Text to display as the watermark.

• mode: Watermark mode. Valid values:

  • BULLET: Marquee (default).

  • GHOST: Random blinking.

• direction: Movement direction. Valid values:

  • RTL: Right to left (default).

  • LTR: Left to right.

  • STATIC: Stationary (valid only for GHOST mode).

• speed: Movement speed. Range: 0~100. Higher values mean faster movement. Default: 50 for BULLET, 30 for GHOST.

• interval: Time in milliseconds between watermark disappearances and reappearance. Default: 3000.

• duration: Display duration for each watermark appearance (GHOST mode only). Default: 5000 (milliseconds).

• opacity: Transparency of watermark text. Range: 0~1. Default: 0.5.

• fontSize: Font size of watermark text. CSS font-size value. Default: 14px.

• fontColor: Color of watermark text. Any valid CSS color value. Default: #FFFFFF.

• top: Distance from the top of the container to the watermark area. Supports pixel values (e.g., 50) or percentages (e.g., '20%').

• bottom: Distance from the bottom of the container to the watermark area. Supports pixel values or percentages.

• left: Distance from the left of the container to the watermark area. Supports pixel values or percentages (GHOST mode only).

• right: Distance from the right of the container to the watermark area. Supports pixel values or percentages (GHOST mode only).

memoryPlay

Object

To enable resume playback, add the memoryPlay option to the player configuration. Example:

// Resume playback configuration
memoryPlay: {
    enable: true, // Enable resume playback.
    autoSeek: false // Automatically jump to the remembered position.
}

Field descriptions:

• enable: Enable resume playback. Valid values:

  • false (default): Disable resume playback.

  • true: Enable resume playback.

• autoSeek: Automatically jump to the remembered position. Valid values:

  • false (default): Show a prompt asking the user whether to jump (recommended).

  • true: Jump to the remembered position and show a prompt after the video loads.

getTimeFunction/saveTimeFunction are used for scenarios requiring custom playback progress control (such as multi-device sync). If omitted, the player defaults to storing progress in localStorage.

• getTimeFunction: Retrieve the remembered time from a custom storage location. Function signature: (videoKey) => number｜Promise<number>.

• saveTimeFunction: Save the current playback time. Function signature: (videoKey, currentTime) => void.

menuMode

String

Set where to display the playback speed, definition, caption, and audio track controls. Valid values:

• fold (default): Place in the Settings submenu.

• expand: Display in the control bar (main menu).

Name

Type

Required

Description

showPlayButton

Boolean

No

Show the play button.

Name

Type

Required

Description

time

number

Yes

Time to jump to. Unit: seconds.

Name

Type

Required

Description

volume

number

Yes

Volume as a real number between 0 and 1. Not supported on iOS and some Android devices.

Name

Type

Required

Description

quiet

boolean

No

Hide the mute/unmute status text in the bottom-left corner.

Name

Type

Required

Description

quiet

boolean

No

Whether to hide the text prompt in the bottom-left corner when you unmute.

Name

Type

Required

Description

url

string

Yes

The URL of the video to switch to.

seconds

number

No

Playback start time after switching.

autoPlay

boolean

No

Start playback automatically 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 built-in component name (e.g., fullScreenButton). See Configure the skinLayout Property for a list of component names. Each component supports hide and show methods.

Name

Type

Required

Description

width

string

Yes

Set the player size. Valid values:

• 400px

• 60%

height

string

Yes

Name

Parameter 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

Width and height units: pixels. Screenshot quality range: 0–1 (default: 1). For more details, see Video Screenshots.

height

number

Yes

rate

number

Yes

Name

Type

Required

Description

start

string

Yes

Start time for live streaming.

end

string

Yes

End time for live streaming.

Name

Type

Required

Description

rotate

number

Yes

Positive values rotate clockwise. Negative values rotate counterclockwise. Example: setRotate(90). For more information, see Set Display Mode.

Name

Type

Required

Description

type

string

Yes

Valid values:

• horizon: Horizontal flip.

• Vertical: Refers to a vertical orientation.

Example: setImage('horizon'). For more information, see Set Display Mode.

Name

Type

Required

Description

coverUrl

string

Yes

Thumbnail URL.

Name

Type

Required

Description

markers

Array<markers>

Yes

markers: Array of marker objects (required).

marker.time: Time of the marker (required).

marker.text: Text label for the marker (required).

See parameter progressMarkers for details.

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 field descriptions, see property: logo.

Name

Type

Required

Description

start

string

Yes

Start time.

end

string

Yes

End time.

Name

Type

Required

Description

start

string

Yes

Start time.

end

string

Yes

End time.

Name

Type

Required

Description

start

string

Yes

Start time.

end

string

Yes

End time.

Name

Type

Required

Description

start

string

Yes

Start time.

end

string

Yes

End time.

Name

Type

Description

time

string

Screenshot time.

base64

string

Base64-encoded screenshot content.

binary

string

Binary string representation of the screenshot content.

error

Error

Details of any screenshot error.