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> **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 11. 13 14AVMetadataExtractor 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](arkts-apis-media-f.md#mediacreateavmetadataextractor11) to create an AVMetadataExtractor instance. 15 16For details about the demo of obtaining audio or video metadata and video thumbnails, see [Using AVMetadataExtractor to Extract Audio and Video Metadata (ArkTS)](../../media/media/avmetadataextractor.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.AVMetadataExtractor 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 AVMetadataExtractor use the same resource handle to read and write files at the same time, resulting in errors in obtaining video thumbnail data.| 31| dataSrc<sup>11+</sup> | [AVDataSrcDescriptor](arkts-apis-media-i.md#avdatasrcdescriptor10) | Yes | Yes | Streaming media resource descriptor, which specifies the data source. Before obtaining metadata, you must set the data source through either **fdSrc** or **dataSrc**.<br> When an application obtains a media file from the remote, you can set **dataSrc** to obtain the metadata before the application finishes the downloading.| 32 33## setUrlSource<sup>20+</sup> 34 35setUrlSource(url: string, headers?: Record\<string, string>): void 36 37Sets the data source for a network on-demand resource. Only network metadata ([fetchMetadata](#fetchmetadata11)) and thumbnails ([fetchFrameByTime](#fetchframebytime20)) can be obtained. The media resource URL must be set before the retrieval. 38 39**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 40 41**Parameters** 42 43| Name | Type | Mandatory| Description | 44| -------- | -------------------------------------------- | ---- | ----------------------------------- | 45| url | string | Yes | URL of the media resource.<br>1. The video formats MP4, MPEG-TS, and MKV are supported.<br>2. The audio formats M4A, AAC, MP3, OGG, WAV, FLAC, and AMR are supported.<br>**Example of supported URLs**:<br>1. HTTP: http\://xx<br>2. HTTPS: https\://xx<br>Note: HLS/DASH and live streaming resources cannot be set.| 46| headers | Record\<string, string> | No | Custom HTTP headers for accessing the network resource. The default value is empty.| 47 48**Example** 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 75Obtains a video thumbnail. This API uses a promise to return the result. 76 77**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 78 79**Parameters** 80 81| Name | Type | Mandatory| Description | 82| -------- | -------------------------------------------- | ---- | ----------------------------------- | 83| timeUs | number | Yes | Time of the video for which a thumbnail is to be obtained, in us.| 84| options | [AVImageQueryOptions](arkts-apis-media-e.md#avimagequeryoptions12) | Yes | Relationship between the time passed in and the video frame.| 85| param | [PixelMapParams](arkts-apis-media-i.md#pixelmapparams12) | Yes | Format parameters of the thumbnail to be obtained.| 86 87**Return value** 88 89| Type | Description | 90| -------------- | ---------------------------------------- | 91| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise used to return the video thumbnail.| 92 93**Error codes** 94 95For details about the error codes, see [Media Error Codes](errorcode-media.md). 96 97| ID| Error Message | 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**Example** 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// Initialize input parameters. 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// Obtain the thumbnail. 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 140Obtains media metadata. This API uses an asynchronous callback to return the result. 141 142**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 143 144**Parameters** 145 146| Name | Type | Mandatory| Description | 147| -------- | -------------------------------------------- | ---- | ----------------------------------- | 148| callback | AsyncCallback\<[AVMetadata](arkts-apis-media-i.md#avmetadata11)> | Yes | Callback used to return the result, which is an AVMetadata instance.| 149 150**Error codes** 151 152For details about the error codes, see [Media Error Codes](errorcode-media.md). 153 154| ID| Error Message | 155| -------- | ------------------------------------------ | 156| 5400102 | Operation not allowed. Returned by callback. | 157| 5400106 | Unsupported format. Returned by callback. | 158 159**Example** 160 161```ts 162import { BusinessError } from '@kit.BasicServicesKit'; 163import { media } from '@kit.MediaKit'; 164 165async function test() { 166 // Create an AVMetadataExtractor instance. 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 182Obtains media metadata. This API uses a promise to return the result. 183 184**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 185 186**Return value** 187 188| Type | Description | 189| -------------- | ---------------------------------------- | 190| Promise\<[AVMetadata](arkts-apis-media-i.md#avmetadata11)> | Promise used to return the result. which is an AVMetadata instance.| 191 192**Error codes** 193 194For details about the error codes, see [Media Error Codes](errorcode-media.md). 195 196| ID| Error Message | 197| -------- | ----------------------------------------- | 198| 5400102 | Operation not allowed. Returned by promise. | 199| 5400106 | Unsupported format. Returned by promise. | 200 201**Example** 202 203```ts 204import { BusinessError } from '@kit.BasicServicesKit'; 205import { media } from '@kit.MediaKit'; 206 207async function test() { 208 // Create an AVMetadataExtractor instance. 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 222Obtains the cover of the audio album. This API uses an asynchronous callback to return the result. 223 224**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 225 226**Parameters** 227 228| Name | Type | Mandatory| Description | 229| -------- | -------------------------------------------- | ---- | ----------------------------------- | 230| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Yes | Callback used to return the album cover.| 231 232**Error codes** 233 234For details about the error codes, see [Media Error Codes](errorcode-media.md). 235 236| ID| Error Message | 237| -------- | ------------------------------------------ | 238| 5400102 | Operation not allowed. Return by callback. | 239| 5400106 | Unsupported format. Returned by callback. | 240 241**Example** 242 243```ts 244import { BusinessError } from '@kit.BasicServicesKit'; 245import { image } from '@kit.ImageKit'; 246import { media } from '@kit.MediaKit'; 247 248async function test() { 249 // Create an AVMetadataExtractor instance. 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 267Obtains the cover of the audio album. This API uses a promise to return the result. 268 269**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 270 271**Return value** 272 273| Type | Description | 274| -------------- | ---------------------------------------- | 275| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise used to return the album cover.| 276 277**Error codes** 278 279For details about the error codes, see [Media Error Codes](errorcode-media.md). 280 281| ID| Error Message | 282| -------- | ----------------------------------------- | 283| 5400102 | Operation not allowed. Returned by promise. | 284| 5400106 | Unsupported format. Returned by promise. | 285 286**Example** 287 288```ts 289import { BusinessError } from '@kit.BasicServicesKit'; 290import { image } from '@kit.ImageKit'; 291import { media } from '@kit.MediaKit'; 292 293async function test() { 294 // Create an AVMetadataExtractor instance. 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 310Releases this AVMetadataExtractor instance. This API uses an asynchronous callback to return the result. 311 312**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 313 314**Parameters** 315 316| Name | Type | Mandatory| Description | 317| -------- | -------------------------------------------- | ---- | ----------------------------------- | 318| callback | AsyncCallback\<void> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 319 320**Error codes** 321 322For details about the error codes, see [Media Error Codes](errorcode-media.md). 323 324| ID| Error Message | 325| -------- | ------------------------------------------ | 326| 5400102 | Operation not allowed. Returned by callback. | 327 328**Example** 329 330```ts 331import { BusinessError } from '@kit.BasicServicesKit'; 332import { media } from '@kit.MediaKit'; 333 334async function test() { 335 // Create an AVMetadataExtractor instance. 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 351Releases this AVMetadataExtractor instance. This API uses a promise to return the result. 352 353**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 354 355**Return value** 356 357| Type | Description | 358| -------------- | ---------------------------------------- | 359| Promise\<void> | Promise that returns no value.| 360 361**Error codes** 362 363For details about the error codes, see [Media Error Codes](errorcode-media.md). 364 365| ID| Error Message | 366| -------- | ----------------------------------------- | 367| 5400102 | Operation not allowed. Returned by promise. | 368 369**Example** 370 371```ts 372import { BusinessError } from '@kit.BasicServicesKit'; 373import { media } from '@kit.MediaKit'; 374 375async function test() { 376 // Create an AVMetadataExtractor instance. 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