Advanced features

Transparent video playback

Overview

ApsaraVideo Player SDK for HarmonyOS NEXT supports rendering the alpha channel to play dynamic effects such as transparent gifts. In scenarios like live streaming rooms, you can play transparent gift animations without obscuring the main content, which significantly enhances the user experience.

Limits

Transparent rendering is supported in ApsaraVideo Player SDK for HarmonyOS NEXT v6.21.0 and later.

Benefits

Using MP4 videos that contain transparency information for gift effects offers better animation quality, smaller file sizes, higher compatibility, and greater development efficiency.

1. Better animation quality: MP4 videos can preserve the original animation quality, including details and colors. Compared to other formats like APNG or IXD, MP4 can more accurately restore the animation effects created by designers.

2. Smaller file sizes: MP4 video files can be compressed more effectively than other formats like APNG or IXD, which improves loading speed and reduces network bandwidth consumption.

3. Higher compatibility: MP4 is a universal video format widely supported across various devices and browsers, allowing gift effects to be played and viewed on mainstream devices.

4. Using MP4 videos for gift effects is technically straightforward. It eliminates the need for complex parsing and rendering logic, allowing developers to focus on other features and improve development efficiency.

  /**
   * Sets the alpha rendering mode.
   *
   * @param alphaRenderMode The specified alpha render mode. See {@link AlphaRenderMode}.
   */
  setAlphaRenderMode: (mode: AlphaRenderMode) => void;

@Builder
AlphaSurface() {
  if (this.uiController.enableAlpha) {
    XComponent({
      id: this.alphaPlayerIndex.toString(),
      type: XComponentType.TEXTURE, // Gifts must use a texture; otherwise, a background color is displayed.
      libraryname: 'premierlibrary',
      controller: this.alphaXComponentController
    })
      .onLoad(async () => {
        console.log("HOS DEMO", "alpha enabled")
        const player = VideoController.getPlayer(this.alphaPlayerIndex);
        if (player) {
          player.setAlphaRenderMode(AlphaRenderMode.RENDER_MODE_ALPHA_AT_RIGHT);
          // Set the asset that corresponds to the alpha mode.
          const urlSource: UrlSource = new UrlSource();
          urlSource.setUri("https://alivc-player.oss-cn-shanghai.aliyuncs.com/video/%E4%B8%9A%E5%8A%A1%E9%9C%80%E6%B1%82%E6%A0%B7%E6%9C%AC/alpha%E9%80%9A%E9%81%93/alpha_right.mp4");
          player.setUrlDataSource(urlSource);
          player.setAutoPlay(true);
          player.setLoop(true);
          player.prepare();
          player.setSurfaceId(this.alphaPlayerIndex.toString());
        }
      })
      .opacity(0.5) // Gift opacity
      .width(this.uiController.alphaWidth)
      .height(this.uiController.alphaHeight)
      .position({x: this.uiController.alphaX, y: this.uiController.alphaY })
  }
}

ApsaraVideo Player SDK for HarmonyOS NEXT allows you to add and switch external subtitles. Subtitle files in the SubRip Subtitle (SRT), SubStation Alpha (SSA), Advanced SubStation Alpha (ASS), and WebVTT (VTT) formats are supported. However, the SDK does not provide a built-in renderer for external subtitles.

Sample code:

1. Set subtitle-related listeners.

   Sample code

   private mOnSubtitle: OnSubtitleDisplayListener = {
       onSubtitleExtAdded: (trackIndex: number, url: string): void => {
         // The external subtitle has been added.
       },
       onSubtitleShow: (trackIndex: number, id: number, data: string): void => {
         // The subtitle text is available in `data`. Render it as needed.
       },
       onSubtitleHide: (trackIndex: number, id: number): void => {
         // Hide the subtitle.
       },
       onSubtitleHeader: (trackIndex: number, header: string): void => {
         // Subtitle header information.
       }
     }
   
     mAliPlayer.setOnSubtitleDisplayListener(this.mOnSubtitle);

2. Add subtitles.

   mAliPlayer.addExtSubtitle(url); // Add the subtitle after the player's onPrepared callback is triggered.

3. Show or hide subtitles.

   After you receive the onSubtitleExtAdded callback, use the following method to show or hide subtitles:

   // trackIndex: the subtitle track index. true: shows the specified track; false: hides the specified track.
   mAliPlayer.selectExtSubtitle(trackIndex, true);

Adaptive bitrate streaming

let mediaInfo: MediaInfo | null | undefined = player?.getMediaInfo();

let trackInfos: TrackInfo[] | undefined = mediaInfo?.getTrackInfos();

let index: number | undefined = trackInfo?.getIndex();
if (index ) {
  player?.selectTrack(index);
}
player?.selectTrack(TrackInfo.AUTO_SELECT_INDEX);

private mOnTrackChange: OnTrackChangedListener = {
  // The definition switch is successful.
  onChangedSuccess: (trackInfo: TrackInfo): void => {
    // Switch successful.
  }
}

let config:PlayerConfig | undefined = player.getConfig();
if (config) {
  config.mMaxAllowedAbrVideoPixelNumber = 921600; // Set the ABR upper limit to 921600 pixels (width × height = 1280 × 720). ABR can switch only to streams with a pixel count less than or equal to this value.
  player.setConfig(config);
}

ApsaraVideo Player SDK for HarmonyOS NEXT, in conjunction with ApsaraVideo VOD configurations, supports the preview feature. It supports both VidSts and VidAuth (recommended for ApsaraVideo VOD) playback methods. For more information about how to configure and use the preview feature, see Preview videos.

const vidSts: VidSts = new VidSts();

....
let configGen: VidPlayerConfigGen = new VidPlayerConfigGen();
configGen.setPreviewTime(20); // 20-second preview
vidSts.setPlayConfig(configGen); // Set for the playback source.
...

ApsaraVideo Player SDK for HarmonyOS NEXT provides methods in PlayerConfig to control buffering and latency. Sample code:

let config:PlayerConfig | undefined = player.getConfig();
if (config) {
  // The maximum latency. Note: This parameter is effective only for live streaming. If the latency is high, the player SDK internally adjusts the playback speed to keep the latency within this range.
  config.mMaxDelayTime = 5000;
  // The maximum buffer duration in milliseconds. The player loads a buffer of up to this duration at a time.
  config.mMaxBufferDuration = 50000;
  // The high buffer threshold in milliseconds. When data is being loaded due to poor network conditions, the loading state ends after the buffered data reaches this duration.
  config.mHighBufferDuration = 3000;
  // The buffer duration for playback startup in milliseconds. A smaller value results in a faster startup, but may cause the player to enter a loading state soon after playback begins.
  config.mStartBufferDuration = 500;
  ....// Other settings
  // The maximum backward buffer duration in milliseconds. The default value is 0.
  config.mMaxBackwardBufferDurationMs = 0;
  player.setConfig(config);
}

ApsaraVideo Player SDK for HarmonyOS NEXT supports setting the background color for video rendering. The API and usage are described below.

API example

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

Usage

// The parameter is an 8-digit hexadecimal value. The 8 digits are in pairs, representing A (alpha), R (red), G (green), and B (blue) in order.
// For example, 0x0000ff00 represents green.
player.setVideoBackgroundColor(0x0000ff00);

Set playback domain for VidAuth

With VidAuth-based playback, you can specify fields such as the domain name corresponding to a vid. For more information about the supported fields, see GetPlayInfo request parameters. The API and usage are described below.

API example

/**
 * Sets playback parameters.
 *
 * @param playConfig The playback parameters.
 */
setPlayerConfig: (playerConfig: VidPlayerConfigGen) => void

Usage

Use the addPlayerConfig method of the VidPlayerConfigGen interface to add the playDomain field.

const vidAuthSource: VidAuth = new VidAuth();
let configGen: VidPlayerConfigGen = new VidPlayerConfigGen();
// Add the playDomain field. For more information about the fields that can be added, see
// https://www.alibabacloud.com/help/en/apsaravideo-for-vod/latest/api-vod-2017-03-21-getplayinfo
configGen.addPlayerConfigString("playDomain", "com.xxx.xxx");
vidAuthSource.setPlayerConfig(configGen);

player.setVidAuthDataSource(vidAuthSource);

Automatic source refresh

Automatic playback source refresh prevents interruptions caused by expired sources in authentication-based scenarios. When a source expires, the player triggers a listener to obtain a new URL, ensuring continuous playback.

Prerequisites

1. The Player SDK or All-in-One SDK is v7.9.0 or later.

2. You are using VidAuth-based playback or have configured URL authentication for your service.

/**
     * Sets the listener for VidAuth source expiration events.
     *
     * This feature enables automated VidAuth source refresh to avoid playback interruptions
     * caused by expiration. When the listener is triggered, you can refresh the VidAuth source
     * and return the updated VidAuth using {@link SourceRefreshCallback#onSuccess}.
     *
     * @param listener The interface for listening to VidAuth source expiration events. See {@link OnVidAuthExpiredListener}.
     */
setOnVidAuthExpiredListener(listener: OnVidAuthExpiredListener): void;

export interface OnVidAuthExpiredListener {
    /**
     * This callback is triggered when the player detects that the VidAuth source has expired. A VidAuth source can expire if its PlayAuth or playback URL expires.
     *
     * You can refresh the VidAuth source in this callback and return the new VidAuth source
     * by using {@link SourceRefreshCallback#onSuccess}.
     *
     * @param expiredSource The expired VidAuth source object. See {@link VidAuth}.
     * @param callback The callback interface for providing the new VidAuth source to the player. See {@link SourceRefreshCallback}.
     */
    onVidAuthExpired(expiredSource: VidAuth, callback: SourceRefreshCallback<VidAuth> | null): void;
}

/**
* A callback interface for handling playback source refresh results.
*
* This interface is applicable to playback source types that require dynamic updates,
* such as a URL source or VidAuth source. When the player triggers a refresh request,
* you can return the refresh result through this interface by calling either the `onSuccess` or `onError` method.
*/
export interface SourceRefreshCallback<T> {
/**
* Called by the player when the refresh operation succeeds.
*
* @param newSource The new playback source object that contains the updated information. See {@link SourceBase}.
*
* This method indicates that the refresh operation was successfully completed. You must provide
* the new playback source within this method so that the player can load the latest resource.
*/
onSuccess(newSource: T): void;

/**
* Called by the player when the refresh operation fails.
*
* @param errorMsg A string that describes the reason for the failure.
*
* This method indicates that the refresh operation has failed. You can use the `errorMsg`
* to capture details about the failure and proceed with subsequent handling.
*/
onError(errorMsg: string): void;
}

private mOnVidAuthExpiredListener: OnVidAuthExpiredListener = ({
   onVidAuthExpired(vidAuth: VidAuth, callback: SourceRefreshCallback<VidAuth> | null) {
     let vid: String = vidAuth.getVid()

     // ------------------- Start of user implementation -------------------
     // Call your own function to get the new PlayAuth from your app server.
     // This is an example. You must implement it according to your business logic.
     XHR.fetch(``)
       .then((data) => {
         try {
           console.log("Refresh - VidAuth", data.toString());
           const response: IAuthResponse = JSON.parse(JSON.parse(data));

           if (response && response.data && response.data.playAuth) {
             // 1. Update the old vidAuth object with the new PlayAuth.
             vidAuth.setPlayAuth(response.data.playAuth);

             // 2. Pass the updated object back to the player by using the SDK's callback.
             callback?.onSuccess(vidAuth);
           } else {
             // Pass the error message back to the player by using the SDK's callback.
             callback?.onError('REFRESH_ERROR, invalid response data');
           }
         } catch (parseError) {
           console.error("Parse or callback error:", parseError);
         }
       })
       .catch((e: Error) => {
         console.error("Network error:", e);
         // Pass the error message back to the player by using the SDK's callback.
         callback?.onError('REFRESH_ERROR, network fail');
       })
   }
 })

/**
 * Sets the listener for URL source expiration events.
 *
 * This feature enables URL refresh to avoid playback interruptions caused by
 * URL expiration due to authentication. When the listener is triggered,
 * you can refresh the URL source and return the updated URL source by using {@link SourceRefreshCallback#onSuccess}.
 *
 * @param listener Listener for handling URL source expiration events. See {@link OnURLSourceExpiredListener}.
 *
 * <p>For more information about how to configure URL authentication, see
 * <a href="https://www.alibabacloud.com/help/en/apsaravideo-for-vod/latest/url-signing">URL authentication</a>.</p>
 */
setOnURLSourceExpiredListener(listener: OnURLSourceExpiredListener): void;

/**
 * A callback interface for handling playback source refresh results.
 *
 * This interface is applicable to playback source types that require dynamic updates,
 * such as a URL source or VidAuth source. When the player triggers a refresh request,
 * you can return the refresh result through this interface by calling either the `onSuccess` or `onError` method.
 */
export interface SourceRefreshCallback<T> {
    /**
     * Called by the player when the refresh operation succeeds.
     *
     * @param newSource The new playback source object that contains the updated information. See {@link SourceBase}.
     *
     * This method indicates that the refresh operation was successfully completed. You must provide
     * the new playback source within this method so that the player can load the latest resource.
     */
    onSuccess(newSource: T): void;
    /**
     * Called by the player when the refresh operation fails.
     *
     * @param errorMsg A string that describes the reason for the failure.
     *
     * This method indicates that the refresh operation has failed. You can use the `errorMsg`
     * to capture details about the failure and proceed with subsequent handling.
     */
    onError(errorMsg: string): void;
}
/**
 * Sets the listener for URL source expiration events.
 *
 * This feature enables URL refresh to avoid playback interruptions caused by
 * URL expiration due to authentication. When the listener is triggered,
 * you can refresh the URL source and return the updated URL source by using {@link SourceRefreshCallback#onSuccess}.
 *
 * @param listener Listener for handling URL source expiration events. See {@link OnURLSourceExpiredListener}.
 *
 * <p>For more information about how to configure URL authentication, see
 * <a href="https://www.alibabacloud.com/help/en/apsaravideo-for-vod/latest/url-signing">URL authentication</a>.</p>
 */
export interface OnURLSourceExpiredListener {
    /**
     * This callback is triggered when the player detects that the URL source (UrlSource) has expired.
     *
     * You can refresh the URL source in this callback and return the new UrlSource
     * by using {@link SourceRefreshCallback#onSuccess}.
     *
     * @param expiredSource The expired UrlSource object. See {@link UrlSource}.
     * @param callback The refresh callback used to return the updated UrlSource to the player. See {@link SourceRefreshCallback}.
     */
    onUrlSourceExpired(expiredSource: UrlSource, callback: SourceRefreshCallback<UrlSource> | null): void;
}

/**
* A callback interface for handling playback source refresh results.
*
* This interface is applicable to playback source types that require dynamic updates,
* such as a URL source or VidAuth source. When the player triggers a refresh request,
* you can return the refresh result through this interface by calling either the `onSuccess` or `onError` method.
*/
export interface SourceRefreshCallback<T> {
/**
* Called by the player when the refresh operation succeeds.
*
* @param newSource The new playback source object that contains the updated information. See {@link SourceBase}.
*
* This method indicates that the refresh operation was successfully completed. You must provide
* the new playback source within this method so that the player can load the latest resource.
*/
onSuccess(newSource: T): void;

/**
* Called by the player when the refresh operation fails.
*
* @param errorMsg A string that describes the reason for the failure.
*
* This method indicates that the refresh operation has failed. You can use the `errorMsg`
* to capture details about the failure and proceed with subsequent handling.
*/
onError(errorMsg: string): void;
}

private mOnURLSourceExpiredListener: OnURLSourceExpiredListener = ({
  onUrlSourceExpired(urlSource: UrlSource, callback: SourceRefreshCallback<UrlSource> | null) {
    // 1. Extract the original URL from the expired URL (using authentication method A as an example).
    let playURL: String = urlSource.getUri();

    let urlAuthKeyIndex = playURL.indexOf('?auth_key=');
    if (urlAuthKeyIndex == -1) {
      urlAuthKeyIndex = playURL.indexOf("&auth_key=");
    }

    if (urlAuthKeyIndex === -1) {
      callback?.onError('PARSE_ERROR, Cannot find auth_key in URL');
      return;
    }

    // Restore the original resource address by removing the URL parameter part, for example, "?auth_key=".
    // This ensures safe handling even if auth_key is not found.
    const originalUrl = playURL.substring(0, urlAuthKeyIndex);

    // 2. Generate a new authentication URL.
    let key = '';
    if (mAuthKey != null) {
      key = mAuthKey
    }

    // Calculate the timeout for the playback URL (validity period).
    const newExpireTime = Math.floor(Date.now() / 1000) + parseInt(mValidTime); // Current time + 1 hour

    // Use the utility class to generate a new authentication URL.
    const newAuthUrl = CdnAuthUtil.aAuth(originalUrl, key, newExpireTime);

    // 3. Check the generated authentication URL and return the result through the callback.
    if (newAuthUrl) {
      let urlSource: UrlSource = new UrlSource();
      urlSource.setUri(newAuthUrl);
      callback?.onSuccess(urlSource);
    } else {
      callback?.onError('REFRESH_ERROR, refresh fail');
    }
  }
})

Utility functions

class CdnAuthUtil {
  /**
   * Authentication method A
   */
  static aAuth(uri: string, key: string, exp: number): string | null {
    const match = uri.match(URI_PATTERN);
    if (!match) {
      return null;
    }

    const scheme = match[1] ? `${match[1]}://` : 'http://';
    const host = match[2];
    const path = match[3] || '/';
    const args = match[4] || '';

    const rand = '0';
    const uid = '0';
    const sstring = `${path}-${exp}-${rand}-${uid}-${key}`;
    md5sum(sstring).then(res => {
      authKey = `${exp}-${rand}-${uid}-${res}`;
    })

    const separator = args ? '&' : '?';
    return `${scheme}${host}${path}${args}${separator}auth_key=${authKey}`;
  }

  /**
   * Authentication method B
   */
  static bAuth(uri: string, key: string, exp: number): string | null {
    const match = uri.match(URI_PATTERN);
    if (!match) {
      return null;
    }

    const scheme = match[1] ? `${match[1]}://` : 'http://';
    const host = match[2];
    const path = match[3] || '/';
    const args = match[4] || '';

    // Convert the timestamp to UTC time and format it as yyyyMMddHHmm.
    const date = new Date(exp * 1000);
    const utcStr = date.toUTCString(); // Use toUTCString and parse or format manually.
    const formatter = new Intl.DateTimeFormat('zh-CN', {
      timeZone: 'UTC',
      year: 'numeric',
      month: '2-digit',
      day: '2-digit',
      hour: '2-digit',
      minute: '2-digit',
      second: '2-digit',
      hour12: false
    });
    const parts = formatter.formatToParts(date);
    const getPart = (type: string) => parts.find(p => p.type === type)?.value || '';
    const nexp = `${getPart('year')}${getPart('month')}${getPart('day')}${getPart('hour')}${getPart('minute')}`;

    const sstring = key + nexp + path;
    const hashvalue = md5sum(sstring);

    return `${scheme}${host}/${nexp}/${hashvalue}${path}${args}`;
  }

  /**
   * Authentication method C
   */
  static cAuth(uri: string, key: string, exp: number): string | null {
    const match = uri.match(URI_PATTERN);
    if (!match) {
      return null;
    }

    const scheme = match[1] ? `${match[1]}://` : 'http://';
    const host = match[2];
    const path = match[3] || '/';
    const args = match[4] || '';

    const hexexp = exp.toString(16); // Convert decimal to hexadecimal.
    const sstring = key + path + hexexp;
    const hashvalue = md5sum(sstring);

    return `${scheme}${host}/${hashvalue}/${hexexp}${path}${args}`;
  }
}

export default CdnAuthUtil;

ApsaraVideo Player SDK for HarmonyOS NEXT provides a local cache feature. When playing a video multiple times, this feature improves startup speed and seek speed, reduces stuttering, and saves network traffic.

Enable local caching

/**
   * Enables the local cache. If enabled, content is cached to local files.
   * @param enable true: enables local caching. false: disables local caching. This feature is disabled by default.
   * @param maxBufferMemoryKB The maximum memory size for a single source, in KB.
   * @param localCacheDir The absolute path of the directory for local cache files.
   */
  static enableLocalCache(enable: boolean, maxBufferMemoryKB: number, localCacheDir: string)

    /**
   *  Configures the automatic cleanup of local cache files.
   * @param expireMin The expiration time of the cache in minutes. Default value: 30 days. Expired cache items are always removed during cleanup, regardless of their size.
   * @param maxCapacityMB The maximum cache capacity in MB. Default value: 20 GB. During cleanup, if the total cache size exceeds this limit, items are deleted one by one based on their last access time (oldest first) until the total size is within the limit.
   * @param freeStorageMB The minimum free disk space in MB. Default value: 0. During cleanup, if the available disk space is less than this value, cache items are deleted one by one based on their last access time until the free space meets the requirement or all cache items are removed.
   */
  static setCacheFileClearConfig(expireMin: number, maxCapacityMB: number, freeStorageMB: number)

  /**
   * Sets the callback for generating a URL hash. If not set, the SDK uses the MD5 algorithm.
   */
  setCacheUrlHashCallback(cb: OnGetUrlHashCallback)

Enable or disable local caching for a single URL

let config:PlayerConfig | undefined = player.getConfig();
if (config) {
  // Specifies whether to enable local caching for the playback URL. Default value: true.
  // For the local cache to be effective for this URL, global caching in AliPlayerGlobalSettings must also be enabled, and this value must be true.
  // If set to false, local caching is disabled for this specific URL.
  config.mEnableLocalCache = true; 
  player.setConfig(config);
}

ApsaraVideo Player SDK for HarmonyOS NEXT provides a preload feature, which is an enhancement of the local cache. It improves video startup speed by caching a specified duration of content before playback begins.

AliPlayerGlobalSettings.enableNetworkBalance(false);

1. Enable the local cache feature. For details, see Local Cache.

2. Call the pre-initialization method.

   privateService.preInitService(getContext());

3. Set the data source.

   VidAuth (recommended)

   let vidAuth: VidAuth = new VidAuth();
   vidAuth.setVid("Your_Vid");// Required. The Video ID.
   vidAuth.setPlayAuth("<yourPlayAuth>");// Required. The playback credential. Generate it by calling the GetVideoPlayAuth operation of the VOD service.
   vidAuth.setRegion("Your_Region");// Optional. Default value: cn-shanghai.
   vidAuth.setQuality("Selected_Quality");// "AUTO" represents auto bitrate.

   VidSts

   let vidSts: VidSts = new VidSts();
   vidSts.setVid("Your_Vid");// Required. The Video ID.
   vidSts.setAccessKeyId("<yourAccessKeyId>");// Required. The Access Key ID of the temporary STS token pair. Generate it by calling the AssumeRole operation of STS.
   vidSts.setAccessKeySecret("<yourAccessKeySecret>");// Required. The Access Key Secret of the temporary STS token pair. Generate it by calling the AssumeRole operation of STS.
   vidSts.setSecurityToken("<yourSecurityToken>");// Required. The Security Token of the temporary STS token pair. Generate it by calling the AssumeRole operation of STS.
   vidSts.setRegion("Your_Region"); // Optional. Default value: cn-shanghai.
   vidSts.setQuality("Selected_Quality");// "AUTO" represents auto bitrate.

   UrlSource

   // Create a data source object and set the playback URL.
   let urlSource: UrlSource = new UrlSource();
   // Required parameter.
   urlSource.setUri("Your_Playback_URL");

4. Set the task parameters.

   Note

   This applies only to multi-bitrate video. You only need to choose one ofsetDefaultBandWidth,setDefaultResolution, orsetDefaultQuality.

   let mPreloadConfig: PreloadConfig = new PreloadConfig();
   // Set the preload bitrate for multi-bitrate streams.
   preloadConfig.setDefaultBandWidth(400000);
   // Set the preload resolution for multi-bitrate streams.
   preloadConfig.setDefaultResolution(640 * 480);
   // Set the preload quality for multi-bitrate streams.
   preloadConfig.setDefaultQuality(“FD“);
   // Set the preload duration.
   preloadConfig.setDuration(1000);

5. Add a task listener.

   private PreloadListenerImpl: OnPreloadListener = {
     onError: (taskId: string, urlOrVid: string, errorInfo: ErrorInfo): void => {
       console.error("OnPreloadListener -> " + " taskId: " + taskId + " ErrorMsg: " + errorInfo.getMsg())
     },
     onCompleted: (taskId: string, urlOrVid: string): void => {
       console.info("OnPreloadListener -> " + "onCompleted" + " taskId: " + taskId);
     },
     onCanceled: (taskId: string, urlOrVid: string): void => {
       console.info("OnPreloadListener -> " + "onCanceled" + " taskId: " + taskId)
     }
   }

6. Build the task, add it to theMediaLoaderV2 instance, and start preloading.

   VidAuth (recommended)

   // Build the preload task.
   let mPreloadTask: PreloadTask = new PreloadTask(vidAuth, mPreloadConfig);
   // Get the MediaLoaderV2 instance.
   let mediaLoaderV2: MediaLoaderV2 = MediaLoaderV2.getInstance();
   // Add the task and start preloading.
   let taskId: String = mediaLoaderV2.addTask(mPreloadTask, PreloadListenerImpl)

   VidSts

   // Build the preload task.
   let mPreloadTask: PreloadTask = new PreloadTask(vidSts, mPreloadConfig);
   // Get the MediaLoaderV2 instance.
   let mediaLoaderV2: MediaLoaderV2 = MediaLoaderV2.getInstance();
   // Add the task and start preloading.
   let taskId: String = mediaLoaderV2.addTask(mPreloadTask, PreloadListenerImpl)

   UrlSource

   // Build the preload task.
   let mPreloadTask: PreloadTask = new PreloadTask(urlSource, mPreloadConfig);
   // Get the MediaLoaderV2 instance.
   let mediaLoaderV2: MediaLoaderV2 = MediaLoaderV2.getInstance();
   // Add the task and start preloading.
   let taskId: String = mediaLoaderV2.addTask(mPreloadTask, PreloadListenerImpl)

7. Optional: Manage tasks.

   mediaLoaderV2.cancelTask(taskId);// Cancels the preload task with the specified task ID.
   mediaLoaderV2.pauseTask(taskId);// Pauses the preload task with the specified task ID.
   mediaLoaderV2.resumeTask(taskId);// Resumes the preload task with the specified task ID.

8. Delete the loaded files.

   To save space, you can delete preloaded files. The SDK does not provide a deletion API; you must delete the files from the loading directory in your app.

HTTPDNS

// Enable enhanced HTTPDNS.
AliPlayerGlobalSettings.enableEnhancedHttpDns(true);

// Optional: Add a domain name for HTTPDNS pre-resolution.
DomainProcessor.addPreResolveDomain("player.***alicdn.com");

HTTP/2

AliPlayerGlobalSettings.setUseHttp2(true);

The ApsaraVideo Player SDK for HarmonyOS NEXT lets you download videos from ApsaraVideo VOD and cache them for offline playback. It offers two download methods: normal download and secure download.

• Normal download

  Alibaba Cloud does not encrypt videos downloaded in this mode, so they can be played by third-party players.

• Secure download

  Alibaba Cloud encrypts videos downloaded in this mode. Only ApsaraVideo Player can play these videos; third-party players cannot.

Usage notes

• The video download feature is supported only for VidSts and VidAuth sources.

• To use the video download feature, you must enable and configure the download mode in the ApsaraVideo VOD console. For more information, see offline download.

• Resumable downloads are supported.

Procedure

1. Optional: Configure the key file. This step is required only for secure download.

   Note

   Ensure the configured key file matches your app information to prevent download failures.

   For secure downloads, you must configure the player SDK with the key file generated in the ApsaraVideo VOD console. This file is required for decryption and verification during video download and playback. To generate the key file, see Enable secure download.

   After generating the key file, place it in the rawfile directory of your project (create the directory if it does not exist). The directory structure is as follows:

   src/main/resources/
   └── rawfile/
       └── encrypt/
           └── encryptedApp.dat

   After placing the file, configure it using the following sample code:

   try {
     getContext().resourceManager.getRawFileContent('encrypt/encryptedApp.dat', (error, value) => {
       if (error != null) {
         console.log('downloader init error is ' + error);
       } else {
         let rawFile = value;
         let textDecoder = util.TextDecoder.create('utf-8', { ignoreBOM : true });
         let rawFileString = textDecoder.decodeToString( rawFile , {stream: false});
         console.log(`downloader get encryptedApp.dat value: ${rawFileString}`);
         PrivateService.initServiceWithBytes(getContext(), rawFileString);
       }
     })
   } catch (error) {
     let code = (error as BusinessError).code;
     let message = (error as BusinessError).message;
     console.error(`callback getRawFileContent failed, error code: ${code}, message: ${message}.`);
   }

2. Create and set up the downloader.

   Create a downloader using AliDownloaderFactory. Sample code:

   ......
   // Create the downloader.
   let mAliDownloader:AliMediaDownloader = AliDownloaderFactory.create(getApplicationContext());
   // Configure the path to save downloaded files.
   mAliDownloader.setSaveDir(getContext().cacheDir);

3. Set listeners.

   You can set multiple listeners for the downloader. Sample code:

   Sample code

   // Callback for successful download preparation. After the callback is invoked, use the {@linkplain #selectItem(int)} method to select the track to download.
   export interface OnPreparedListener {
     onPrepared: (mediaInfo: MediaInfo) => void;
   }
   
   // Progress callback.
   export interface OnProgressListener {
      // The download progress percentage.
     onDownloadingProgress: (percent: number) => void;
     // The processing progress percentage.
     onProcessingProgress: (percent: number) => void;
   }
   
   // Completion callback.
   export interface OnCompletionListener {
     onCompletion: () => void;
   }
   
   // Error callback.
   export interface OnErrorListener {
     // The download error message.
     onError: (errorInfo: ErrorInfo) => void;
   }

4. Prepare the download source.

   Use the prepare method to prepare the download source. VidSts and VidAuth sources are supported. Sample code:

   • VidSts

     // Create a VidSts source.
     let aliyunVidSts : VidSts = new VidSts();
     aliyunVidSts.setVid("Your Video ID");// The Video ID.
     aliyunVidSts.setAccessKeyId("<yourAccessKeyId>");// The AccessKey ID of the temporary STS token, obtained by calling the STS AssumeRole operation.
     aliyunVidSts.setAccessKeySecret"<yourAccessKeySecret>");// The AccessKey Secret of the temporary STS token, obtained by calling the STS AssumeRole operation.
     aliyunVidSts.setSecurityToken("<yourSecurityToken>");// The security token, obtained by calling the STS AssumeRole operation.
     aliyunVidSts.setRegion("Your region");// The region where ApsaraVideo VOD is enabled. Default: cn-shanghai.
     
     // If you enabled HLS standard encryption parameter passthrough in the ApsaraVideo VOD console
     // and the default parameter name is MtsHlsUriToken, you need to set the config
     // and pass it to the VidSts object as shown in the following code.
     // If you have not enabled HLS standard encryption parameter passthrough, you can skip the following code.
     let config:VidPlayerConfigGen = new VidPlayerConfigGen();
     config.setMtsHlsUriToken("<yourMtsHlsUriToken>");
     aliyunVidSts.setPlayerConfig(config);
         
     
     // Prepare the download source.
     mAliDownloader.prepare(aliyunVidSts)

   • VidAuth

     // Create a VidAuth source.
     let vidAuth : VidAuth = new VidAuth();
     vidAuth.setVid("Your Video ID");// The Video ID.
     vidAuth.setPlayAuth("<yourPlayAuth>");// The playback credential, obtained by calling the ApsaraVideo VOD GetVideoPlayAuth operation.
     vidAuth.setRegion("Your region");// Deprecated. The region is parsed automatically.
      // If you enabled HLS standard encryption parameter passthrough in the ApsaraVideo VOD console
      // and the default parameter name is MtsHlsUriToken, you need to set the config
      // and pass it to the VidAuth object as shown in the following code.
      // If you have not enabled HLS standard encryption parameter passthrough, you can skip the following code.
     let config:VidPlayerConfigGen = new VidPlayerConfigGen();
     config.setMtsHlsUriToken("<yourMtsHlsUriToken>");
     vidAuth.setPlayerConfig(config);
     // Prepare the download source.
     mAliDownloader.prepare(vidAuth);

   Note

   • The format of the downloaded file is the same as that of the source file and cannot be changed.

   • If you enable HLS standard encryption parameter passthrough in the ApsaraVideo VOD console, the default parameter name is MtsHlsUriToken. For more information, see HLS standard encryption parameter passthrough. In this case, you must set the MtsHlsUriToken value in the source object as shown in the preceding code.

5. Select a track and start the download.

   When preparation is complete, the OnPreparedListener callback is triggered. The returned TrackInfo contains information about each video stream, such as its definition. Select a track to download. Sample code:

   mAliDownloader.setOnPreparedListener({
     onPrepared: (mediaInfo: MediaInfo) => {
       // The download source is successfully prepared.
       let trackInfos : TrackInfo[] = mediaInfo.getTrackInfos();
       // For example, download the first track.
       mAliDownloader.selectItem(trackInfos[0].getIndex());
       // Start the download.
       mAliDownloader.start();
     }
   });

6. (Optional) Update the download source.

   To prevent VidSts and VidAuth from expiring, update the download source information before starting the download. For example:

   // Update the download source.
   mAliDownloader.updateVidStsSource(VidSts);
   // Start the download.
   mAliDownloader.start();

7. Release the downloader after the download completes or fails.

   When the download finishes, call the release method within the onCompletion or onError callback.

   mAliDownloader.stop();
   mAliDownloader.release();

8. Optional: Delete the downloaded files.

   You can delete downloaded files during or after the download. Sample code:

   // Delete the file using the object.
   mAliDownloader.deleteFile();
   // Delete the file using the static method. If the deletion succeeds, 0 is returned.
   AliDownloaderFactory.deleteFile("Path to the download folder to be deleted","Video ID","Video format","Index of the downloaded video");

Next steps

To play the downloaded videos with ApsaraVideo Player, follow these steps:

1. After the download is complete, obtain the absolute path of the video file.

   let path: string = mAliDownloader.getFilePath();

2. Set the absolute path using a UrlSource to play the video.

   let urlSource: UrlSource = new UrlSource();
   urlSource.setUri(path);// Set the absolute path of the downloaded video file.
   aliPlayer.setUrlDataSource(urlSource);