ApsaraVideo VOD:Aliplayer API description

Name

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

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

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

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.

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.

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

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

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.

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

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.

Name

Parameter type

Required

Description

showPlayButton

Boolean

No

Specifies whether to display the playback button.

Name

Parameter type

Required

Description

time

number

Yes

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

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.

Name

Parameter type

Required

Description

quiet

boolean

No

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

Name

Parameter type

Required

Description

quiet

boolean

No

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

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.

Name

Parameter type

Required

Description

vid

string

Yes

The ID of the source file.

playauth

string

Yes

The playback credential.

Name

Parameter type

Required

Description

mediaAuth

string

Yes

The playback credential.

Name

Parameter type

Required

Description

width

string

Yes

Sets the player sizer. Valid values:

• 400px

• 60%

height

string

Yes

Name

Parameter type

Required

Description

speed

number

Yes

Supports 0.5 to 2 times speed playback.

Name

Parameter type

Required

Description

traceId

string

Yes

The unique identifier.

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

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.

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.

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

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.

Name

Parameter type

Required

Description

time

number

Yes

Unit: seconds. For more information, see Preview.

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' }])

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.

Name

Parameter type

Required

Description

start

string

Yes

start: the start time.

end

string

Yes

end: the end time.

Name

Parameter type

Required

Description

start

string

Yes

start: the start time.

end

string

Yes

end: the end time.

Name

Parameter type

Required

Description

start

string

Yes

start: the start time.

end

string

Yes

end: the end time.

Name

Parameter type

Required

Description

start

string

Yes

start: the start time.

end

string

Yes

end: the end time.

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.