• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Interface (AVMetadataExtractor)
2<!--Kit: Media Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @wang-haizhou6-->
5<!--Designer: @HmQQQ-->
6<!--Tester: @xchaosioda-->
7<!--Adviser: @zengyawen-->
8
9> **说明：**
10>
11> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
12> - 本Interface首批接口从API version 11开始支持。
13
14元数据获取类，用于从媒体资源中获取元数据、缩略图。在调用AVMetadataExtractor的方法前，需要先通过[media.createAVMetadataExtractor](arkts-apis-media-f.md#mediacreateavmetadataextractor11)构建一个AVMetadataExtractor实例。
15
16获取音频或视频元数据、视频缩略图的demo可参考：[使用AVMetadataExtractor提取音视频元数据信息(ArkTS)](../../media/media/avmetadataextractor.md)。
17
18## 导入模块
19
20```ts
21import { media } from '@kit.MediaKit';
22```
23
24## 属性
25
26**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor
27
28| 名称                                                | 类型                                                         | 只读 | 可选 | 说明                                                         |
29| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ |
30| fdSrc<sup>12+</sup>                                  | [AVFileDescriptor](arkts-apis-media-i.md#avfiledescriptor9)                       | 否   | 是   | 媒体文件描述，通过该属性设置数据源。<br/> **使用示例**：<br/>假设一个连续存储的媒体文件，地址偏移：0，字节长度：100。其文件描述为AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br>**说明：** <br> 将资源句柄（fd）传递给AVImageGenerator实例之后，不允许通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个AVPlayer/AVMetadataExtractor/AVImageGenerator/AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频缩略图数据获取异常。 |
31| dataSrc<sup>11+</sup>                               | [AVDataSrcDescriptor](arkts-apis-media-i.md#avdatasrcdescriptor10)                | 是   | 是   | 流式媒体资源描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。<br/> 当应用从远端获取音视频媒体文件，在应用未下载完整音视频资源时，可以设置dataSrc提前获取该资源的元数据。|
32
33## setUrlSource<sup>20+</sup>
34
35setUrlSource(url: string, headers?: Record\<string, string>): void
36
37网络点播资源地址描述，通过该接口设置数据源。只支持获取网络[fetchMetadata](#fetchmetadata11)（元数据）和[fetchFrameByTime](#fetchframebytime20)（缩略图），在获取之前，必须设置媒体资源URL。
38
39**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor
40
41**参数：**
42
43| 参数名   | 类型                                         | 必填 | 说明                                |
44| -------- | -------------------------------------------- | ---- | ----------------------------------- |
45| url | string       | 是   | 媒体资源URL。<br/>1. 支持的视频格式包括：mp4、mpeg-ts、mkv。<br/>2. 支持的音频格式包括：m4a、aac、mp3、ogg、wav、flac、amr。<br/>**支持路径示例**：<br/>1. http网络播放：`http\://xx`。<br/>2. https网络播放：`https\://xx`。<br/>**说明：** 不支持设置hls/dash、直播资源。|
46| headers | Record\<string, string> | 否   | 支持访问网络资源HttpHeader自定义。默认为空。|
47
48**示例：**
49
50```ts
51import { BusinessError } from '@kit.BasicServicesKit';
52import { media } from '@kit.MediaKit';
53
54let avMetadataExtractor: media.AVMetadataExtractor | undefined = undefined;
55
56media.createAVMetadataExtractor(async (error: BusinessError, extractor: media.AVMetadataExtractor) => {
57  if (extractor != null) {
58    avMetadataExtractor = extractor;
59    console.info('Succeeded in creating AVMetadataExtractor');
60    let url = "http://xx";
61    let headers: Record<string, string> = {
62      "User-Agent" : "User-Agent-Value"
63    };
64    avMetadataExtractor.setUrlSource(url, headers);
65  } else {
66    console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`);
67  }
68});
69```
70
71## fetchFrameByTime<sup>20+</sup>
72
73fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams): Promise\<image.PixelMap>
74
75获取视频缩略图。使用Promise异步回调。
76
77**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor
78
79**参数：**
80
81| 参数名   | 类型                                         | 必填 | 说明                                |
82| -------- | -------------------------------------------- | ---- | ----------------------------------- |
83| timeUs | number                   | 是   | 需要获取的缩略图在视频中的时间点，单位为微秒（us）。 |
84| options | [AVImageQueryOptions](arkts-apis-media-e.md#avimagequeryoptions12)     | 是   | 需要获取的缩略图时间点与视频帧的对应关系。 |
85| param | [PixelMapParams](arkts-apis-media-i.md#pixelmapparams12)    | 是   | 需要获取的缩略图的格式参数。 |
86
87**返回值：**
88
89| 类型           | 说明                                     |
90| -------------- | ---------------------------------------- |
91| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象，返回视频缩略图对象。 |
92
93**错误码：**
94
95以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)
96
97| 错误码ID | 错误信息                                  |
98| -------- | ----------------------------------------- |
99| 5400102  | Operation not allowed. Returned by promise. |
100| 5400106  | Unsupported format. Returned by promise.  |
101| 5400108  | Parameter check failed. Returned by promise. |
102
103**示例：**
104
105```ts
106import { BusinessError } from '@kit.BasicServicesKit';
107import { image } from '@kit.ImageKit';
108import { media } from '@kit.MediaKit';
109
110let avMetadataExtractor: media.AVMetadataExtractor | undefined = undefined;
111let pixel_map : image.PixelMap | undefined = undefined;
112
113// 初始化入参。
114let timeUs: number = 0;
115let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_PREVIOUS_SYNC;
116let param: media.PixelMapParams = {
117  width : 300,
118  height : 300
119};
120// 获取缩略图。
121media.createAVMetadataExtractor((error: BusinessError, extractor: media.AVMetadataExtractor) => {
122  if (extractor != null) {
123    avMetadataExtractor = extractor;
124    console.info('Succeeded in creating AVMetadataExtractor');
125    avMetadataExtractor.fetchFrameByTime(timeUs, queryOption, param).then((pixelMap: image.PixelMap) => {
126      pixel_map = pixelMap;
127    }).catch((error: BusinessError) => {
128      console.error(`Failed to fetch FrameByTime, error message:${error.message}`);
129    });
130  } else {
131    console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`);
132  }
133});
134```
135
136## fetchMetadata<sup>11+</sup>
137
138fetchMetadata(callback: AsyncCallback\<AVMetadata>): void
139
140异步方式获取媒体元数据。通过注册回调函数获取返回值。
141
142**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor
143
144**参数：**
145
146| 参数名   | 类型                                         | 必填 | 说明                                |
147| -------- | -------------------------------------------- | ---- | ----------------------------------- |
148| callback | AsyncCallback\<[AVMetadata](arkts-apis-media-i.md#avmetadata11)>       | 是   | 回调函数。异步返回音视频元数据对象（AVMetadata）。|
149
150**错误码：**
151
152以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
153
154| 错误码ID | 错误信息                                   |
155| -------- | ------------------------------------------ |
156| 5400102  | Operation not allowed. Returned by callback. |
157| 5400106  | Unsupported format. Returned by callback.  |
158
159**示例：**
160
161```ts
162import { BusinessError } from '@kit.BasicServicesKit';
163import { media } from '@kit.MediaKit';
164
165async function test() {
166  // 创建AVMetadataExtractor对象。
167  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
168  avMetadataExtractor.fetchMetadata((error: BusinessError, metadata: media.AVMetadata) => {
169    if (error) {
170      console.error(`Failed to fetch Metadata, err = ${JSON.stringify(error)}`);
171      return;
172    }
173    console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`);
174  });
175}
176```
177
178## fetchMetadata<sup>11+</sup>
179
180fetchMetadata(): Promise\<AVMetadata>
181
182异步方式获取媒体元数据。通过Promise获取返回值。
183
184**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor
185
186**返回值：**
187
188| 类型           | 说明                                     |
189| -------------- | ---------------------------------------- |
190| Promise\<[AVMetadata](arkts-apis-media-i.md#avmetadata11)>  | Promise对象。异步返回音视频元数据对象（AVMetadata）。 |
191
192**错误码：**
193
194以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
195
196| 错误码ID | 错误信息                                  |
197| -------- | ----------------------------------------- |
198| 5400102  | Operation not allowed. Returned by promise. |
199| 5400106  | Unsupported format. Returned by promise.  |
200
201**示例：**
202
203```ts
204import { BusinessError } from '@kit.BasicServicesKit';
205import { media } from '@kit.MediaKit';
206
207async function test() {
208  // 创建AVMetadataExtractor对象。
209  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
210  avMetadataExtractor.fetchMetadata().then((metadata: media.AVMetadata) => {
211    console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`);
212  }).catch((error: BusinessError) => {
213    console.error(`Failed to fetch Metadata, error message:${error.message}`);
214  });
215}
216```
217
218## fetchAlbumCover<sup>11+</sup>
219
220fetchAlbumCover(callback: AsyncCallback\<image.PixelMap>): void
221
222异步方式获取音频专辑封面。通过注册回调函数获取返回值。
223
224**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor
225
226**参数：**
227
228| 参数名   | 类型                                         | 必填 | 说明                                |
229| -------- | -------------------------------------------- | ---- | ----------------------------------- |
230| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)>    | 是   | 回调函数。异步返回专辑封面。 |
231
232**错误码：**
233
234以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
235
236| 错误码ID | 错误信息                                   |
237| -------- | ------------------------------------------ |
238| 5400102  | Operation not allowed. Return by callback. |
239| 5400106  | Unsupported format. Returned by callback.  |
240
241**示例：**
242
243```ts
244import { BusinessError } from '@kit.BasicServicesKit';
245import { image } from '@kit.ImageKit';
246import { media } from '@kit.MediaKit';
247
248async function test() {
249  // 创建AVMetadataExtractor对象。
250  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
251  let pixel_map : image.PixelMap | undefined = undefined;
252
253  avMetadataExtractor.fetchAlbumCover((error: BusinessError, pixelMap: image.PixelMap) => {
254    if (error) {
255      console.error(`Failed to fetch AlbumCover, error = ${JSON.stringify(error)}`);
256      return;
257    }
258    pixel_map = pixelMap;
259  });
260}
261```
262
263## fetchAlbumCover<sup>11+</sup>
264
265fetchAlbumCover(): Promise\<image.PixelMap>
266
267异步方式获取专辑封面。通过Promise获取返回值。
268
269**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor
270
271**返回值：**
272
273| 类型           | 说明                                     |
274| -------------- | ---------------------------------------- |
275| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> |  Promise对象。异步返回专辑封面。 |
276
277**错误码：**
278
279以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
280
281| 错误码ID | 错误信息                                  |
282| -------- | ----------------------------------------- |
283| 5400102  | Operation not allowed. Returned by promise. |
284| 5400106  | Unsupported format. Returned by promise.  |
285
286**示例：**
287
288```ts
289import { BusinessError } from '@kit.BasicServicesKit';
290import { image } from '@kit.ImageKit';
291import { media } from '@kit.MediaKit';
292
293async function test() {
294  // 创建AVMetadataExtractor对象。
295  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
296  let pixel_map : image.PixelMap | undefined = undefined;
297
298  avMetadataExtractor.fetchAlbumCover().then((pixelMap: image.PixelMap) => {
299    pixel_map = pixelMap;
300  }).catch((error: BusinessError) => {
301    console.error(`Failed to fetch AlbumCover, error message:${error.message}`);
302  });
303}
304```
305
306## release<sup>11+</sup>
307
308release(callback: AsyncCallback\<void>): void
309
310异步方式释放资源。通过注册回调函数获取返回值。
311
312**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor
313
314**参数：**
315
316| 参数名   | 类型                                         | 必填 | 说明                                |
317| -------- | -------------------------------------------- | ---- | ----------------------------------- |
318| callback | AsyncCallback\<void>                   | 是   |回调函数。当释放资源成功，err为undefined，否则为错误对象。 |
319
320**错误码：**
321
322以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
323
324| 错误码ID | 错误信息                                   |
325| -------- | ------------------------------------------ |
326| 5400102  | Operation not allowed. Returned by callback. |
327
328**示例：**
329
330```ts
331import { BusinessError } from '@kit.BasicServicesKit';
332import { media } from '@kit.MediaKit';
333
334async function test() {
335  // 创建AVMetadataExtractor对象。
336  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
337  avMetadataExtractor.release((error: BusinessError) => {
338    if (error) {
339      console.error(`Failed to release, err = ${JSON.stringify(error)}`);
340      return;
341    }
342    console.info(`Succeeded in releasing.`);
343  });
344}
345```
346
347## release<sup>11+</sup>
348
349release(): Promise\<void>
350
351异步方式释放资源。通过Promise获取返回值。
352
353**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor
354
355**返回值：**
356
357| 类型           | 说明                                     |
358| -------------- | ---------------------------------------- |
359| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 |
360
361**错误码：**
362
363以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
364
365| 错误码ID | 错误信息                                  |
366| -------- | ----------------------------------------- |
367| 5400102  | Operation not allowed. Returned by promise. |
368
369**示例：**
370
371```ts
372import { BusinessError } from '@kit.BasicServicesKit';
373import { media } from '@kit.MediaKit';
374
375async function test() {
376  // 创建AVMetadataExtractor对象。
377  let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor();
378  avMetadataExtractor.release().then(() => {
379    console.info(`Succeeded in releasing.`);
380  }).catch((error: BusinessError) => {
381    console.error(`Failed to release, error message:${error.message}`);
382  });
383}
384```
385