Integrate ApsaraVideo Player SDK for Web - ApsaraVideo VOD

This topic describes how to integrate and use ApsaraVideo Player SDK for Web to play audio and video files.

Usage notes

In this topic, ApsaraVideo Player SDK for Web V2.25.1 is used as an example. We recommend you use the latest version. For more information, see SDK overview and download.
ApsaraVideo Player SDK for Web allows you to play audio and video files by using the HTML5 player or Flash player. Before you integrate ApsaraVideo Player SDK for Web, you must determine the player that you want to use and learn about its features and compatibility with different browsers. For more information, see Overview.
ApsaraVideo Player SDK for Web V2.14.0 or later supports playback of H.265 videos and ApsaraVideo Player SDK for Web V2.20.2 or later supports playback of H.266 videos. This topic describes how to integrate and use ApsaraVideo Player SDK for Web to play H.264 videos. For more information about how to use the SDK to play H.265 and H.266 videos, see Play H.265 and H.266 videos.

Procedure

Integrate ApsaraVideo Player SDK for Web.

Use the node package manager (NPM) to integrate ApsaraVideo Player SDK for Web. Sample code:

//Run npm install aliyun-aliplayer --save to install the NPM package.
import Aliplayer from 'aliyun-aliplayer';
import 'aliyun-aliplayer/build/skins/default/aliplayer-min.css';

Alternatively, perform the following steps to integrate ApsaraVideo Player SDK for Web by using the .js file.

Add an adaptive .js file

The adaptive .js file contains the adaptation logic for the Flash player and HTML5 player on multiple devices. After you add the .js file, ApsaraVideo Player SDK for Web automatically selects a player based on the environment. Add the .js file and .css file for ApsaraVideo Player SDK for Web under the <head> tag in the HTML document. Sample code:

<!--In the following content, ApsaraVideo Player SDK for Web V2.25.1 is used as an example. If you want to use other versions, obtain the version number and replace 2.25.1 in the sample code with the desired version number.-->
<head>
  <link rel="stylesheet" href="https://g.alicdn.com/apsara-media-box/imp-web-player/2.25.1/skins/default/aliplayer-min.css" />  // Optional. If you want to use the HTML5 player for playback, add the .css file to your project. 
  <script charset="utf-8" type="text/javascript" src="https://g.alicdn.com/apsara-media-box/imp-web-player/2.25.1/aliplayer-min.js"></script>  // Required. You must add the .js file. 
</head>

Note

After you add the .js file, specify useFlashPrism=true to use the Flash player or specify useH5Prism=true to use the HTML5 player.

Add a single-mode .js file

If you use only the Flash player or HTML5 player, you can add the .js file for only the player that you use to your project to reduce the file size.

If you use the HTML5 player, add the .js file and .css file of ApsaraVideo Player SDK for Web under the <head> tag in the HTML document. Sample code:

<head>
  <link rel="stylesheet" href="https://g.alicdn.com/apsara-media-box/imp-web-player/2.25.1/skins/default/aliplayer-min.css" />  // Required. You must add the .css file to use the HTML5 player. 
  <script charset="utf-8" type="text/javascript" src="https://g.alicdn.com/apsara-media-box/imp-web-player/2.25.1/aliplayer-h5-min.js"></script>  // Required. You must add the .js file to use the HTML5 player. 
</head>

If you use the Flash player, add the .js file of the ApsaraVideo Player SDK for Web under the <head> tag in the HTML document. Sample code:

<head>
  <script charset="utf-8" type="text/javascript" src="https://g.alicdn.com/apsara-media-box/imp-web-player/2.25.1/aliplayer-flash-min.js"></script>  // Required. You must add the .js file to use the Flash player. 
</head>

If you use the Flash player in Internet Explorer 8, you must add the reference to the json.min.js file under the <head> tag in the HTML document. Sample code:

https://g.alicdn.com/apsara-media-box/imp-web-player/2.25.1/json/json.min.js

Note

You can use the preceding sample code to integrate ApsaraVideo Player SDK for Web V2.16.3 or later. To integrate ApsaraVideo Player SDK for Web of a version that is earlier than V2.16.3, replace /apsara-media-box/imp-web-player in the preceding code with /de/prismplayer. The following sample code describes how to add an adaptive .js file for ApsaraVideo Player SDK for Web V2.15.2:

<head>
  <link rel="stylesheet" href="https://g.alicdn.com/de/prismplayer/2.15.2/skins/default/aliplayer-min.css" />  // Optional. If you want to use the HTML5 player for playback, add the .css file to your project. 
  <script charset="utf-8" type="text/javascript" src="https://g.alicdn.com/de/prismplayer/2.15.2/aliplayer-min.js"></script>  // Required. You must add the .js file. 
</head>

Specify a container for the player.
Add a <div> node that is used to mount the player under the <body> tag. Sample code:
```
<body>
  <div id="J_prismPlayer"></div>
</body>
```

Configure a license.
Note
- Starting from December 1, 2024, you must perform the following operations to configure the license for ApsaraVideo Player SDK for Web before you use the SDK.
- ApsaraVideo Player SDK provides free licenses that are valid for one year. For more information, see Manage licenses.
- If no license-related errors are reported on the player UI after you configure the license, the license is configured correctly.
- Make sure that the domain name of the page where the player resides is the same as the domain name specified when you apply for the license or a subdomain of the domain name. Otherwise, the license verification fails. If you specify localhost, the license is not verified.
When you initialize the player, specify the license-related fields, including the registered domain name and the license key:
```
var player = new Aliplayer({
  license: {
    domain: "example.com", // The domain name that you specified when you apply for a license.
    key: "example-key" // The license key that is displayed in the console after you apply for the license.
  }
});
```

Instantiate the player.

Add the following sample code under the <script> tag:

Play on-demand videos

Playback based on URLs

To play videos from URLs, you must set the source parameter to the playback URL. You can specify the playback URL of an audio or video file stored in a third-party VOD service or in ApsaraVideo VOD.

You can call the GetPlayInfo operation to obtain the playback URL of a media file stored in ApsaraVideo VOD. We recommend that you use ApsaraVideo VOD SDKs to obtain media playback URLs. This frees you from complex signature calculations. For more information about the GetPlayInfo operation, visit OpenAPI Explorer.

var player = new Aliplayer({
        id: 'J_prismPlayer',
        source: '<your play URL>', // The playback URL of an audio or video file stored in a third-party VOD service or in ApsaraVideo VOD. 
      },function(player){
        console.log('The player is created.')
     });

Playback based on VID and PlayAuth

To play videos based on VID and PlayAuth, you must set the vid parameter to the audio or video ID and set the playauth parameter to the playback credential.

After you upload an audio or video file, you can log on to the ApsaraVideo VOD console and choose Media Files > Audio/Video to view the ID of the audio or video file. Alternatively, you can call the SearchMedia operation provided by the ApsaraVideo VOD SDK to obtain the ID.
You can call the GetVideoPlayAuth operation to obtain the playback credential. We recommend that you integrate ApsaraVideo VOD SDKs to obtain credentials for media playback in ApsaraVideo VOD. This frees you from complex signature calculations. For more information about the GetVideoPlayAuth operation, visit OpenAPI Explorer.

We recommend that you use this playback method. Compared with video playback based on Security Token Service (STS), VidAuth-based playback is easier to use and more secure. For more information about the comparison between the two playback methods, see Comparison between credentials and STS.

var player = new Aliplayer({
           id: 'J_prismPlayer',
           width: '100%',
           vid : '<your video ID>', // Required. The ID of the audio or video file. Example: 1e067a2831b641db90d570b6480f****. 
           playauth : '<your PlayAuth>', // Required. The playback credential. 
           // authTimeout: 7200, // The validity period of the playback URL. Unit: seconds. Default value: 7200. If you have configured a validity period for signed URLs in the ApsaraVideo VOD console, the configuration of this parameter takes precedence. If you leave this parameter empty, the default value is used. The validity period must be longer than the actual duration of the video. Otherwise, the playback URL expires before the playback is complete. 
         },function(player){
           console.log('The player is created.')
        });

Playback based on STS

If you use STS-based playback, a temporary STS token rather than a playback credential is used. In this case, you need to call the AssumeRole operation to obtain an STS token in advance. For more information, see Use STS to upload videos.

var player = new Aliplayer({
       id: 'J_prismPlayer',
       width: '100%',
       vid : '<your video ID>', // Required. After you upload an audio or video file, you can log on to the ApsaraVideo VOD console and choose Media Files > Audio/Video to view the ID of the audio or video file. Alternatively, you can call the SearchMedia operation provided by the ApsaraVideo VOD SDK to obtain the ID. Example: 1e067a2831b641db90d570b6480f****. 
       accessKeyId: '<your AccessKey ID>', // Required. The AccessKey ID is returned when the temporary STS token is generated. 
       securityToken: '<your STS token>', // Required. The STS token. To obtain an STS token, call the AssumeRole operation. 
       accessKeySecret: '<your AccessKey Secret>', // Required. The AccessKey secret is returned when the temporary STS token is generated. 
       region: '<region of your video>', // Required. The ID of the region in which the media asset resides, such as cn-shanghai, eu-central-1, or ap-southeast-1. 
       // authTimeout: 7200, // The validity period of the playback URL. Unit: seconds. Default value: 7200. If you have configured a validity period for signed URLs in the ApsaraVideo VOD console, the configuration of this parameter takes precedence. If you leave this parameter empty, the default value is used. The validity period must be longer than the actual duration of the video. Otherwise, the playback URL expires before the playback is complete. 
     },function(player){
       console.log('The player is created.')
       });

Encrypted playback

ApsaraVideo VOD supports Alibaba Cloud proprietary cryptography and digital rights management (DRM) encryption. For more information, see Play an encrypted video.

Play live streams

URL-based live streaming

To stream content from URLs, you must set the source parameter to the streaming URL and the isLive parameter to true.

You can specify the streaming URL of a live stream in a third-party live streaming service or in ApsaraVideo Live. The ApsaraVideo Live console provides a URL generator to help you generate streaming URLs. For more information, see URL generator.

<script>
  var player = new Aliplayer({
    id: 'J_prismPlayer',
    source: '<your play URL>', // The streaming URL can be a third-party streaming URL or a streaming URL that is generated in ApsaraVideo Live. 
    isLive: true, // Specifies whether to play live streams. 
    },function(player){
      console.log('The player is created.')
    });
</script>

DRM-encrypted live streaming

For more information about DRM-encrypted live streaming, see Play an encrypted video.

Real-Time Streaming (RTS)

RTS allows you to play videos from URLs without the need to configure additional parameters.

You can use the URL generator in the ApsaraVideo Live console to generate an RTS URL. For more information, see URL generator.
ApsaraVideo Player implements RTS playback by integrating the RTS SDK. By default, the latest version of the RTS SDK is integrated. You can also specify the RTS SDK version by configuring the parameter. For example, specify rtsVersion: '2.2.1'.
If your browser does not support RTS or stream pulling over RTS fails, the system automatically plays the stream over a degraded protocol such as HTTP Live Streaming (HLS) or HTTP Flash Video (HTTP-FLV). If your browser supports FLV, the system plays the stream over FLV first.

<script>
var player = new Aliplayer({
    id: 'J_prismPlayer',
    source: '<your play URL>', // The RTS playback URL. The artc:// protocol is used. // 
    isLive: true, // Specifies whether to play live streams. 
    // rtsFallback: false, //Optional. Specifies whether to enable the RTS playback degradation feature. Default value: true.
    // rtsFallbackType: 'HLS', //Optional. The degraded protocol that you want to use. You can specify HLS or FLV. 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: '<your play URL>', // Optional. The degraded protocol that you want to use.
    // rtsVersion: 'x.x.x', // Optional. The version of the RTS SDK. 
},function(player){
    console.log('The player is created.')
});
// The event that is triggered when a stream is pulled over RTS. Listen for this event to obtain the TraceId.   In the event callback, traceId indicates the TraceId that is used for stream pulling and source indicates the playback URL of the RTS stream. 
player.on('rtsTraceId', function(event) {
    console.log('EVENT rtsTraceId', event.paramData);
})
// The event that is triggered when a degraded protocol is used for playback. reason indicates the degradation cause and fallbackUrl indicates the alternative URL. 
player.on('rtsFallback', function(event) {
    console.log(' EVENT rtsFallback', event.paramData);
})
</script>

FAQ

How do I integrate ApsaraVideo Player SDK for Web in a Vue project?

ApsaraVideo Player SDK for Web provides you with the source code of the demo for integrating ApsaraVideo Player SDK for Web with the Vue framework. For more information about the demo, see Online trial and source code of demos.

For more information, see FAQ about ApsaraVideo Player SDK for Web.

ApsaraVideo VOD:Quick integration