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 16 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 * @kit MediaKit 33 * @library libavmetadata_extractor.so 34 * @since 16 35 */ 36 37 #ifndef MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVMETADATA_EXTRACTOR_H 38 #define MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVMETADATA_EXTRACTOR_H 39 40 #include <stdbool.h> 41 #include <stdint.h> 42 #include <stdio.h> 43 #include "native_averrors.h" 44 #include "avmetadata_extractor_base.h" 45 #include "native_avcodec_base.h" 46 #include "native_avformat.h" 47 #include "pixelmap_native.h" 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 /** 54 * @brief Define OH_AVMetadataExtractor field. 55 * 56 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 57 * @since 16 58 */ 59 typedef struct OH_AVMetadataExtractor OH_AVMetadataExtractor; 60 61 /** 62 * @brief Create a metadata extractor. 63 * 64 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 65 * @return Returns a pointer to an OH_AVMetadataExtractor instance for success, nullptr for failure 66 * Possible failure causes: failed to HstEngineFactory::CreateAVMetadataHelperEngine. 67 * @since 16 68 */ 69 OH_AVMetadataExtractor* OH_AVMetadataExtractor_Create(void); 70 71 /** 72 * @brief Sets the media file descriptor source for the metadata extractor. 73 * 74 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 75 * @param extractor Pointer to an OH_AVMetadataExtractor instance. 76 * @param fd Indicates the file descriptor of media source. 77 * @param offset Indicates the offset of media source in file descriptor. 78 * @param size Indicates the size of media source. 79 * @return Function result code. 80 * {@link AV_ERR_OK} if the execution is successful. 81 * {@link AV_ERR_INVALID_VAL} if input extractor is nullptr or input param is invalid. 82 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 83 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 84 * @since 16 85 */ 86 OH_AVErrCode OH_AVMetadataExtractor_SetFDSource(OH_AVMetadataExtractor* extractor, 87 int32_t fd, int64_t offset, int64_t size); 88 89 /** 90 * @brief Extract metadata info from the media source. 91 * This function must be called after {@link SetFDSource}. 92 * 93 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 94 * @param extractor Pointer to an OH_AVMetadataExtractor instance. 95 * @param avMetadata Pointer to an {@link OH_AVFormat} instance, its content contains the fetched metadata info. 96 * @return Function result code. 97 * {@link AV_ERR_OK} if the execution is successful. 98 * {@link AV_ERR_INVALID_VAL} if input extractor is nullptr or input param is invalid. 99 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 100 * {@link AV_ERR_UNSUPPORTED_FORMAT} if format is unsupported. 101 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 102 * @since 16 103 */ 104 OH_AVErrCode OH_AVMetadataExtractor_FetchMetadata(OH_AVMetadataExtractor* extractor, OH_AVFormat* avMetadata); 105 106 /** 107 * @brief Fetch album cover from the audio source. 108 * This function must be called after {@link SetFDSource}. 109 * 110 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 111 * @param extractor Pointer to an OH_AVMetadataExtractor instance. 112 * @param pixelMap The fetched album cover from the audio source. For details, see {@link OH_PixelmapNative}. 113 * @return Function result code. 114 * {@link AV_ERR_OK} if the execution is successful. 115 * {@link AV_ERR_INVALID_VAL} if input extractor is nullptr or input param is invalid. 116 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 117 * {@link AV_ERR_UNSUPPORTED_FORMAT} if format is unsupported. 118 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 119 * @since 16 120 */ 121 OH_AVErrCode OH_AVMetadataExtractor_FetchAlbumCover(OH_AVMetadataExtractor* extractor, OH_PixelmapNative** pixelMap); 122 123 /** 124 * @brief Release the resource used for AVMetadataExtractor. 125 * 126 * @syscap SystemCapability.Multimedia.Media.AVMetadataExtractor 127 * @param extractor Pointer to an OH_AVMetadataExtractor instance. 128 * @return Function result code. 129 * {@link AV_ERR_OK} if the execution is successful. 130 * {@link AV_ERR_INVALID_VAL} if input extractor is nullptr or input param is invalid. 131 * @since 16 132 */ 133 OH_AVErrCode OH_AVMetadataExtractor_Release(OH_AVMetadataExtractor* extractor); 134 135 #ifdef __cplusplus 136 } 137 #endif 138 139 #endif // MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVMETADATA_EXTRACTOR_H