Integrate the SDK

Feature list

The main features of the current version are as follows:

Demo and best practices

Get the demo

Best practices for HarmonyOS Next integration

To reduce the learning and development costs of integrating the Player SDK for HarmonyOS Next, we recommend that you download the demo and read the ReadMe.md file in the project directory. Follow the instructions in the file to implement the recommended best practices. The demo currently includes the following common video playback scenarios:

• The simplest connection type.

• Implementation of a custom VideoComponent component for reuse in multiple scenarios.

• Multi-instance playback solution.

• UI practices such as playback control, full screen, and gesture-based adjustments.

• List playback solution for short video swipe-to-play scenarios.

Prerequisites

Video tutorial

Integrate the SDK

Get the SDK

To download the SDK, see Release notes for the HarmonyOS SDK.

Configure the SDK

The HAR package is in the following location:

Configure dependencies in the oh-package.json5 file:

"dependencies": {
  "premierlibrary": "file:../amdemos-player-ohos-listapp/libs/premierlibrary.har",
}

Configure the license

1. Manage license authorization.

2. After the authorization is granted, copy the obtained license certificate file to your DevEco Studio project. We recommend that you place the file in the rawfile directory.

3. Add the following fields to the module.json5 file.

   • The key is com.aliyun.alivc_license.licensekey (all lowercase), and the value is the LicenseKey.

   • The key is com.aliyun.alivc_license.licensefile (all lowercase), and the value is the path where the certificate file from Step 2 is stored. Specify the path as required.

     "metadata": [
       {
         "name": "com.aliyun.alivc_license.licensekey",
         "value": "********"
       },
       {
         "name": "com.aliyun.alivc_license.licensefile",
         "value": "license.crt"
       },
     ]

Play a video

1. Create a player.

   // Download the demo project and see the ReadMe.md file for best practices to help you quickly complete the integration.
   
   // Import player-related definitions from the SDK HAR package.
   import { AliPlayerFactory, AliPlayer } from 'premierlibrary';
   
   // Create a player instance.
   const player: AliPlayer = AliPlayerFactory.createAliPlayer(getContext(), traceId);
   
   // Create a list player for swipe-to-play scenarios.
   const listPlayer: AliListPlayer = AliPlayerFactory.createAliListPlayer(getContext(), traceId);
   
   // getContext() is a HarmonyOS system function. traceId is a unique session ID specified by the service. It can be an empty string '' or null.

2. Set the player callback listener.

   // Download the demo project and see the ReadMe.md file for best practices to help you quickly complete the integration.
   
   // Import player event callback type definitions as needed.
   import { OnPreparedListener, OnCompletionListener, OnAudioInterruptEventListener,OnErrorListener,OnInfoListener,OnLoadingStatusListener, AudioStatus } from 'premierlibrary/src/main/ets/com/aliyun/player/IPlayer';
   
   // Player instance.
   const player: AliPlayer = AliPlayerFactory.createAliPlayer(getContext(), traceId);
   
   // Define the callback listener.
   const mPreparedEventHandler: OnPreparedListener = { // onPrepared is complete.
     onPrepared: () => {
       console.log("prepared");
     }
   };
   const mCompletionEventHandler: OnCompletionListener = { // Playback is complete.
     onCompletion: () => {
       console.log("play complete");
     }
   }
   const mOnAudioInterruptListener: OnAudioInterruptEventListener = { // Audio interruption.
     onAudioInterruptEvent: (audioStatus: AudioStatus) => {
       if (player) {
         console.log("[HOS DEMO] [AUDIO INTERRUPT]: " + audioStatus);
         let statusInfo: string = "";
         switch (audioStatus) {
           case AudioStatus.AUDIO_STATUS_DEFAULT:
             statusInfo = "AUDIO_STATUS_DEFAULT"
             break;
           case AudioStatus.AUDIO_STATUS_RESUME:
             statusInfo = "AUDIO_STATUS_RESUME"
             player.start(); // Resume playback.
             break;
           case AudioStatus.AUDIO_STATUS_PAUSE:
             statusInfo = "AUDIO_STATUS_PAUSE"
             player.pause(); // Pause playback.
             break;
           case AudioStatus.AUDIO_STATUS_STOP:
             statusInfo = "AUDIO_STATUS_STOP"
             player.stop(); // Stop playback.
             break;
           case AudioStatus.AUDIO_STATUS_DUCK:
             statusInfo = "AUDIO_STATUS_DUCK"
             break;
           case AudioStatus.AUDIO_STATUS_UNDUCK:
             statusInfo = "AUDIO_STATUS_UNDUCK"
             break;
           default:
             break;
         }
         showToast("CALLBACK: onAudioInterrupt " + statusInfo);
       }
     }
   }
   const mOnErrorEventListener: OnErrorListener = { // Error callback.
     onError:(errorInfo) => {
       let errorCode:PlayerErrorCode = errorInfo.getCode(); // Error code.
       let errorMsg:string = errorInfo.getMsg(); // Error description.
       // errorExtra provides additional error information in a JSON string format. Example:
       // { "Url": "xxx",
    		//	"Module": "NetWork",
     	//	"ModuleCode": "-377",
    		//  "ModuleMessage": "Redirect to a url that is not a media"}
       // Note that ModuleCode is not always the same as errorCode.
       let errorExtra:string = errorInfo.getExtra();
       
       // After an error occurs, stop the player.
       player.stop();
     }
   }
   const mOnVideoInfo: OnInfoListener = { // Video information callback.
     // Information from the player, including the current progress and buffer position.
     onInfo: (bean: InfoBean) => {
       // Current progress: InfoCode.CurrentPosition
       // Current buffer position: InfoCode.BufferedPosition
       if (bean.getCode() === InfoCode.CurrentPosition) {
         this.videoProgress = bean.getExtraValue() / this.mVideoDuration * 100;
         this.mDuration = CommonUtils.getDurationString(this.mVideoDuration, bean.getExtraValue());
       } else if (bean.getCode() === InfoCode.BufferedPosition) {
         this.buffer = CommonUtils.secondToTime(Math.floor(bean.getExtraValue() / 1000));
         this.bufferedProgress = bean.getExtraValue() / this.mVideoDuration * 100;
       }
     }
   }
   const mOnLoadingProgressEventListener: OnLoadingStatusListener = { // Callback for loading and stuttering states.
     onLoadingBegin: () => {
         // Starts loading. The video and audio are insufficient for playback.
         // A loading spinner is usually displayed here.
     },
     onLoadingProgress: (percent: number, netSpeed: number) => {
        // Loading progress. Percentage and network speed.
     },
     onLoadingEnd: () => {
         // Finishes loading. The video and audio are ready for playback.
         // The loading spinner is usually hidden here.
     }
   }
   
   // Register the listener with the player instance.
   player.setOnPreparedListener(mPreparedEventHandler);
   player.setOnCompletionListener(mCompletionEventHandler);
   player.setOnAudioInterruptEventListener(mOnAudioInterruptListener);
   player.setOnErrorListener(mOnErrorEventListener);
   player.setOnInfoListener(mOnVideoInfo);
   player.setOnLoadingStatusListener(mOnLoadingProgressEventListener);

3. Set the playback method.

   • The Player SDK for HarmonyOS NEXT supports four VOD playback methods: UrlSource, VidAuth (recommended for ApsaraVideo VOD users), VidSts, and encrypted playback.

   • The Player SDK for HarmonyOS NEXT supports only one live playback method: UrlSource.

   Note

   • UrlSource plays a video directly from a URL. VidSts and VidAuth play a video using its video ID (VID).

   • For information about how to set the region, see VOD region IDs.

   VOD playback

   VOD playback using UrlSource

   To play a VOD video using the UrlSource method, set the setUrl property of the player to the playback URL.

   • Playback URL in ApsaraVideo VOD: You can call the GetPlayInfo operation to obtain the URL. We recommend that you integrate the ApsaraVideo VOD server-side SDK to obtain audio and video playback URLs. This saves you the trouble of signing the URLs. For an example of how to call the operation to obtain audio and video playback URLs, see Developer Portal.

   • Local video URL: Make sure that you have the required access permissions. You can obtain the full path of an accessible local video file using a system API, such as /sdcard/xxx/xxx/xxx.mp4 or content://xxx/xxx/xx.mp4.

   import { AliPlayerFactory, AliPlayer } from 'premierlibrary';
   import { UrlSource } from 'premierlibrary/src/main/ets/com/aliyun/player/source/UrlSource';
   @Preview
   @Component
   export struct MyPlayerComponent {
     private videoUrl: string = 'HTTP playback URL';
     private aliPlayer: AliPlayer = AliPlayerFactory.createAliPlayer(getContext(), '');
     playByUrl() {
       let urlSource: UrlSource = new UrlSource();
       urlSource.setUri(this.videoUrl);// Required. The playback URL. The URL can be a third-party VOD URL, a playback URL from ApsaraVideo VOD, or a local video URL.
       this.aliPlayer.setUrlDataSource(urlSource);
     }
   }

   VOD playback using VidAuth (Recommended)

   To play a VOD video using the VidAuth method, set the vid property of the player to the audio or video ID and the playauth property to the audio or video playback credential.

   • Audio or video ID: You can obtain the ID from the console (choose Media Library > Audio/Video) or by calling a server-side API operation (SearchMedia) after the audio or video is uploaded.

   • Audio or video playback credential: You can call the GetVideoPlayAuth operation to obtain the credential. We recommend that you integrate the ApsaraVideo VOD server-side SDK to obtain audio and video playback credentials. This saves you the trouble of signing the URLs. For an example of how to call the operation to obtain an audio or video playback credential, see Developer Portal.

   We recommend that ApsaraVideo VOD users use this playback method. Compared with the STS method, the PlayAuth method is easier to use and more secure. For a detailed comparison, see Comparison between the credential-based method and the STS-based method.

   import { AliPlayerFactory, AliPlayer, VidAuth } from 'premierlibrary';
   interface IAuthInfo { videoId: string, playAuth: string }
   @Preview
   @Component
   export struct MyPlayerComponent {
     private authInfo: IAuthInfo = {
       videoId: 'VOD video ID',
       playAuth: 'playauth',
     };
     private aliPlayer: AliPlayer = AliPlayerFactory.createAliPlayer(getContext(), '');
     playByVidAndAuth() {
       const vidAuthSource: VidAuth = new VidAuth();
       vidAuthSource.setVid(this.authInfo.videoId);// Required. The video ID.
       vidAuthSource.setPlayAuth(this.authInfo.playAuth);// Required. The playback credential. You must call the GetVideoPlayAuth operation of ApsaraVideo VOD to generate the credential.
       this.aliPlayer.setVidAuthDataSource(vidAuthSource);
     }
   }

   VOD playback using VidSts

   Playing a VOD video using the VidSts method means using a temporary STS credential instead of a VOD audio or video playback credential. You must obtain an STS token and a temporary STS AccessKey pair (AccessKey ID and AccessKey secret) in advance. For more information, see Obtain an STS token.

   import { AliPlayerFactory, AliPlayer, VidSts } from 'premierlibrary';
   interface ISTSInfo { videoId: string, accessKeyId: string, securityToken: string, accessKeySecret: string, region: string }
   @Preview
   @Component
   export struct MyPlayerComponent {
     private stsInfo: ISTSInfo = {
       videoId: 'VOD video ID',
       accessKeyId: 'STS-accessKeyId',
       securityToken: 'STS-token',
       accessKeySecret: 'STS-accessKeySecret',
       region: 'regionId'
     };
     private aliPlayer: AliPlayer = AliPlayerFactory.createAliPlayer(getContext(), '');
     playByVidAndSTS() {
       const vidStsSource: VidSts = new VidSts();
       vidStsSource.setVid(this.stsInfo.videoId);// Required. The video ID.
       vidStsSource.setAccessKeyId(this.stsInfo.accessKeyId);// Required. The AccessKey ID of the temporary STS AccessKey pair. You must call the AssumeRole operation of STS to generate the AccessKey ID.
       vidStsSource.setAccessKeySecret(this.stsInfo.accessKeySecret);// Required. The AccessKey secret of the temporary STS AccessKey pair. You must call the AssumeRole operation of STS to generate the AccessKey secret.
       vidStsSource.setSecurityToken(this.stsInfo.securityToken);// Required. The STS token. You must call the AssumeRole operation of STS to generate the token.
       vidStsSource.setRegion(this.stsInfo.region);// Required. The region where ApsaraVideo VOD is activated. Default value: cn-shanghai.
       this.aliPlayer.setVidStsDataSource(vidStsSource);
     }
   }

   Encrypted VOD playback

   ApsaraVideo VOD supports HLS encryption and Alibaba Cloud proprietary cryptography. For more information about encrypted playback, see Play an encrypted video.

   Live video playback

   Live playback using UrlSource

   To play a live video using the UrlSource method, set the setUrl property of the player to the live stream pulling URL. The playback URL can be a third-party live streaming URL or a stream pulling URL from ApsaraVideo Live.

   You can use the URL generator in the ApsaraVideo Live console to generate a stream pulling URL. For more information, see URL generator.

   import { AliPlayerFactory, AliPlayer } from 'premierlibrary';
   import { UrlSource } from 'premierlibrary/src/main/ets/com/aliyun/player/source/UrlSource';
   @Preview
   @Component
   export struct MyPlayerComponent {
     private videoUrl: string = 'live playback URL';
     private aliPlayer: AliPlayer = AliPlayerFactory.createAliPlayer(getContext(), '');
     playByUrl() {
       let urlSource: UrlSource = new UrlSource();
       urlSource.setUri(this.videoUrl);// The playback URL. The URL can be a third-party live streaming URL or a stream pulling URL from ApsaraVideo Live.
       this.aliPlayer.setUrlDataSource(urlSource);
     }
   }

4. Bind the player to a HarmonyOS XComponent component to render the video.

   // We recommend that you download and view the atomic integration solution in the demo's best practices.
   // The following code is an example of a @Component component in the HarmonyOS ArkTS environment.
   
   /**
    * Atomic integration of the HarmonyOS Player SDK.
    * This is the simplest integration method based on the underlying HarmonyOS XC capability, providing high flexibility for custom development.
    * Three steps to implement video playback.
    */
   
   import { AliPlayerFactory, AliPlayer } from 'premierlibrary';
   import { UrlSource } from 'premierlibrary/src/main/ets/com/aliyun/player/source/UrlSource';
   
   @Preview
   @Component
   export struct MyPlayerComponent {
   
     private videoUrl: string = 'HTTP playback URL';
     private xComponentController = new XComponentController();
     private aliPlayer: AliPlayer = AliPlayerFactory.createAliPlayer(getContext(), '');
   
     build() {
       XComponent({
         id: '0', // unique XC id
         type: XComponentType.SURFACE,
         libraryname: 'premierlibrary',
         controller: this.xComponentController
       })
       .onLoad(async () => {
   
         // Prepare the URL object.
         let urlSource: UrlSource = new UrlSource();
         urlSource.setUri(this.videoUrl);
   
         // Bind the URL and XC_SurfaceId.
         this.aliPlayer.setUrlDataSource(urlSource);
         this.aliPlayer.setSurfaceId('0'); // The surface ID corresponds to the XC ID.
   
         // Play the video.
         this.aliPlayer.setAutoPlay(true);
         this.aliPlayer.prepare();
       })
       .width('100%')
       .height(200)
     }
   
     aboutToDisappear(): void {
       if (this.aliPlayer) {
         this.aliPlayer.stop();
         this.aliPlayer.release();
       }
     }
   }

   Important

   XComponent needs to load the player SO file using `libraryname: 'premierlibrary'`. You must also specify a unique ID to differentiate between XComponent instances and prevent video rendering conflicts.

5. Optional: Enable autoplay. This feature is disabled by default.

   // player is the player instance.
   player.setAutoPlay(true);

6. Prepare for playback. Call `prepare()` to start reading and parsing data. If autoplay is enabled, the video starts playing automatically after the data is parsed.

   // player is the player instance.
   player.prepare();

7. Start playback. Call the `start` method to start playing the video.

   // player is the player instance.
   player.start();

API reference

For a standard player, use the interfaces provided by IPlayer. You can read the IPlayer file from the HAR package.

The current IPlayer code is as follows:

import { ErrorInfo } from './bean/ErrorInfo';
import { InfoBean } from './bean/InfoBean';
import { PlayerConfig } from './nativeclass/PlayerConfig';

/**
 * Unknown status.
 */
export const unKnow: number = -1;

/**
 * Idle. The player enters this state after it is created.
 */
export const idle: number = 0;

/**
 * Initialized. The player enters this state after a media source is specified.
 */
export const initalized: number = 1;

/**
 * Prepared.
 */
export const prepared: number = 2;

/**
 * The player is playing video or audio.
 */
export const started: number = 3;

/**
 * The player is paused.
 */
export const paused: number = 4;

/**
 * The player is stopped.
 */
export const stopped: number = 5;

/**
 * The player has completed playing the video or audio.
 */
export const completion: number = 6;

/**
 * The player has an error.
 */
export const error: number = 7;

export interface IPlayer {
  /**
   * Starts playback.
   */
  start: () => void;

  /**
   * Pauses playback.
   */
  pause: () => void;

  /**
   * Stops playback.
   */
  stop: () => void;

  /**
   * Enables or disables autoplay. If autoplay is enabled, the {@link OnPreparedListener} callback is not received.
   *
   * @param isAutoPlay Specifies whether to enable autoplay. Default value: false.
   */
  setAutoPlay: (isAutoPlay: boolean) => void;

  /**
   * Prepares the player. Call {@link OnPreparedListener} to return success messages. Call {@link OnErrorListener} to return error messages.
   */
  prepare: () => void;

  /**
   * Sets the surfaceId to bind the player's display surface with an XComponent. The XComponent ID of different XComponents must be unique.
   *
   * @param surfaceId The XComponent ID.
   */
  setSurfaceId: (surfaceId: string) => void;

  /**
   * Sets the playback speed.
   *
   * @param speed Valid values: [0.5, 5].
   */
  setSpeed: (speed: number) => void;

  /**
   * Sets the volume of the player, not the system volume. The range is 0.0 to 2.0. If the volume is greater than 1.0, noise may occur. We do not recommend this.
   *
   * @param volume Valid values: [0, 1].
   */
  setVolume: (volume: number) => void;

  /**
   * Queries the volume of the player.
   *
   * @return Valid values: [0, 1].
   */
  getVolume: () => number;

  /**
   * Seeks to a position. This is not an accurate seek.
   *
   * @param position The position in milliseconds.
   */
  seekTo: (position: number, mode: number) => void;

  /**
   * Queries the total duration.
   *
   * @return The total duration in milliseconds.
   */
  getDuration: () => number;

  /**
   * Queries the current playback position.
   *
   * @return The playback position in milliseconds.
   */
  getCurrentPosition: () => number;

  /**
   * Queries the buffer progress position. Note the difference between this method and {@link OnLoadingStatusListener}.
   *
   * @return The buffer progress position in milliseconds.
   */
  getBufferedPosition: () => number;

  /**
   * Enables or disables hardware decoding.
   *
   * @param enabled Set to true to enable hardware decoding or false to disable it.
   */
  enableHardwareDecoder: (enabled: boolean) => void;

  /**
   * Releases the player.
   */
  release: () => void;

  /**
   * Mutes the player.
   *
   * @param mute Set to true to mute the player. Default value: false.
   */
  setMute: (mute: boolean) => void;

  /**
   * Queries whether the player is muted.
   *
   * @return Returns true if the player is muted. Default value: false.
   */
  isMuted: () => boolean;

  /**
   * Sets the scaling mode.
   *
   * @param mode The scaling mode. Default value: {@link ScaleMode#SCALE_TO_FILL}. For more information, see {@link ScaleMode}.
   */
  setScaleMode: (mode: ScaleMode) => void;

  /**
   * Queries the scaling mode.
   *
   * @return The scaling mode. Default value: {@link ScaleMode#SCALE_TO_FILL}.
   */
  getScaleMode: () => ScaleMode;

  /**
   * Enables or disables loop playback. If a local cache exists, the next loop plays the local file.
   *
   * @param on Set to true to enable loop playback. It is disabled by default.
   */
  setLoop: (on: boolean) => void;

  /**
   * Queries whether loop playback is enabled.
   *
   * @return Returns true if loop playback is enabled. It is disabled by default.
   */
  isLoop: () => boolean;

  /**
   * Queries the video width.
   *
   * @return The video width.
   */
  getVideoWidth: () => number;

  /**
   * Queries the video height.
   *
   * @return The video height.
   */
  getVideoHeight: () => number;

  /**
   * Queries the video rotation angle.
   *
   * @return The video rotation angle.
   */
  getVideoRotation: () => number;

  /**
   * Reloads the player. For example, you can reload the player when a network timeout occurs.
   */
  reload: () => void;

  /**
   * Sets the rotation mode.
   *
   * @param mode The rotation mode. For more information, see {@link RotateMode}.
   */
  setRotateMode: (mode: RotateMode) => void;

  /**
   * Queries the rotation mode.
   *
   * @return The rotation mode. For more information, see {@link RotateMode}.
   */
  getRotateMode: () => RotateMode;

  /**
   * Sets the mirroring mode.
   *
   * @param mode The mirroring mode. For more information, see {@link MirrorMode}.
   */
  setMirrorMode: (mode: MirrorMode) => void;

  /**
   * Queries the mirroring mode.
   *
   * @return The mirroring mode. For more information, see {@link MirrorMode}.
   */
  getMirrorMode: () => MirrorMode;

  /**
   * Sets the background color of the video.
   *
   * @param color ARGB.
   *
   */
  setVideoBackgroundColor: (color: number) => void;

  /**
   * Queries the playback speed.
   *
   * @return The playback speed. Valid values: [0.5, 5].
   */
  getSpeed: () => number;

  /**
   * Queries whether autoplay is enabled.
   *
   * @return Returns true if autoplay is enabled. It is disabled by default.
   */
  isAutoPlay: () => boolean;
  /**
   * Sets the player configuration.
   *
   * @param config The player configuration. For more information, see {@link PlayerConfig}.
   */
  setConfig: (config:PlayerConfig) => void;

  /**
   * Queries the player configuration.
   *
   * @return The player configuration.
   */
  getConfig: () => PlayerConfig | undefined;

  getNativeContextAddr: () => number;

  /**
   * Sets a preparation success notification. If the preparation fails, {@link OnErrorListener} is notified.
   *
   * @param l The preparation success notification.
   */
  setOnPreparedListener: (l: OnPreparedListener) => void;

  /**
   * Sets a rendering start notification. You can listen for the first frame display event to hide the thumbnail and perform other functions.
   *
   * @param l The rendering start notification.
   */
  setOnRenderingStartListener: (l: OnRenderingStartListener) => void;

  /**
   * Sets a player state change notification.
   *
   * @param l The player state change notification.
   */
  setOnStateChangedListener: (l: OnStateChangedListener) => void;

  /**
   * Sets a playback completion notification. Note: This notification is not sent during loop playback.
   *
   * @param l The playback completion notification.
   */
  setOnCompletionListener: (l: OnCompletionListener) => void;

  /**
   * Sets a loading status notification.
   *
   * @param l The loading status notification.
   */
  setOnLoadingStatusListener: (l: OnLoadingStatusListener) => void;

  /**
   * Sets an error notification.
   *
   * @param l The error notification.
   */
  setOnErrorListener: (l: OnErrorListener) => void;

  /**
   * Sets an information listener.
   *
   * @param l The information listener.
   */
  setOnInfoListener: (l: OnInfoListener) => void;

  /**
   * Sets a video size change notification.
   *
   * @param l The video size change notification.
   */
  setOnVideoSizeChangedListener: (l: OnVideoSizeChangedListener) => void;

  /**
   * Sets a seek completion notification.
   *
   * @param l The seek completion notification.
   */
  setOnSeekCompleteListener: (l: OnSeekCompleteListener) => void;

  /**
   * Sets a subtitle display notification.
   *
   * @param l The subtitle display notification.
   */
  setOnSubtitleDisplayListener: (l: OnSubtitleDisplayListener) => void;

  /**
   * Sets the video rendering callback.
   * @param l The video rendering callback. See {@linkplain OnVideoRenderedListener}.
   */
  setOnVideoRenderedListener: (l: OnVideoRenderedListener) => void;
}

/**
 * Preparation success notification.
 */
export interface OnPreparedListener {
  /**
   * The preparation is successful.
   */
  onPrepared: () => void;
}

/**
 * Information notification.
 */
export interface OnInfoListener {
  /**
   * Information.
   *
   * @param infoBean The information object. See {@linkplain InfoBean}.
   */
  onInfo: (infoBean: InfoBean) => void;
}

/**
 * Rendering start notification.
 */
export interface OnRenderingStartListener {
  /**
   * Rendering starts.
   */
  onRenderingStart: () => void;
}

/**
 * Player state change notification.
 */
export interface OnStateChangedListener {
  /**
   * The state changes.
   *
   * @param newState The new state.
   */
  onStateChanged: (newState: number) => void;
}

/**
 * Playback completion notification.
 */
export interface OnCompletionListener {
  /**
   * Playback is complete.
   */
  onCompletion: () => void;
}

/**
 * Loading status notification.
 */
export interface OnLoadingStatusListener {
  /**
   * Starts loading.
   */
  onLoadingBegin: () => void;

  /**
   * Loading progress.
   *
   * @param percent The percentage, [0, 100].
   * @param netSpeed The current network speed in kbit/s.
   */
  onLoadingProgress: (percent: number, netSpeed: number) => void;

  /**
   * Loading is complete.
   */
  onLoadingEnd: () => void;
}

/**
 * Error notification.
 */
export interface OnErrorListener {
  /**
   * An error occurs.
   *
   * @param errorInfo The error information.
   */
  onError: (errorInfo: ErrorInfo) => void;
}

/**
 * Video size change notification.
 */
export interface OnVideoSizeChangedListener {
  /**
   * The video size changes.
   *
   * @param width The width.
   * @param height The height.
   */
  onVideoSizeChanged: (width: number, height: number) => void;
}

/**
 * Seek completion notification.
 */
export interface OnSeekCompleteListener {
  /**
   * Seeking is complete.
   */
  onSeekComplete: () => void;
}

/**
 * Subtitle display notification.
 */
export interface OnSubtitleDisplayListener {

  /**
   * An external subtitle is added.
   * @param trackIndex The stream ID.
   * @param url The subtitle URL.
   */
  onSubtitleExtAdded: (trackIndex: number, url: string) => void;

  /**
   * Displays subtitles.
   *
   * @param tackIndex The stream ID.
   * @param id The index.
   * @param data The content.
   */
  onSubtitleShow: (trackIndex: number, id: number, data: string) => void;

  /**
   * Hides subtitles.
   * @param trackIndex The stream ID.
   * @param id The subtitle ID.
   */
  onSubtitleHide: (trackIndex: number, id: number) => void;

  /**
   * Subtitle header information.
   * @param trackIndex The stream ID.
   * @param header The header information.
   */
  onSubtitleHeader: (trackIndex: number, header: string) => void;
}

/**
 * Video rendering callback.
 */
export interface OnVideoRenderedListener {
  /**
   * A video frame is rendered.
   * @param timeMs The time point of rendering.
   * @param pts The PTS of rendering.
   */
  onVideoRendered: (timeMs: number, pts: number) => void;
}

export enum IPResolveType {
  /**
   * Any type.
   */
  IpResolveWhatEver,
  /**
   * Use only IPv4.
   */
  IpResolveV4,
  /**
   * Use only IPv6.
   */
  IpResolveV6
}

export enum ScaleMode {
  /**
   * Fit with aspect ratio.
   */
  SCALE_ASPECT_FIT = 0,
  /**
   * Fill with aspect ratio.
   */
  SCALE_ASPECT_FILL,
  /**
   * Stretch to fill.
   */
  SCALE_TO_FILL
}

export enum MirrorMode {
  /**
   * No mirroring.
   */
  MIRROR_MODE_NONE = 0,
  /**
   * Horizontal mirroring.
   */
  MIRROR_MODE_HORIZONTAL,
  /**
   * Vertical mirroring.
   */
  MIRROR_MODE_VERTICAL,
}

export enum RotateMode {
  /**
   * Rotate 0 degrees clockwise.
   */
  ROTATE_0 = 0,
  /**
   * Rotate 90 degrees clockwise.
   */
  ROTATE_90 = 90,
  /**
   * Rotate 180 degrees clockwise.
   */
  ROTATE_180 = 180,
  /**
   * Rotate 270 degrees clockwise.
   */
  ROTATE_270 = 270,
}

Known issues

Switching the application between the foreground and background may interrupt video playback. You can resolve this issue by setting a long-running task at the application's upper layer.

References

Compliance configuration guide for the HarmonyOS Player SDK