1# AVImageGenerator 2 3 4## Overview 5 6The AVImageGenerator module provides the APIs for extracting video frames at given time points from videos. 7 8**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 9 10**Since**: 18 11 12 13## Summary 14 15 16### Files 17 18| Name| Description| 19| -------- | -------- | 20| [avimage_generator.h](avimage__generator_8h.md) | Declares the AVImageGenerator APIs. With these native APIs, you can extract video frames at given time points from videos. | 21| [avimage_generator_base.h](avimage__generator__base_8h.md) | Declares the enums used by the AVImageGenerator. | 22 23 24### Types 25 26| Name| Description| 27| -------- | -------- | 28| typedef struct [OH_AVImageGenerator](#oh_avimagegenerator) [OH_AVImageGenerator](#oh_avimagegenerator) | Defines a struct for the OH_AVImageGenerator. | 29| typedef enum [OH_AVImageGenerator_QueryOptions](#oh_avimagegenerator_queryoptions-1) [OH_AVImageGenerator_QueryOptions](#oh_avimagegenerator_queryoptions) | Defines an enum for the mappings between time points and video frames. | 30 31 32### Enums 33 34| Name| Description| 35| -------- | -------- | 36| [OH_AVImageGenerator_QueryOptions](#oh_avimagegenerator_queryoptions-1) {<br> OH_AVIMAGE_GENERATOR_QUERY_NEXT_SYNC = 0,<br> OH_AVIMAGE_GENERATOR_QUERY_PREVIOUS_SYNC = 1, <br> OH_AVIMAGE_GENERATOR_QUERY_CLOSEST_SYNC = 2, <br> OH_AVIMAGE_GENERATOR_QUERY_CLOSEST = 3 } | Enumerates the mappings between time points and video frames. | 37 38 39### Functions 40 41| Name| Description| 42| -------- | -------- | 43| [OH_AVImageGenerator](#oh_avimagegenerator) \* [OH_AVImageGenerator_Create](#oh_avimagegenerator_create) (void) | Creates an **OH_AVImageGenerator** instance. | 44| [OH_AVErrCode](../apis-avcodec-kit/_core.md#oh_averrcode) [OH_AVImageGenerator_SetFDSource](#oh_avimagegenerator_setfdsource) ([OH_AVImageGenerator](#oh_avimagegenerator) \*generator, int32_t fd, int64_t offset, int64_t size) | Sets a data source based on the media file descriptor. | 45| [OH_AVErrCode](../apis-avcodec-kit/_core.md#oh_averrcode) [OH_AVImageGenerator_FetchFrameByTime](#oh_avimagegenerator_fetchframebytime) ([OH_AVImageGenerator](#oh_avimagegenerator) \*generator, int64_t timeUs, [OH_AVImageGenerator_QueryOptions](#oh_avimagegenerator_queryoptions) options, OH_PixelmapNative \*\*pixelMap) | Extracts a video frame at a given time from a video. | 46| [OH_AVErrCode](../apis-avcodec-kit/_core.md#oh_averrcode) [OH_AVImageGenerator_Release](#oh_avimagegenerator_release) ([OH_AVImageGenerator](#oh_avimagegenerator) \*generator) | Releases the resources used by the **OH_AVImageGenerator** instance and destroys the instance. | 47 48 49## Type Description 50 51 52### OH_AVImageGenerator 53 54``` 55typedef struct OH_AVImageGenerator OH_AVImageGenerator 56``` 57**Description** 58 59Defines a struct for the OH_AVImageGenerator. 60 61**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 62 63**Since**: 18 64 65 66### OH_AVImageGenerator_QueryOptions 67 68``` 69typedef enum OH_AVImageGenerator_QueryOptions OH_AVImageGenerator_QueryOptions 70``` 71**Description** 72 73Defines an enum for the mappings between time points and video frames. 74 75**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 76 77**Since**: 18 78 79 80## Enum Description 81 82 83### OH_AVImageGenerator_QueryOptions 84 85``` 86enum OH_AVImageGenerator_QueryOptions 87``` 88**Description** 89 90Enumerates the mappings between time points and video frames. 91 92**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 93 94**Since**: 18 95 96| Value| Description| 97| -------- | -------- | 98| OH_AVIMAGE_GENERATOR_QUERY_NEXT_SYNC | Extracts the key frame at or next to the specified time. | 99| OH_AVIMAGE_GENERATOR_QUERY_PREVIOUS_SYNC | Extracts the key frame at or prior to the specified time. | 100| OH_AVIMAGE_GENERATOR_QUERY_CLOSEST_SYNC | Extracts the key frame closest to the specified time. | 101| OH_AVIMAGE_GENERATOR_QUERY_CLOSEST | Extracts the frame (not necessarily a key frame) closest to the specified time. | 102 103 104## Function Description 105 106 107### OH_AVImageGenerator_Create() 108 109``` 110OH_AVImageGenerator* OH_AVImageGenerator_Create(void) 111``` 112**Description** 113 114Creates an **OH_AVImageGenerator** instance. 115 116**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 117 118**Since**: 18 119 120**Returns** 121 122Returns the pointer to the **OH_AVImageGenerator** instance created if the operation is successful; returns a null pointer otherwise. 123 124Possible cause of failures: HstEngineFactory fails to create an AVMetadataHelperEngine. 125 126 127### OH_AVImageGenerator_FetchFrameByTime() 128 129``` 130OH_AVErrCode OH_AVImageGenerator_FetchFrameByTime(OH_AVImageGenerator* generator, int64_t timeUs, OH_AVImageGenerator_QueryOptions options, OH_PixelmapNative** pixelMap) 131``` 132**Description** 133 134Extracts a video frame at a given time from a video. 135 136This function must be called after [SetFDSource](#oh_avimagegenerator_setfdsource). 137 138**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 139 140**Parameters** 141 142| Name| Description| 143| -------- | -------- | 144| generator | Pointer to an **OH_AVImageGenerator** instance. | 145| timeUs | Time point of the video frame to be extracted in the video, in μs. | 146| options | Mappings between the given time points and video frames. For details, see [OH_AVImageGenerator_QueryOptions](#oh_avimagegenerator_queryoptions-1). | 147| pixelMap | Double pointer to the video frame object obtained. For details, see {@link OH_PixelmapNative}. | 148 149**Returns** 150 151Returns a result code defined in [OH_AVErrCode](../apis-avcodec-kit/_core.md#oh_averrcode-1). The following result codes are possible: 152 153**AV_ERR_OK**: The operation is successful. 154 155**AV_ERR_INVALID_VAL**: The input parameter **generator** is a null pointer or an input parameter is invalid. 156 157**AV_ERR_OPERATE_NOT_PERMIT**: The operation is not allowed. 158 159**AV_ERR_UNSUPPORTED_FORMAT**: The format is not supported. 160 161**AV_ERR_NO_MEMORY**: Internal memory allocation failed. 162 163### OH_AVImageGenerator_Release() 164 165``` 166OH_AVErrCode OH_AVImageGenerator_Release(OH_AVImageGenerator* generator) 167``` 168**Description** 169 170Releases the resources used by the **OH_AVImageGenerator** instance and destroys the instance. 171 172**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 173 174**Since**: 18 175 176**Parameters** 177 178| Name| Description| 179| -------- | -------- | 180| generator | Pointer to an **OH_AVImageGenerator** instance. | 181 182**Returns** 183 184Returns a result code defined in [OH_AVErrCode](../apis-avcodec-kit/_core.md#oh_averrcode-1). The following result codes are possible: 185 186**AV_ERR_OK**: The operation is successful. 187 188**AV_ERR_INVALID_VAL**: The input parameter **generator** is a null pointer or an input parameter is invalid. 189 190 191### OH_AVImageGenerator_SetFDSource() 192 193``` 194OH_AVErrCode OH_AVImageGenerator_SetFDSource(OH_AVImageGenerator* generator, int32_t fd, int64_t offset, int64_t size) 195``` 196**Description** 197 198Sets a data source based on the media file descriptor. 199 200**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 201 202**Since**: 18 203 204**Parameters** 205 206| Name| Description| 207| -------- | -------- | 208| generator | Pointer to an **OH_AVImageGenerator** instance. | 209| fd | File descriptor of the media source. | 210| offset | Offset of the media source in the file descriptor. | 211| size | Size of the media source. | 212 213**Returns** 214 215Returns a result code defined in [OH_AVErrCode](../apis-avcodec-kit/_core.md#oh_averrcode-1). The following result codes are possible: 216 217**AV_ERR_OK**: The operation is successful. 218 219**AV_ERR_INVALID_VAL**: The input parameter **generator** is a null pointer or an input parameter is invalid. 220 221**AV_ERR_OPERATE_NOT_PERMIT**: The operation is not allowed. 222 223**AV_ERR_NO_MEMORY**: Internal memory allocation failed. 224