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> **NOTE** 10> 11> - 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. 12> - The initial APIs of this interface are supported since API version 12. 13 14AVImageGenerator is a class for video thumbnail retrieval. It provides APIs to obtain a thumbnail from a video. Before calling any API in AVImageGenerator, you must use [createAVImageGenerator()](arkts-apis-media-f.md#mediacreateavimagegenerator12) to create an AVImageGenerator instance. 15 16For details about the demo for obtaining video thumbnails, see [Obtaining Video Thumbnails](../../media/media/avimagegenerator.md). 17 18## Modules to Import 19 20```ts 21import { media } from '@kit.MediaKit'; 22``` 23 24## Properties 25 26**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 27 28| Name | Type | Read-Only| Optional| Description | 29| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 30| fdSrc<sup>12+</sup> | [AVFileDescriptor](arkts-apis-media-i.md#avfiledescriptor9) | No | Yes | Media file descriptor, which specifies the data source.<br> **Example:**<br>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; }**.<br>**NOTE**<br> After the resource handle (FD) is transferred to an AVImageGenerator 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 AVImageGenerator use the same resource handle to read and write files at the same time, resulting in errors in obtaining data.| 31 32## fetchFrameByTime<sup>12+</sup> 33 34fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams, callback: AsyncCallback\<image.PixelMap>): void 35 36Obtains a video thumbnail. This API uses an asynchronous callback to return the result. 37 38**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 39 40**Parameters** 41 42| Name | Type | Mandatory| Description | 43| -------- | -------------------------------------------- | ---- | ----------------------------------- | 44| timeUs | number | Yes | Time of the video for which a thumbnail is to be obtained, in μs.| 45| options | [AVImageQueryOptions](arkts-apis-media-e.md#avimagequeryoptions12) | Yes | Relationship between the thumbnail timestamp in and the video frame.| 46| param | [PixelMapParams](arkts-apis-media-i.md#pixelmapparams12) | Yes | Format parameters of the thumbnail to be obtained.| 47| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the PixelMap instance obtained; otherwise, **err** is an error object.| 48 49**Error codes** 50 51For details about the error codes, see [Media Error Codes](errorcode-media.md). 52 53| ID| Error Message | 54| -------- | ------------------------------------------ | 55| 5400102 | Operation not allowed. Returned by callback. | 56| 5400106 | Unsupported format. Returned by callback. | 57 58**Example** 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// Initialize input parameters. 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// Obtain the thumbnail. 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 100Obtains a video thumbnail. This API uses a promise to return the result. 101 102**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 103 104**Parameters** 105 106| Name | Type | Mandatory| Description | 107| -------- | -------------------------------------------- | ---- | ----------------------------------- | 108| timeUs | number | Yes | Time of the video for which a thumbnail is to be obtained, in μs.| 109| options | [AVImageQueryOptions](arkts-apis-media-e.md#avimagequeryoptions12) | Yes | Relationship between the thumbnail timestamp in and the video frame.| 110| param | [PixelMapParams](arkts-apis-media-i.md#pixelmapparams12) | Yes | Format parameters of the thumbnail to be obtained.| 111 112**Return value** 113 114| Type | Description | 115| -------------- | ---------------------------------------- | 116| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise used to return the video thumbnail.| 117 118**Error codes** 119 120For details about the error codes, see [Media Error Codes](errorcode-media.md). 121 122| ID| Error Message | 123| -------- | ----------------------------------------- | 124| 5400102 | Operation not allowed. Returned by promise. | 125| 5400106 | Unsupported format. Returned by promise. | 126 127**Example** 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// Initialize input parameters. 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// Obtain the thumbnail. 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 167Fetches a scaled thumbnail from the video at a particular timestamp. This API uses a promise to return the result. 168 169**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 170 171**Parameters** 172 173| Name | Type | Mandatory| Description | 174| ---------- | --------------------------------------------- | ---- | ---------------------------------------------------- | 175| timeUs | number | Yes | Timestamp, in microseconds (μs), at which the thumbnail is to be fetched from the video.| 176| queryMode | [AVImageQueryOptions](arkts-apis-media-e.md#avimagequeryoptions12) | Yes | Relationship between the thumbnail timestamp in and the video frame. | 177| outputSize | [OutputSize ](arkts-apis-media-i.md#outputsize20) | No | Output size of the thumbnail. By default, the original image size is used. | 178 179**Return value** 180 181| Type | Description | 182| ------------------------------------------------------------ | --------------------------------- | 183| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise used to return the video thumbnail.| 184 185**Error codes** 186 187For details about the error codes, see [Media Error Codes](errorcode-media.md). 188 189| ID| Error Message | 190| -------- | ------------------------------------------- | 191| 5400102 | Operation not allowed. Returned by promise. | 192| 5400106 | Unsupported format. Returned by promise. | 193 194**Example** 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// Initialize input parameters. 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// Obtain the thumbnail. 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 229Releases this AVImageGenerator instance. This API uses an asynchronous callback to return the result. 230 231**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 232 233**Parameters** 234 235| Name | Type | Mandatory| Description | 236| -------- | -------------------------------------------- | ---- | ----------------------------------- | 237| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 238 239**Error codes** 240 241For details about the error codes, see [Media Error Codes](errorcode-media.md). 242 243| ID| Error Message | 244| -------- | ------------------------------------------ | 245| 5400102 | Operation not allowed. Returned by callback. | 246 247**Example** 248 249```ts 250import { BusinessError } from '@kit.BasicServicesKit'; 251import { media } from '@kit.MediaKit'; 252 253let avImageGenerator: media.AVImageGenerator | undefined = undefined; 254 255// Release the resources. 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 277Releases this AVImageGenerator instance. This API uses a promise to return the result. 278 279**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 280 281**Return value** 282 283| Type | Description | 284| -------------- | ---------------------------------------- | 285| Promise\<void> | Promise that returns no value.| 286 287**Error codes** 288 289For details about the error codes, see [Media Error Codes](errorcode-media.md). 290 291| ID| Error Message | 292| -------- | ----------------------------------------- | 293| 5400102 | Operation not allowed. Returned by promise. | 294 295**Example** 296 297```ts 298import { BusinessError } from '@kit.BasicServicesKit'; 299import { media } from '@kit.MediaKit'; 300 301let avImageGenerator: media.AVImageGenerator | undefined = undefined; 302 303// Release the instance. 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