harmony 鸿蒙Interface (AVMetadataExtractor)

2025-06-16
浏览 (2)

Interface (AVMetadataExtractor)

说明： 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

元数据获取类，用于从媒体资源中获取元数据。在调用AVMetadataExtractor的方法前，需要先通过createAVMetadataExtractor()构建一个AVMetadataExtractor实例。

属性

系统能力： SystemCapability.Multimedia.Media.AVMetadataExtractor

名称	类型	可读	可写	说明
fdSrc¹¹⁺	AVFileDescriptor	是	是	媒体文件描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。使用示例：假设一个连续存储的媒体文件，地址偏移:0，字节长度:100。其文件描述为 AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。说明： - 将资源句柄（fd）传递给 AVMetadataExtractor 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致音视频元数据获取异常。
dataSrc¹¹⁺	AVDataSrcDescriptor	是	是	流式媒体资源描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。当应用从远端获取音视频媒体文件，在应用未下载完整音视频资源时，可以设置dataSrc提前获取该资源的元数据。

fetchMetadata¹¹⁺

fetchMetadata(callback: AsyncCallback<AVMetadata>): void

异步方式获取媒体元数据。通过注册回调函数获取返回值。

系统能力： SystemCapability.Multimedia.Media.AVMetadataExtractor

参数：

参数名	类型	必填	说明
callback	AsyncCallback<AVMetadata>	是	回调函数。异步返回音视频元数据对象（AVMetadata）。

错误码：

以下错误码的详细介绍请参见媒体错误码。

错误码ID	错误信息
5400102	Operation not allowed. Returned by callback.
5400106	Unsupported format. Returned by callback.

示例：

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

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}`);
});

fetchMetadata¹¹⁺

fetchMetadata(): Promise<AVMetadata>

异步方式获取媒体元数据。通过Promise获取返回值。

系统能力： SystemCapability.Multimedia.Media.AVMetadataExtractor

返回值：

类型	说明
Promise<AVMetadata>	Promise对象。异步返回音视频元数据对象（AVMetadata）。

错误码：

以下错误码的详细介绍请参见媒体错误码。

错误码ID	错误信息
5400102	Operation not allowed. Returned by promise.
5400106	Unsupported format. Returned by promise.

示例：

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

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}`);
});

fetchAlbumCover¹¹⁺

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

异步方式获取音频专辑封面。通过注册回调函数获取返回值。

系统能力： SystemCapability.Multimedia.Media.AVMetadataExtractor

参数：

参数名	类型	必填	说明
callback	AsyncCallback<image.PixelMap>	是	回调函数。异步返回专辑封面。

错误码：

以下错误码的详细介绍请参见媒体错误码。

错误码ID	错误信息
5400102	Operation not allowed. Return by callback.
5400106	Unsupported format. Returned by callback.

示例：

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

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;
});

fetchAlbumCover¹¹⁺

fetchAlbumCover(): Promise<image.PixelMap>

异步方式获取专辑封面。通过Promise获取返回值。

系统能力： SystemCapability.Multimedia.Media.AVMetadataExtractor

返回值：

类型	说明
Promise<image.PixelMap>	Promise对象。异步返回专辑封面。

错误码：

以下错误码的详细介绍请参见媒体错误码。

错误码ID	错误信息
5400102	Operation not allowed. Returned by promise.
5400106	Unsupported format. Returned by promise.

示例：

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

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}`);
});

release¹¹⁺

release(callback: AsyncCallback<void>): void

异步方式释放资源。通过注册回调函数获取返回值。

系统能力： SystemCapability.Multimedia.Media.AVMetadataExtractor

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。当释放资源成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见媒体错误码。

错误码ID	错误信息
5400102	Operation not allowed. Returned by callback.

示例：

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

avMetadataExtractor.release((error: BusinessError) => {
  if (error) {
    console.error(`Failed to release, err = ${JSON.stringify(error)}`);
    return;
  }
  console.info(`Succeeded in releasing.`);
});

release¹¹⁺

release(): Promise<void>

异步方式释放资源。通过Promise获取返回值。

系统能力： SystemCapability.Multimedia.Media.AVMetadataExtractor

返回值：

类型	说明
Promise<void>	异步方式释放资源release方法的Promise返回值。

错误码：

以下错误码的详细介绍请参见媒体错误码。

错误码ID	错误信息
5400102	Operation not allowed. Returned by promise.

示例：

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

avMetadataExtractor.release().then(() => {
  console.info(`Succeeded in releasing.`);
}).catch((error: BusinessError) => {
  console.error(`Failed to release, error message:${error.message}`);
});