openharmony 鸿蒙 arkts-apis-media-AVMetadataExtractor

2026-08-25 浏览 (1)

Interface (AVMetadataExtractor)

AVMetadataExtractor is a class for metadata retrieval. It provides APIs to obtain metadata and thumbnails from media assets. Before calling any API of AVMetadataExtractor, you must use media.createAVMetadataExtractor to create an AVMetadataExtractor instance.

For details about the demo of obtaining audio or video metadata and video thumbnails, see Using AVMetadataExtractor to Extract Audio and Video Metadata (ArkTS).

NOTE

  • The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
  • The initial APIs of this interface are supported since API version 11.

Modules to Import

import { media } from '@kit.MediaKit';

Properties

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

NameTypeRead-OnlyOptionalDescription
fdSrc11+AVFileDescriptorNoYesMedia file descriptor, which specifies the data source. Before obtaining metadata, you must set the data source through either fdSrc or dataSrc.
Example:
There is a media file that stores continuous assets, the address offset is 0, and the byte length is 100. Its file descriptor is AVFileDescriptor { fd = resourceHandle; offset = 0; length = 100; }.
NOTE
After the resource handle (FD) is transferred to an AVMetadataExtractor instance, do not use the resource handle to perform other read and write operations, including but not limited to transferring this handle to other AVPlayer, AVMetadataExtractor, AVImageGenerator, or AVTranscoder instance. Competition occurs when multiple AVMetadataExtractor use the same resource handle to read and write files at the same time, resulting in errors in obtaining data.
dataSrc11+AVDataSrcDescriptorNoYesStreaming media resource descriptor, which specifies the data source. Before obtaining metadata, you must set the data source through either fdSrc or dataSrc.
When an application obtains a media file from the remote, you can set dataSrc to obtain the metadata before the application finishes the downloading.

setUrlSource20+

setUrlSource(url: string, headers?: Record<string, string>): void

Sets the data source for a network on-demand resource. Only network metadata (fetchMetadata) and thumbnails (fetchFrameByTime) can be obtained. The media resource URL must be set before the retrieval.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
urlstringYesURL of the media resource.
1. The video formats MP4, MPEG-TS, and MKV are supported.
2. The audio formats M4A, AAC, MP3, OGG, WAV, FLAC, and AMR are supported.
Example of supported URLs:
1. HTTP: http://xx
2. HTTPS: https://xx
Note: HLS/DASH and live streaming resources are not supported.
headersRecord<string, string>NoCustom HTTP headers for accessing the network resource. The default value is empty.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

let avMetadataExtractor: media.AVMetadataExtractor|undefined = undefined;

media.createAVMetadataExtractor(async (error: BusinessError, extractor: media.AVMetadataExtractor) => {
  if (extractor) {
    avMetadataExtractor = extractor;
    console.info('Succeeded in creating AVMetadataExtractor');
    let url = "http://xx";
    let headers: Record<string, string> = {
      "User-Agent": "User-Agent-Value"
    };
    avMetadataExtractor.setUrlSource(url, headers);
  } else {
    console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`);
  }
});

fetchFrameByTime20+

fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams): Promise<image.PixelMap>

Obtains a video thumbnail. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
timeUsnumberYesTime of the video for which a thumbnail is to be obtained, in us.
optionsAVImageQueryOptionsYesRelationship between the time passed in and the video frame.
paramPixelMapParamsYesFormat parameters of the thumbnail to be obtained.

Return value

TypeDescription
Promise<image.PixelMap>Promise used to return the video thumbnail.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by promise.
5400106Unsupported format. Returned by promise.
5400108Parameter check failed. Returned by promise.
5411012Http cleartext traffic is not permitted.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';
import { media } from '@kit.MediaKit';

let avMetadataExtractor: media.AVMetadataExtractor|undefined = undefined;
let pixelMap: image.PixelMap|undefined = undefined;

// Initialize input parameters.
let timeUs: number = 0;
let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_PREVIOUS_SYNC;
let param: media.PixelMapParams = {
  width: 300,
  height: 300
};
// Obtain the thumbnail.
media.createAVMetadataExtractor((error: BusinessError, extractor: media.AVMetadataExtractor) => {
  if (extractor) {
    avMetadataExtractor = extractor;
    console.info('Succeeded in creating AVMetadataExtractor');
    avMetadataExtractor.fetchFrameByTime(timeUs, queryOption, param).then((pixelMap: image.PixelMap) => {
      pixelMap = pixelMap;
    }).catch((error: BusinessError) => {
      console.error(`Failed to fetch FrameByTime, error message:${error.message}`);
    });
  } else {
    console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`);
  }
});

fetchFrameByTimeWithTimeout

fetchFrameByTimeWithTimeout(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams, timeoutMs: number): Promise<image.PixelMap|undefined>

Obtains a video thumbnail. You can set the maximum timeout interval (timeoutMs) for obtaining the thumbnail. This API uses a promise to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
timeUsnumberYesTime of the video for which a thumbnail is to be obtained, in μs.
optionsAVImageQueryOptionsYesRelationship between the time passed in and the video frame.
paramPixelMapParamsYesFormat parameters of the thumbnail to be obtained.
timeoutMsnumberYesTimeout interval for obtaining the thumbnail. The value range is (0, 20000], in milliseconds.
If the thumbnail is not obtained within the specified timeout interval, error code 5400104 is returned.

Return value

TypeDescription
Promise<image.PixelMap |undefined>Promise used to return the video thumbnail.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by promise.
5400104Operation timeout.
5400106Unsupported format. Returned by promise.
5400108Parameter check failed. Returned by promise.
5411012Http cleartext traffic is not permitted.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';
import { media } from '@kit.MediaKit';

let avMetadataExtractor: media.AVMetadataExtractor|undefined = undefined;
let pixelMap: image.PixelMap|undefined = undefined;

// Initialize input parameters.
let timeUs: number = 0;
let timeoutMs: number = 3000;
let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_PREVIOUS_SYNC;
let param: media.PixelMapParams = {
  width: 300,
  height: 300
};
// Obtain the thumbnail.
media.createAVMetadataExtractor((error: BusinessError, extractor: media.AVMetadataExtractor) => {
  if (extractor) {
    avMetadataExtractor = extractor;
    console.info('Succeeded in creating AVMetadataExtractor');
    avMetadataExtractor.fetchFrameByTimeWithTimeout(timeUs, queryOption, param, timeoutMs).then((pixelMap: image.PixelMap|undefined) => {
      pixelMap = pixelMap;
    }).catch((error: BusinessError) => {
      console.error(`Failed to fetch FrameByTime, code: ${error.code}, message:${error.message}`);
    });
  } else {
    console.error(`Failed to create AVMetadataExtractor, code: ${error.code}, message:${error.message}`);
  }
});

fetchFramesByTimes23+

fetchFramesByTimes(timesUs: number[], queryOption: AVImageQueryOptions, param: PixelMapParams, callback: OnFrameFetched): void

Obtains video thumbnails in batches. This API uses an asynchronous callback to return the result.

NOTE

  • The given video resource is decoded first, and then image frames are extracted from each time point in the timesUs array based on the provided options and param.
  • When each image extraction is complete, the system calls the callback function and passes the extraction result. Note that the execution order of the callback function may be inconsistent with the time points in the timesUs array.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
timesUsnumber[]YesSet of time points of all thumbnails to be obtained in the video.
The unit is microsecond (μs), and the value range of the array length is (0, 4096].
queryOptionAVImageQueryOptionsYesRelationship between the time passed in and the video frame.
paramPixelMapParamsYesFormat parameters of the thumbnail to be obtained.
callbackOnFrameFetchedYesThumbnail information to be returned and possible exception types.
For details about the exception types, see the returned error code information.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by callback.
5400104Fetch timeout. Returned by callback.
5400106Unsupported format. Returned by callback.
5400105Service died.
5400108Parameter check failed. e.g. The size of timesUs is larger than 4096.
5411012Http cleartext not permitted.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';
import { media } from '@kit.MediaKit';

async function fetchFramesByTimesDemo() {
  // Initialize input parameters.
  let timesUs: number[] = [0];
  let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_PREVIOUS_SYNC;
  let param: media.PixelMapParams = {
    width: 300,
    height: 300
  };
  // Obtain the thumbnail.
  let avMetadataExtractor = await media.createAVMetadataExtractor();
  if (avMetadataExtractor) {
    console.info('Succeeded in creating AVMetadataExtractor');
    avMetadataExtractor.fetchFramesByTimes(timesUs, queryOption, param, async (frameInfo: media.FrameInfo, err: BusinessError) => {
      if (err) {
        console.info(`fetchFramesByTimes callback failed, error = ${JSON.stringify(err)}`);
        return;
      }
      if (frameInfo != undefined && frameInfo.image != undefined) {
        let pixelMap = frameInfo.image;
      }});
  }
}

fetchFramesByTimesWithTimeout

fetchFramesByTimesWithTimeout(timesUs: number[], queryOption: AVImageQueryOptions, param: PixelMapParams, timeoutMs: number, callback: OnFrameFetched): void

Obtains video thumbnails in batches. You can set the maximum timeout interval (timeoutMs) for obtaining each thumbnail. This API uses an asynchronous callback to return the result.

NOTE

  • The given video resource is decoded first, and then image frames are extracted from each time point in the timesUs array based on the provided options and param.
  • When each image extraction is complete, the system calls the callback function and passes the extraction result. Note that the execution order of the callback function may be inconsistent with the time points in the timesUs array.
  • The timeoutMs parameter indicates the maximum timeout interval for obtaining each thumbnail frame, not the entire batch thumbnail extraction process.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
timesUsnumber[]YesSet of time points of all thumbnails to be obtained in the video.
The unit is microsecond (μs), and the value range of the array length is (0, 4096].
queryOptionAVImageQueryOptionsYesRelationship between the time passed in and the video frame.
paramPixelMapParamsYesFormat parameters of the thumbnail to be obtained.
timeoutMsnumberYesTimeout interval for obtaining each thumbnail. The value range is (0, 20000], in milliseconds.
If a thumbnail is not obtained within the specified timeout interval, error code 5400104 is returned.
callbackOnFrameFetchedYesThumbnail information to be returned and possible exception types.
For details about the exception types, see the returned error code information.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by callback.
5400104Fetch timeout. Returned by callback.
5400106Unsupported format. Returned by callback.
5400105Service died.
5400108Parameter check failed. e.g. The size of timesUs is larger than 4096.
5411012Http cleartext not permitted.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';
import { media } from '@kit.MediaKit';

async function fetchFramesByTimesDemo() {
  // Initialize input parameters.
  let timesUs: number[] = [0];
  let timeoutMs: number = 3000;
  let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_PREVIOUS_SYNC;
  let param: media.PixelMapParams = {
    width: 300,
    height: 300
  };
  // Obtain the thumbnail.
  let avMetadataExtractor = await media.createAVMetadataExtractor();
  if (avMetadataExtractor) {
    console.info('Succeeded in creating AVMetadataExtractor');
    avMetadataExtractor.fetchFramesByTimesWithTimeout(timesUs, queryOption, param, timeoutMs, async (frameInfo: media.FrameInfo, err: BusinessError) => {
      if (err) {
        console.error(`fetchFramesByTimes callback failed, code: ${err.code}, message: ${err.message}`);
        return;
      }
      if (frameInfo != undefined && frameInfo.image != undefined) {
        let pixelMap = frameInfo.image;
      }});
  }
}

cancelAllFetchFrames23+

cancelAllFetchFrames(): void

Cancels the ongoing task of obtaining thumbnails in batches. (The thumbnails that have been obtained are not affected.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Example

import { media } from '@kit.MediaKit';

let avMetadataExtractor: media.AVMetadataExtractor|undefined = undefined;

media.createAVMetadataExtractor((error: BusinessError, extractor: media.AVMetadataExtractor) => {
  if (extractor) {
    avMetadataExtractor = extractor;
    console.info('Succeeded in creating AVMetadataExtractor');
    avMetadataExtractor.cancelAllFetchFrames();
  } else {
    console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`);
  }
});

fetchMetadata11+

fetchMetadata(callback: AsyncCallback<AVMetadata>): void

Obtains the media metadata. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<AVMetadata>YesCallback used to return the result, which is an AVMetadata instance.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by callback.
5400106Unsupported format. Returned by callback.
5411012Http cleartext traffic is not permitted.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // Create an AVMetadataExtractor instance.
  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
  avMetadataExtractor.fetchMetadata((error: BusinessError, metadata: media.AVMetadata) => {
    if (error) {
      console.error(`Failed to fetch Metadata, err = ${JSON.stringify(error)}`);
      return;
    }
    console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`);
  });
}

fetchMetadata11+

fetchMetadata(): Promise<AVMetadata>

Obtains the media metadata. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Return value

TypeDescription
Promise<AVMetadata>Promise used to return the result, which is an AVMetadata instance.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by promise.
5400106Unsupported format. Returned by promise.
5411012Http cleartext traffic is not permitted.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // Create an AVMetadataExtractor instance.
  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
  avMetadataExtractor.fetchMetadata().then((metadata: media.AVMetadata) => {
    console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`);
  }).catch((error: BusinessError) => {
    console.error(`Failed to fetch Metadata, error message:${error.message}`);
  });
}

fetchMetadataWithTimeout

fetchMetadataWithTimeout(timeoutMs: number): Promise<AVMetadata|undefined>

Obtains the media metadata. You can set the maximum timeout interval (timeoutMs) for obtaining the metadata. This API uses a promise to return the result.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
timeoutMsnumberYesTimeout interval for obtaining media metadata. The value range is (0, 20000], in milliseconds.
If no metadata is returned within the specified timeout interval, error code 5400104 is returned.

Return value

TypeDescription
Promise<AVMetadata |undefined>Promise used to return the audio and video metadata object (AVMetadata) asynchronously.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by promise.
5400104Operation timeout. Returned by promise.
5400106Unsupported format. Returned by promise.
5400108Parameter check failed. Returned by promise.
5411012Http cleartext traffic is not permitted.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // Create an AVMetadataExtractor instance.
  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
  let timeoutMs = 3000;
  avMetadataExtractor.fetchMetadataWithTimeout(timeoutMs).then((metadata: media.AVMetadata|undefined) => {
    if (metadata) {
      console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`);
    }
  }).catch((error: BusinessError) => {
    console.error(`Failed to fetch Metadata, code: ${error.code}, message: ${error.message}`);
  });
}

fetchAlbumCover11+

fetchAlbumCover(callback: AsyncCallback<image.PixelMap>): void

Obtains the cover of the audio album. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<image.PixelMap>YesCallback used to return the album cover.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Return by callback.
5400106Unsupported format. Returned by callback.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';
import { media } from '@kit.MediaKit';

async function test() {
  // Create an AVMetadataExtractor instance.
  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
  let pixel_map: image.PixelMap|undefined = undefined;

  avMetadataExtractor.fetchAlbumCover((error: BusinessError, pixelMap: image.PixelMap) => {
    if (error) {
      console.error(`Failed to fetch AlbumCover, error = ${JSON.stringify(error)}`);
      return;
    }
    pixel_map = pixelMap;
  });
}

fetchAlbumCover11+

fetchAlbumCover(): Promise<image.PixelMap>

Obtains the cover of the audio album. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Return value

TypeDescription
Promise<image.PixelMap>Promise used to return the album cover.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by promise.
5400106Unsupported format. Returned by promise.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';
import { media } from '@kit.MediaKit';

async function test() {
  // Create an AVMetadataExtractor instance.
  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
  let pixel_map: image.PixelMap|undefined = undefined;

  avMetadataExtractor.fetchAlbumCover().then((pixelMap: image.PixelMap) => {
    pixel_map = pixelMap;
  }).catch((error: BusinessError) => {
    console.error(`Failed to fetch AlbumCover, error message:${error.message}`);
  });
}

release11+

release(callback: AsyncCallback<void>): void

Releases this AVMetadataExtractor instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<void>YesCallback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by callback.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // Create an AVMetadataExtractor instance.
  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
  avMetadataExtractor.release((error: BusinessError) => {
    if (error) {
      console.error(`Failed to release, err = ${JSON.stringify(error)}`);
      return;
    }
    console.info(`Succeeded in releasing.`);
  });
}

release11+

release(): Promise<void>

Releases this AVMetadataExtractor instance. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Return value

TypeDescription
Promise<void>Promise that returns no value.

Error codes

For details about the error codes, see Media Error Codes.

IDError Message
5400102Operation not allowed. Returned by promise.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // Create an AVMetadataExtractor instance.
  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
  avMetadataExtractor.release().then(() => {
    console.info(`Succeeded in releasing.`);
  }).catch((error: BusinessError) => {
    console.error(`Failed to release, error message:${error.message}`);
  });
}

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 capi-avrecorder-oh-avrecorder-range

openharmony 鸿蒙 errorcode-media

openharmony 鸿蒙 capi-avplayer

openharmony 鸿蒙 capi-avplayer-base-h

openharmony 鸿蒙 capi-avimage-generator-h

openharmony 鸿蒙 capi-avscreencapture-oh-rect

openharmony 鸿蒙 capi-videoprocessing-videoprocessing-callback

openharmony 鸿蒙 capi-avsinkbase

openharmony 鸿蒙 capi-avmetadataextractor

openharmony 鸿蒙 capi-avscreencapture-oh-multidisplaycapability

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/OOMdYTvl