This topic describes how to quickly start video playback using the HarmonyOS player SDK, including creating a player, setting the display view, configuring a playback source, and controlling the playback flow.-ApsaraVideo VOD(VOD)-阿里云帮助中心

This topic describes how to get started with video playback using the HarmonyOS player software development kit (SDK).

Prerequisites

You have successfully completed the SDK integration for the HarmonyOS player.

Procedure

Step 1: Create the player

Create an AliPlayer object.

// Import player-related definitions from the SDK's HAR package.
import { AliPlayerFactory, AliPlayer } from 'premierlibrary';
// Create a player object. 
// 'traceId' is optional.
private mAliPlayer: AliPlayer = AliPlayerFactory.createAliPlayer(getContext(), 'traceId');
// Pass the traceId.
mAliPlayer.setTraceId("traceId");

Note

The player's features, such as playback quality monitoring, single-point tracking, and video playback statistics, rely on the instrumentation log reporting feature. Playback quality monitoring provides data on overall playback quality. Single-point tracking helps locate specific users or devices to analyze playback behavior and quickly identify issues.

When you create the player, the available features depend on how you set the setTraceID parameter:

If you do not pass the setTraceID parameter (default): The instrumentation log reporting feature is enabled. You can use playback quality monitoring and video playback statistics, but not single-point tracking.
If you pass a traceid to the setTraceID parameter: The traceid is a unique identifier that you define for a user or device, such as your business's user ID or a device ID such as an International Mobile Equipment Identity (IMEI) or identifier for advertisers (IDFA). When you pass a traceid, the instrumentation log reporting feature is enabled. You can then use playback quality monitoring, single-point tracking, and video playback statistics.
If you set the setTraceID parameter to DisableAnalytics: The instrumentation log reporting feature is disabled. You cannot use playback quality monitoring, single-point tracking, or video playback statistics.

Step 2: Set the display view

Attach the player to a HarmonyOS XComponent widget to render the video.

XComponent({
  id: '0', // Unique XComponent ID
  type: XComponentType.SURFACE,
  libraryname: 'premierlibrary',
  controller: this.xComponentController
})
  .onLoad(async () => {
    // Set the playback source and control playback.
    
    // (Required) Attach the URL and XC_SurfaceId.
    this.mAliPlayer.setSurfaceId('0'); // The surface ID corresponds to the XComponent ID.      
  })
  .width('100%')
  .height(200)

Important

The XComponent must load the player's SO file using `libraryname: 'premierlibrary'`. You must also specify a unique ID to distinguish different XComponent widgets and prevent video rendering conflicts.

Step 3: Set the playback source

Play using VidAuth (Recommended)

let vidAuth: VidAuth = new VidAuth();
vidAuth.setVid("your_video_id");// Required. The video ID.
vidAuth.setPlayAuth("<yourPlayAuth>");// Required. The playback credential. You must call the GetVideoPlayAuth operation of ApsaraVideo VOD to generate the credential.
vidAuth.setRegion("your_region_id");// Optional. The default value is cn-shanghai.
// vidAuth.setAuthTimeout(3600); // The validity period of the playback URL in seconds. This overwrites the validity period of URL signing that is set in the ApsaraVideo VOD console. If you do not set this parameter, the default value of 3600 is used. If you set this parameter, make sure that the validity period is longer than the video duration to prevent the playback URL from expiring before playback is complete.
mAliPlayer.setVidAuthDataSource(vidAuth);

Play using VidSts

let vidSts: VidSts = new VidSts();
vidSts.setVid("your_video_id");// Required. The video ID.
vidSts.setAccessKeyId("<yourAccessKeyId>");// Required. The AccessKey ID of the temporary AccessKey pair. You must call the AssumeRole operation of Security Token Service (STS) to generate the AccessKey ID.
vidSts.setAccessKeySecret("<yourAccessKeySecret>");// Required. The AccessKey secret of the temporary AccessKey pair. You must call the AssumeRole operation of STS to generate the AccessKey secret.
vidSts.setSecurityToken("<yourSecurityToken>");// Required. The Security Token Service (STS) token. You must call the AssumeRole operation of STS to generate the token.
vidSts.setRegion("your_region_id"); // Optional. The default value is cn-shanghai.
// vidSts.setAuthTimeout(3600); // The validity period of the playback URL in seconds. This overwrites the validity period of URL signing that is set in the ApsaraVideo VOD console. If you do not set this parameter, the default value of 3600 is used. If you set this parameter, make sure that the validity period is longer than the video duration to prevent the playback URL from expiring before playback is complete.
mAliPlayer.setVidStsDataSource(vidSts);

Play using UrlSource

// Create a playback source object and set the playback URL.
let urlSource: UrlSource = new UrlSource();
// Required.
urlSource.setUri("your_playback_url");
mAliPlayer.setUrlDataSource(urlSource);

Note

For more information about how to set a playback source, see Basic Features.

Step 4: Start playback

// Prepare for playback.
mAliPlayer.prepare();
// Start playback.
mAliPlayer.start();

Step 5: End playback

// Stop playback.
mAliPlayer.stop();
// Destroy the player object.
mAliPlayer.release();

References

For more information about basic player features, such as playback control and event listeners, see Basic Features.