All Products
Search
Document Center

ApsaraVideo VOD:API operations

Last Updated:Feb 18, 2024

This topic describes the parameters, methods, events, and error codes for ApsaraVideo Player SDK for Web and provides sample code of API operations used in ApsaraVideo Player SDK for Web.

Parameters

Note

If errors occur when you use ApsaraVideo Player SDK for Web, troubleshoot the errors by following the instructions provided in FAQ about ApsaraVideo Player for Web or Troubleshoot playback errors.

Parameter

Type

Description

id

String

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

source

String

The video playback URL.

Note
  • URL-based playback has a higher priority over other playback methods. You cannot specify the source parameter when you play a video by using VID and PlayAuth or by using a Security Token Service (STS) token. If you specify this parameter, the player plays the video based on the URL that you specify. We recommend that you use only one playback method.

  • You can use the source parameter to specify the URLs of the streams in multiple definitions. For more information, see Multi-definition playback. Sample code:

    source:'{"HD":"address1","SD":"address2"}'

vid

String

The media ID for media transcoding.

playauth

String

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

authTimeout

Number

The validity period of the URL that is used for playback based on VID and PlayAuth or playback based on STS. 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

Note

The size of the Flash player in Google Chrome cannot be smaller than 397 × 297 pixels.

width

String

The width of the player. Valid values:

  • 100%

  • 100px

Note

The size of the Flash player in Google Chrome cannot be smaller than 397 × 297 pixels.

videoWidth

String

The width of the video. This parameter is supported only for the HTML5 player. For more information, see Specify the display mode.

videoHeight

String

The height of the video. This parameter is supported only for the HTML5 player. For more information, see Specify the display mode.

preload

Boolean

Specifies whether to enable automatic loading for the player. This parameter is supported only for the HTML5 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. For the Flash player, you must also enable the cross-origin resource sharing (CORS) feature for this parameter to take effect. For more information, see Configure CORS.

isLive

Boolean

Specifies whether a live stream is being played. Live streams cannot be advanced or rewound. 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 on mobile devices.

Note

By default, Safari 11 does not allow autoplay. To allow autoplay in Safari 11, right-click the address bar and choose Settings for This Website... > Allow All Autoplay.

rePlay

Boolean

Specifies whether to enable automatic loop playback.

useH5Prism

Boolean

Specifies that the HTML5 player is used.

useFlashPrism

Boolean

Specifies that the Flash 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, see Configure the player skin.

skinLayout

Array | Boolean

The layout of the feature components. If you leave this parameter empty, the default layout is used. false indicates that all feature components are hidden. For more information, see Configure skinLayout.

controlBarVisibility

String

Specifies how to display the control bar. Default value: hover. Valid values:

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

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

  • always: The control bar is always displayed.

  • never: The control bar is hidden.

showBarTime

String

The period of time elapsed before the control bar is automatically hidden. Unit: milliseconds.

extraInfo

String

The custom parameter. The value is a JSON string. This parameter is supported only for the Flash player. Valid values:

  • fullTitle: The video title is displayed when the video is played in full-screen mode on the test page.

  • m3u8BufferLength: the duration of buffered TS files during the playback of HTTP Live Streaming (HLS) videos. Unit: seconds.

enableSystemMenu

Boolean

Specifies whether to display the shortcut menu upon a right click. Default value: false.

format

String

The format of the playback URL. This parameter is supported only for video playback based on VID. Valid values:

  • mp4

  • hls or m3u8

  • flv

  • mp3

By default, this parameter is left empty. If you specify a value for this parameter, it takes effect only for the HTML5 player.

mediaType

String

The media type of the returned content. This parameter is supported only for video playback based on VID. Default value: video. Valid values:

  • video: returns video files.

  • audio: returns video files that contain only audio, such as MP4 files. You can set this parameter to audio only for the HTML5 player.

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. This parameter is supported only for the HTML5 player.

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. This parameter is supported only for the HTML5 player. 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 video specified by VID. This parameter is supported only for the HTML5 player. 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. Unit: seconds. For more information, see Configure the playback delay.

autoPlayDelayDisplayText

String

The text message that notifies users of the playback delay. For more information, see Configure the playback delay.

language

String

The language used by the player. 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 more information, see JSON format.

snapshot

Boolean

Specifies whether to enable the snapshot feature for the Flash player. Valid values:

  • true

  • false (default)

snapshotWatermark

Object

The snapshot watermark for the HTML5 player.

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 buffer size for FLV playback in the HTML5 player. 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 before the system prompts the user to switch to a lower resolution. Unit: seconds. Default value: 20.

waitingTimeout

Number

The maximum buffer duration. An error message appears after the maximum buffer duration elapses. Unit: seconds. Default value: 60.

diagnosisButtonVisible

Boolean

Specifies whether to display the diagnosis button. Valid values:

  • true

  • false

Default value: true.

disableSeek

Boolean

Specifies whether to disable the seeking feature. Valid values:

  • true

  • false

Default value: false.

Note

This parameter is supported only for the Flash player.

encryptType

Number

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

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

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

Note
  • A video that is encrypted by using Alibaba Cloud proprietary cryptography is played based on VID and PlayAuth.

  • A video that is encrypted in HLS encryption mode is played based on the URL. For more information, see Play an encrypted video.

progressMarkers

Array

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

vodRetry

Number

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

liveRetry

Number

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

hlsFrameChasing

Boolean

Specifies whether to enable frame synchronization for HLS-based live streaming. 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. Unit: seconds. Default value: 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.

flvFrameChasing

Boolean

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

  • true

  • false

Default value: false.

keyShortCuts

Boolean

Specifies whether to enable shortcut keys. Valid values:

  • true

  • false

Default value: false.

Note

The left and right arrow keys enable fast forward and rewind, the up and down arrow keys enable volume increase and volume decrease, and the space bar enables the pause and play of the video.

keyFastForwardStep

Number

The time range for the fast forward and rewind operations. Unit: seconds. Default value: 10.

rtsFallbackSource

String

The alternative RTS URL, such as a playback URL in the HLS or FLV format.

When you use a playback URL in the RTS format but your browser does not support RTS or stream pulling over RTS fails, the video specified in this URL is automatically played.

rtsLoadDataTimeout

Number

The RTS timeout period. The system retries to pull streams from RTS after the timeout period elapses. Unit: milliseconds. Default value: 3000.

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 save the UUID to the browser cache.

Note

This parameter is supported for ApsaraVideo Player SDK for Web V2.10.0 and later.

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

The following items describe the fields:

  • kind: the type of the VTT file. Valid values: subtitles and captions.

  • label: the display name of the subtitle.

  • srclang: the subtitle language.

  • src: the URL of the subtitle file. You need to enable CORS.

  • default: specifies whether to display subtitles by default. Valid values: true and false. This parameter is supported only in ApsaraVideo Player SDK V2.15.7 or later.

Note
  • This parameter is supported for ApsaraVideo Player SDK for Web V2.12.0 and later.

  • WebVTT external subtitles are not supported in the following browsers:

    • IE

    • QQ Browser on Android devices, OPPO Browser, and the system browser of OnePlus

    • Other browsers that hijack the video tag.

  • For more information about subtitle attributes, see HTML Standard.

  • For more information about advanced subtitle settings, see Advanced features.

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

Methods

You can call methods after the ready event is complete or in the ready callback for creating the player. In the HTML5 player, methods can be called in the callback function of the constructor that is used to create a player. Sample code:

  • For the HTML5 player, use the following sample code:

    // HTML5 player
     var player = new Aliplayer({},function(player) {
        player.play();
     });
  • For the Flash player, use the following sample code:

    // Flash player
     player.on('ready',function(e) {
        player.play();
     });

Method

Parameter

Description

play

None

Plays a video.

pause

None

Pauses a video.

replay

None

Replays a video.

seek

time

Seeks to the video image at a specific point in time to start the playback. Unit: seconds.

getCurrentTime

None

Obtains the current playback time. Unit: seconds.

getDuration

None

Obtains the total duration of a video. Unit: seconds. The value can be obtained only after the video is loaded and the play event is complete.

getVolume

None

Obtains the current volume. The return value is a real number ranging from 0 to 1. This method does not take effect on iOS devices and specific Android devices.

setVolume

None

Obtains the volume. The value is a real number ranging from 0 to 1. This method does not take effect on iOS devices and specific Android devices.

loadByUrl

url(String), time(Number)

Obtains the streaming URL. You can choose whether to specify the time parameter. The unit of the time parameter is second. You can switch between video streams in the same format. The MP4, FLV, and HLS formats are supported. You cannot switch between Real-Time Messaging Protocol (RTMP) streams.

replayByVidAndPlayAuth

vid (string): video ID, playauth (string): playback credential

This parameter is supported only for the HTML5 player. You cannot switch between video streams in different formats. You cannot switch between RTMP streams.

You can call this method to switch between on-demand Digital Rights Management (DRM) streams. Syntax: player.replayByVidAndPlayAuth(vid,playauth).

replayByVidAndAuthInfo

This method is available only for ApsaraVideo for Media Processing (MPS) users. Specify parameters in the following sequence: vid(String), accId(String), accSecret(String), stsToken(String), authInfo(String), and domainRegion(String).

This parameter is supported only for the HTML5 player. You cannot swtich between video streams in different formats. You cannot switch between RTMP streams.

setPlayerSize

w(String), h(String)

Sets the player sizer. Valid values:

  • 400px

  • 60%

The size of the Flash player in Google Chrome cannot be smaller than 397 × 297 pixels.

setSpeed

speed(Number)

Sets the playback speed. Playback speeds ranging from 0.5 to 2 are supported. This parameter is supported only for the HTML5 player. This method may not take effect for apps on mobile devices, such as WeChat for Android. By default, the UI for playback speed control is enabled.

Note

How to disable playback speed control:

  • You cannot disable playback speed control or customize a playback speed. You can only disable the overall settings.

  • Call the hack method to disable playback speed control by overwriting the CSS style.

     .prism-setting-speed {
        display: none !important;
      }

setSanpshotProperties

width(Number): width, height(Number): height, rate(Number): snapshot quality

Sets snapshot configurations. 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.

fullscreenService.requestFullScreen

None

Enables full-screen mode. This method is supported only for the HTML5 player.

fullscreenService.cancelFullScreen

None

Exits full-screen mode. This method does not take effect on iOS devices. This method is supported only for the HTML5 player.

fullscreenService.getIsFullScreen

None

Obtains the full-screen status of the player. This method is supported only for the HTML5 player.

getStatus

None

Obtains the player status. Valid values:

  • init

  • ready

  • loading

  • play

  • pause

  • playing

  • waiting

  • error

  • ended

setRotate

rotate(Number): rotation angle

Sets the rotation angle. A positive value specifies a clockwise rotation and a negative value specifies an anticlockwise rotation. Example: setRotate(90). For more information, see Specify the display mode.

getRotate

None

Obtains the rotation angle. For more information, see Specify the display mode.

setImage

image(String): image type

Sets the mirroring mode. Valid values:

  • horizon: horizontal mirroring

  • vertical: vertical mirroring

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

dispose

None

Destroys a player.

setCover

cover (string): thumbnail URL

Sets the thumbnail URL.

setProgressMarkers

markers(Array): marker dataset

Sets markers.

setPreviewTime

time(Number): preview duration

Sets the preview duration. Unit: seconds. For more information, see the Preview (URL) component on the Aliplayer website.

getPreviewTime

None

Obtains the preview duration.

isPreview

None

Specifies whether to enable the preview feature.

getCurrentPDT

None

You can obtain the ProgramDateTime value in real time for HLS videos.

setTraceId

traceId(String): public tracking point

Sets the public tracking point used to track logs. You can call player.setTraceId(traceId); to set traceId.

Note

This parameter is supported for ApsaraVideo Player SDK for Web 2.10.0 and later.

setTextTracks

textTracks(Array)

Sets WebVTT external subtitles. Sample code:

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

This method is supported for ApsaraVideo Player SDK for Web 2.12.0 and later.

setLogo

logo(Array)

Specifies a custom logo image. Sample code:

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.

Events

Player events

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.

Note

Methods provided by a player can be called only after the ready event is complete.

play

The event that is triggered when a paused video is played again.

pause

The event that is triggered 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 triggered during playback. This event can be triggered multiple times.

ended

The event that is triggered after the video playback is complete.

liveStreamStop

The event that is triggered 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 the live stream is interrupted or the video needs to be reloaded.

Note

If an HLS stream is interrupted or an error occurs during live streaming, the player automatically tries to reload the stream for five times. You do not need to configure a retry logic.

onM3u8Retry

The retry event that is triggered when an HLS stream is interrupted. This event is called only once for each live stream interruption.

hideBar

The event that is triggered to automatically hide the control bar.

showBar

The event that is triggered to automatically display the control bar.

waiting

The data caching event.

timeupdate

The event that is triggered when the playback position changes. This event is supported only for the HTML5 player. You can call the getCurrentTime method to obtain the current playback time.

snapshoted

The event that is triggered when a snapshot is captured.

requestFullScreen

The event that is triggered to enable full-screen mode. This event is supported only for the HTML5 player.

cancelFullScreen

The event that is triggered to exit full-screen mode. This event is supported only for the HTML5 player and is not triggered on iOS devices.

error

The event that is triggered 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 triggered when the video resolution is changed during live streaming.

seiFrame

The event that is triggered 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 parameter is returned 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.

Subscribe to events

  • You can subscribe to an event by using the on method of a player instance. Sample code:

    var handleReady = function(e)
    {
        console.log(e);
    }
    player.on('ready',handleReady);
  • You can unsubscribe from an event by using the off method of a player instance. Sample code:

    player.off('ready',handleReady);