1 /* 2 * Copyright (C) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup AVMetadataExtractor 18 * @{ 19 * 20 * @brief Provides APIs of metadata capability for Media Source. 21 * 22 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 23 * @since 18 24 */ 25 26 /** 27 * @file avmetadata_extractor.h 28 * 29 * @brief Defines the avmetadata extractor APIs. Uses the Native APIs provided by Media AVMetadataExtractor 30 * to get metadata from the media source. 31 * 32 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 33 * @kit MediaKit 34 * @library libavmetadata_extractor.so 35 * @since 18 36 */ 37 38 #ifndef MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVMETADATA_EXTRACTOR_H 39 #define MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVMETADATA_EXTRACTOR_H 40 41 #include <stdbool.h> 42 #include <stdint.h> 43 #include <stdio.h> 44 #include "native_averrors.h" 45 #include "avmetadata_extractor_base.h" 46 #include "native_avcodec_base.h" 47 #include "native_avformat.h" 48 #include "multimedia/image_framework/image/pixelmap_native.h" 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /** 55 * @brief Define OH_AVMetadataExtractor field. 56 * 57 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 58 * @since 18 59 */ 60 typedef struct OH_AVMetadataExtractor OH_AVMetadataExtractor; 61 62 /** 63 * @brief Create a metadata extractor. 64 * 65 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 66 * @return Returns a pointer to an OH_AVMetadataExtractor instance for success, nullptr for failure 67 * Possible failure causes: failed to HstEngineFactory::CreateAVMetadataHelperEngine. 68 * @since 18 69 */ 70 OH_AVMetadataExtractor* OH_AVMetadataExtractor_Create(void); 71 72 /** 73 * @brief Sets the media file descriptor source for the metadata extractor. 74 * 75 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 76 * @param extractor Pointer to an OH_AVMetadataExtractor instance. 77 * @param fd Indicates the file descriptor of media source. 78 * @param offset Indicates the offset of media source in file descriptor. 79 * @param size Indicates the size of media source. 80 * @return Function result code. 81 * {@link AV_ERR_OK} if the execution is successful. 82 * {@link AV_ERR_INVALID_VAL} if input extractor is nullptr or input param is invalid. 83 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 84 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 85 * @since 18 86 */ 87 OH_AVErrCode OH_AVMetadataExtractor_SetFDSource(OH_AVMetadataExtractor* extractor, 88 int32_t fd, int64_t offset, int64_t size); 89 90 /** 91 * @brief Extract metadata info from the media source. 92 * This function must be called after {@link SetFDSource}. 93 * 94 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 95 * @param extractor Pointer to an OH_AVMetadataExtractor instance. 96 * @param avMetadata Pointer to an {@link OH_AVFormat} instance, its content contains the fetched metadata info. 97 * @return Function result code. 98 * {@link AV_ERR_OK} if the execution is successful. 99 * {@link AV_ERR_INVALID_VAL} if input extractor is nullptr or input param is invalid. 100 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 101 * {@link AV_ERR_UNSUPPORTED_FORMAT} if format is unsupported. 102 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 103 * @since 18 104 */ 105 OH_AVErrCode OH_AVMetadataExtractor_FetchMetadata(OH_AVMetadataExtractor* extractor, OH_AVFormat* avMetadata); 106 107 /** 108 * @brief Fetch album cover from the audio source. 109 * This function must be called after {@link SetFDSource}. 110 * 111 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 112 * @param extractor Pointer to an OH_AVMetadataExtractor instance. 113 * @param pixelMap The fetched album cover from the audio source. For details, see {@link OH_PixelmapNative}. 114 * @return Function result code. 115 * {@link AV_ERR_OK} if the execution is successful. 116 * {@link AV_ERR_INVALID_VAL} if input extractor is nullptr or input param is invalid. 117 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 118 * {@link AV_ERR_UNSUPPORTED_FORMAT} if format is unsupported. 119 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 120 * @since 18 121 */ 122 OH_AVErrCode OH_AVMetadataExtractor_FetchAlbumCover(OH_AVMetadataExtractor* extractor, OH_PixelmapNative** pixelMap); 123 124 /** 125 * @brief Release the resource used for AVMetadataExtractor. 126 * 127 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 128 * @param extractor Pointer to an OH_AVMetadataExtractor instance. 129 * @return Function result code. 130 * {@link AV_ERR_OK} if the execution is successful. 131 * {@link AV_ERR_INVALID_VAL} if input extractor is nullptr or input param is invalid. 132 * @since 18 133 */ 134 OH_AVErrCode OH_AVMetadataExtractor_Release(OH_AVMetadataExtractor* extractor); 135 136 #ifdef __cplusplus 137 } 138 #endif 139 140 #endif // MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVMETADATA_EXTRACTOR_H 141 /** @} */ 142