1# avimage_generator.h 2<!--Kit: Media Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @wang-haizhou6--> 5<!--Designer: @HmQQQ--> 6<!--Tester: @xchaosioda--> 7<!--Adviser: @zengyawen--> 8 9## Overview 10 11The file declares the AVImageGenerator APIs. You can use the APIs to extract video frames at given time points from videos. 12 13**File to include**: <multimedia/player_framework/avimage_generator.h> 14 15**Library**: libavimage_generator.so 16 17**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 18 19**Since**: 18 20 21**Related module**: [AVImageGenerator](capi-avimagegenerator.md) 22 23## Summary 24 25### Structs 26 27| Name| typedef Keyword| Description| 28| -- | -- | -- | 29| [OH_AVImageGenerator](capi-avimagegenerator-oh-avimagegenerator.md) | OH_AVImageGenerator | Defines the type used for generating video frames at given time points.| 30 31### Functions 32 33| Name| Description| 34| -- | -- | 35| [OH_AVImageGenerator* OH_AVImageGenerator_Create(void)](#oh_avimagegenerator_create) | Creates an OH_AVImageGenerator instance, which is used to generate video frames at given time points.| 36| [OH_AVErrCode OH_AVImageGenerator_SetFDSource(OH_AVImageGenerator* generator, int32_t fd, int64_t offset, int64_t size)](#oh_avimagegenerator_setfdsource) | Sets a data source based on the media file descriptor.| 37| [OH_AVErrCode OH_AVImageGenerator_FetchFrameByTime(OH_AVImageGenerator* generator, int64_t timeUs, OH_AVImageGenerator_QueryOptions options, OH_PixelmapNative** pixelMap)](#oh_avimagegenerator_fetchframebytime) | Extracts a video frame at a given time from a video.<br>This function must be called after [OH_AVImageGenerator_SetFDSource](#oh_avimagegenerator_setfdsource).| 38| [OH_AVErrCode OH_AVImageGenerator_Release(OH_AVImageGenerator* generator)](#oh_avimagegenerator_release) | Releases the resources used by the OH_AVImageGenerator instance and destroys the instance.| 39 40## Function Description 41 42### OH_AVImageGenerator_Create() 43 44``` 45OH_AVImageGenerator* OH_AVImageGenerator_Create(void) 46``` 47 48**Description** 49 50Creates an OH_AVImageGenerator instance, which is used to generate video frames at given time points. 51 52**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 53 54**Since**: 18 55 56**Return value** 57 58| Type| Description| 59| -- | -- | 60| [OH_AVImageGenerator](capi-avimagegenerator-oh-avimagegenerator.md)* | Pointer to the OH_AVImageGenerator instance created if the operation is successful; nullptr otherwise.<br> Possible cause of failures: HstEngineFactory fails to create an AVMetadataHelperEngine.| 61 62### OH_AVImageGenerator_SetFDSource() 63 64``` 65OH_AVErrCode OH_AVImageGenerator_SetFDSource(OH_AVImageGenerator* generator,int32_t fd, int64_t offset, int64_t size) 66``` 67 68**Description** 69 70Sets a data source based on the media file descriptor. 71 72**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 73 74**Since**: 18 75 76 77**Parameters** 78 79| Parameter| Description| 80| -- | -- | 81| [OH_AVImageGenerator](capi-avimagegenerator-oh-avimagegenerator.md)* generator | Pointer to the OH_AVImageGenerator instance.| 82| int32_t fd | File descriptor of the media source.| 83| int64_t offset | Offset of the media source in the file descriptor.| 84| int64_t size | Size of the media source.| 85 86**Return value** 87 88| Type| Description| 89| -- | -- | 90| [OH_AVErrCode](../apis-avcodec-kit/_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The input parameter **generator** is nullptr or a parameter is invalid.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation is forbidden.<br>**AV_ERR_NO_MEMORY**: Internal memory allocation failed.| 91 92### OH_AVImageGenerator_FetchFrameByTime() 93 94``` 95OH_AVErrCode OH_AVImageGenerator_FetchFrameByTime(OH_AVImageGenerator* generator,int64_t timeUs, OH_AVImageGenerator_QueryOptions options, OH_PixelmapNative** pixelMap) 96``` 97 98**Description** 99 100Extracts a video frame at a given time from a video. 101 102This function must be called after [OH_AVImageGenerator_SetFDSource](#oh_avimagegenerator_setfdsource). 103 104**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 105 106**Since**: 18 107 108 109**Parameters** 110 111| Parameter| Description| 112| -- | -- | 113| [OH_AVImageGenerator](capi-avimagegenerator-oh-avimagegenerator.md)* generator | Pointer to the OH_AVImageGenerator instance.| 114| int64_t timeUs | Time point of the video frame to be extracted in the video, in μs.| 115| [OH_AVImageGenerator_QueryOptions](capi-avimage-generator-base-h.md#oh_avimagegenerator_queryoptions) options | Mappings between the given time points and video frames.| 116| [OH_PixelmapNative](../apis-image-kit/capi-image-nativemodule-oh-pixelmapnative.md)** pixelMap | Double pointer to the video frame object obtained.| 117 118**Return value** 119 120| Type| Description| 121| -- | -- | 122| [OH_AVErrCode](../apis-avcodec-kit/_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The input parameter **generator** is nullptr or a parameter is invalid.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation is forbidden.<br>**AV_ERR_UNSUPPORTED_FORMAT**: The format is not supported.<br>**AV_ERR_NO_MEMORY**: Internal memory allocation failed.| 123 124### OH_AVImageGenerator_Release() 125 126``` 127OH_AVErrCode OH_AVImageGenerator_Release(OH_AVImageGenerator* generator) 128``` 129 130**Description** 131 132Releases the resources used by the OH_AVImageGenerator instance and destroys the instance. 133 134**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 135 136**Since**: 18 137 138 139**Parameters** 140 141| Parameter| Description| 142| -- | -- | 143| [OH_AVImageGenerator](capi-avimagegenerator-oh-avimagegenerator.md)* generator | Pointer to the OH_AVImageGenerator instance.| 144 145**Return value** 146 147| Type| Description| 148| -- | -- | 149| [OH_AVErrCode](../apis-avcodec-kit/_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The input parameter **generator** is nullptr or a parameter is invalid.| 150