• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Interface (AVImageGenerator)
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 12开始支持。
13
14视频缩略图获取类，用于从视频资源中获取缩略图。在调用AVImageGenerator的方法前，需要先通过[createAVImageGenerator()](arkts-apis-media-f.md#mediacreateavimagegenerator12)构建一个AVImageGenerator实例。
15
16获取视频缩略图的demo可参考：[获取视频缩略图开发指导](../../media/media/avimagegenerator.md)。
17
18## 导入模块
19
20```ts
21import { media } from '@kit.MediaKit';
22```
23
24## 属性
25
26**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator
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
32## fetchFrameByTime<sup>12+</sup>
33
34fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams, callback: AsyncCallback\<image.PixelMap>): void
35
36异步方式获取视频缩略图。通过注册回调函数获取返回值。
37
38**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator
39
40**参数：**
41
42| 参数名   | 类型                                         | 必填 | 说明                                |
43| -------- | -------------------------------------------- | ---- | ----------------------------------- |
44| timeUs | number                   | 是   | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 |
45| options | [AVImageQueryOptions](arkts-apis-media-e.md#avimagequeryoptions12)     | 是   | 需要获取的缩略图时间点与视频帧的对应关系。 |
46| param | [PixelMapParams](arkts-apis-media-i.md#pixelmapparams12)     | 是   | 需要获取的缩略图的格式参数。 |
47| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)>   | 是   | 回调函数。获取缩略图成功时，err为undefined，data为PixelMap实例，否则为错误对象。 |
48
49**错误码：**
50
51以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
52
53| 错误码ID | 错误信息                                   |
54| -------- | ------------------------------------------ |
55| 5400102  | Operation not allowed. Returned by callback. |
56| 5400106  | Unsupported format. Returned by callback.  |
57
58**示例：**
59
60```ts
61import { BusinessError } from '@kit.BasicServicesKit';
62import { image } from '@kit.ImageKit';
63import { media } from '@kit.MediaKit';
64
65let avImageGenerator: media.AVImageGenerator | undefined = undefined;
66let pixel_map : image.PixelMap | undefined = undefined;
67
68// 初始化入参。
69let timeUs: number = 0;
70
71let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC;
72
73let param: media.PixelMapParams = {
74  width : 300,
75  height : 300,
76};
77
78// 获取缩略图。
79media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => {
80  if(generator != null){
81    avImageGenerator = generator;
82    console.info(`Succeeded in creating AVImageGenerator`);
83    avImageGenerator.fetchFrameByTime(timeUs, queryOption, param, (error: BusinessError, pixelMap) => {
84      if (error) {
85        console.error(`Failed to fetch FrameByTime, err = ${JSON.stringify(error)}`);
86        return;
87      }
88      pixel_map = pixelMap;
89    });
90  } else {
91    console.error(`Failed to creat AVImageGenerator, error message:${err.message}`);
92  };
93});
94```
95
96## fetchFrameByTime<sup>12+</sup>
97
98fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams): Promise<image.PixelMap>
99
100异步方式获取视频缩略图。通过Promise获取返回值。
101
102**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator
103
104**参数：**
105
106| 参数名   | 类型                                         | 必填 | 说明                                |
107| -------- | -------------------------------------------- | ---- | ----------------------------------- |
108| timeUs | number                   | 是   | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 |
109| options | [AVImageQueryOptions](arkts-apis-media-e.md#avimagequeryoptions12)     | 是   | 需要获取的缩略图时间点与视频帧的对应关系。 |
110| param | [PixelMapParams](arkts-apis-media-i.md#pixelmapparams12)    | 是   | 需要获取的缩略图的格式参数。 |
111
112**返回值：**
113
114| 类型           | 说明                                     |
115| -------------- | ---------------------------------------- |
116| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象，返回视频缩略图对象。 |
117
118**错误码：**
119
120以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
121
122| 错误码ID | 错误信息                                  |
123| -------- | ----------------------------------------- |
124| 5400102  | Operation not allowed. Returned by promise. |
125| 5400106  | Unsupported format. Returned by promise.  |
126
127**示例：**
128
129```ts
130import { BusinessError } from '@kit.BasicServicesKit';
131import { image } from '@kit.ImageKit';
132import { media } from '@kit.MediaKit';
133
134let avImageGenerator: media.AVImageGenerator | undefined = undefined;
135let pixel_map : image.PixelMap | undefined = undefined;
136
137// 初始化入参。
138let timeUs: number = 0;
139
140let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC;
141
142let param: media.PixelMapParams = {
143  width : 300,
144  height : 300,
145};
146
147// 获取缩略图。
148media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => {
149  if(generator != null){
150    avImageGenerator = generator;
151    console.info(`Succeeded in creating AVImageGenerator`);
152    avImageGenerator.fetchFrameByTime(timeUs, queryOption, param).then((pixelMap: image.PixelMap) => {
153      pixel_map = pixelMap;
154    }).catch((error: BusinessError) => {
155      console.error(`Failed to fetch FrameByTime, error message:${error.message}`);
156    });
157  } else {
158    console.error(`Failed to creat AVImageGenerator, error message:${err.message}`);
159  };
160});
161```
162
163## fetchScaledFrameByTime<sup>20+</sup>
164
165fetchScaledFrameByTime(timeUs: number, queryMode: AVImageQueryOptions, outputSize?: OutputSize):Promise\<image.PixelMap\>
166
167支持按比例缩放提取视频缩略图。使用Promise异步回调。
168
169**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator
170
171**参数：**
172
173| 参数名     | 类型                                          | 必填 | 说明                                                 |
174| ---------- | --------------------------------------------- | ---- | ---------------------------------------------------- |
175| timeUs     | number                                        | 是   | 在视频中需要获取的缩略图的时间点，单位为微秒（μs）。 |
176| queryMode  | [AVImageQueryOptions](arkts-apis-media-e.md#avimagequeryoptions12) | 是   | 需要获取的缩略图时间点与视频帧的对应关系。           |
177| outputSize | [OutputSize ](arkts-apis-media-i.md#outputsize20)                  | 否   | 定义帧的输出大小。默认按原图大小显示。               |
178
179**返回值：**
180
181| 类型                                                         | 说明                              |
182| ------------------------------------------------------------ | --------------------------------- |
183| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象。返回视频缩略图对象。 |
184
185**错误码：**
186
187以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
188
189| 错误码ID | 错误信息                                    |
190| -------- | ------------------------------------------- |
191| 5400102  | Operation not allowed. Returned by promise. |
192| 5400106  | Unsupported format. Returned by promise.    |
193
194**示例：**
195
196```ts
197import { BusinessError } from '@kit.BasicServicesKit';
198import { image } from '@kit.ImageKit';
199import { media } from '@kit.MediaKit';
200let avImageGenerator: media.AVImageGenerator | undefined = undefined;
201let pixel_map : image.PixelMap | undefined = undefined;
202// 初始化入参。
203let timeUs: number = 0;
204let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC;
205let outputSize: media.OutputSize = {
206  width : 300,
207  height : 300,
208};
209// 获取缩略图。
210media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => {
211  if(generator != null){
212    avImageGenerator = generator;
213    console.info(`Succeeded in creating AVImageGenerator`);
214    avImageGenerator.fetchScaledFrameByTime(timeUs, queryOption, outputSize).then((pixelMap: image.PixelMap) => {
215      pixel_map = pixelMap;
216    }).catch((error: BusinessError) => {
217      console.error(`Failed to fetch ScaledFrameByTime, error message:${error.message}`);
218    });
219  } else {
220    console.error(`Failed to creat AVImageGenerator, error message:${err.message}`);
221  };
222});
223```
224
225## release<sup>12+</sup>
226
227release(callback: AsyncCallback\<void>): void
228
229异步方式释放资源。通过注册回调函数获取返回值。
230
231**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator
232
233**参数：**
234
235| 参数名   | 类型                                         | 必填 | 说明                                |
236| -------- | -------------------------------------------- | ---- | ----------------------------------- |
237| callback | AsyncCallback\<void>                   | 是   | 回调函数。当释放资源成功，err为undefined，否则为错误对象。 |
238
239**错误码：**
240
241以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
242
243| 错误码ID | 错误信息                                   |
244| -------- | ------------------------------------------ |
245| 5400102  | Operation not allowed. Returned by callback. |
246
247**示例：**
248
249```ts
250import { BusinessError } from '@kit.BasicServicesKit';
251import { media } from '@kit.MediaKit';
252
253let avImageGenerator: media.AVImageGenerator | undefined = undefined;
254
255//释放资源。
256media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => {
257  if(generator != null){
258    avImageGenerator = generator;
259    console.info(`Succeeded in creating AVImageGenerator`);
260    avImageGenerator.release((error: BusinessError) => {
261      if (error) {
262        console.error(`Failed to release, err = ${JSON.stringify(error)}`);
263        return;
264      }
265      console.info(`Succeeded in releasing`);
266    });
267  } else {
268    console.error(`Failed to creat AVImageGenerator, error message:${err.message}`);
269  };
270});
271```
272
273## release<sup>12+</sup>
274
275release(): Promise\<void>
276
277异步方式释放资源。通过Promise获取返回值。
278
279**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator
280
281**返回值：**
282
283| 类型           | 说明                                     |
284| -------------- | ---------------------------------------- |
285| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 |
286
287**错误码：**
288
289以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
290
291| 错误码ID | 错误信息                                  |
292| -------- | ----------------------------------------- |
293| 5400102  | Operation not allowed. Returned by promise. |
294
295**示例：**
296
297```ts
298import { BusinessError } from '@kit.BasicServicesKit';
299import { media } from '@kit.MediaKit';
300
301let avImageGenerator: media.AVImageGenerator | undefined = undefined;
302
303//释放资源
304media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => {
305  if(generator != null){
306    avImageGenerator = generator;
307    console.info(`Succeeded in creating AVImageGenerator`);
308    avImageGenerator.release().then(() => {
309      console.info(`Succeeded in releasing.`);
310    }).catch((error: BusinessError) => {
311      console.error(`Failed to release, error message:${error.message}`);
312    });
313  } else {
314    console.error(`Failed to creat AVImageGenerator, error message:${err.message}`);
315  };
316});
317```
318