1 /* 2 * Copyright (C) 2021 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 #ifndef AVMETADATAHELPER_H 17 #define AVMETADATAHELPER_H 18 19 #include <string> 20 #include <unordered_map> 21 #include <memory> 22 #include "pixel_map.h" 23 #include "nocopyable.h" 24 #include "avsharedmemory.h" 25 26 namespace OHOS { 27 namespace Media { 28 /** 29 * @brief Enumerates avmetadata usage. 30 */ 31 enum AVMetadataUsage : int32_t { 32 /** 33 * Indicates that the avmetadahelper's instance will only be used for resolving the 34 * metadata from the given media resource. 35 */ 36 AV_META_USAGE_META_ONLY, 37 /** 38 * Indicates that the avmetadahelper's instance will be used for fetching the video frame 39 * and resolving metadata from the given media resource. 40 */ 41 AV_META_USAGE_PIXEL_MAP, 42 }; 43 44 /** 45 * @brief Enumerates avmetadata's metadata key. 46 */ 47 enum AVMetadataCode : int32_t { 48 /** 49 * The metadata key to retrieve the information about the album title 50 * of the media source. 51 */ 52 AV_KEY_ALBUM = 0, 53 /** 54 * The metadata key to retrieve the information about the performers or 55 * artist associated with the media source. 56 */ 57 AV_KEY_ALBUM_ARTIST = 1, 58 /** 59 * The metadata key to retrieve the information about the artist of 60 * the media source. 61 */ 62 AV_KEY_ARTIST = 2, 63 /** 64 * The metadata key to retrieve the information about the author of 65 * the media source. 66 */ 67 AV_KEY_AUTHOR = 3, 68 /** 69 * The metadata key to retrieve the information about the composer of 70 * the media source. 71 */ 72 AV_KEY_COMPOSER = 12, 73 /** 74 * The metadata key to retrieve the playback duration of the media source. 75 */ 76 AV_KEY_DURATION = 15, 77 /** 78 * The metadata key to retrieve the content type or genre of the data 79 * source. 80 */ 81 AV_KEY_GENRE = 18, 82 /** 83 * If this key exists the media contains audio content. 84 */ 85 AV_KEY_HAS_AUDIO = 19, 86 /** 87 * If this key exists the media contains video content. 88 */ 89 AV_KEY_HAS_VIDEO = 21, 90 /** 91 * The metadata key to retrieve the mime type of the media source. Some 92 * example mime types include: "video/mp4", "audio/mp4", "audio/amr-wb", 93 * etc. 94 */ 95 AV_KEY_MIME_TYPE = 29, 96 /** 97 * The metadata key to retrieve the number of tracks, such as audio, video, 98 * text, in the media source, such as a mp4 or 3gpp file. 99 */ 100 AV_KEY_NUM_TRACKS = 30, 101 /** 102 * This key retrieves the sample rate, if available. 103 */ 104 AV_KEY_SAMPLE_RATE = 31, 105 /** 106 * The metadata key to retrieve the media source title. 107 */ 108 AV_KEY_TITLE = 33, 109 /** 110 * If the media contains video, this key retrieves its height. 111 */ 112 AV_KEY_VIDEO_HEIGHT = 35, 113 /** 114 * If the media contains video, this key retrieves its width. 115 */ 116 AV_KEY_VIDEO_WIDTH = 37, 117 }; 118 119 /** 120 * @brief Enumerates avmetadata's query option. 121 */ 122 enum AVMetadataQueryOption : int32_t { 123 /** 124 * This option is used to fetch a key frame from the given media 125 * resource that is located right after or at the given time. 126 */ 127 AV_META_QUERY_NEXT_SYNC, 128 /** 129 * This option is used to fetch a key frame from the given media 130 * resource that is located right before or at the given time. 131 */ 132 AV_META_QUERY_PREVIOUS_SYNC, 133 /** 134 * This option is used to fetch a key frame from the given media 135 * resource that is located closest to or at the given time. 136 */ 137 AV_META_QUERY_CLOSEST_SYNC, 138 /** 139 * This option is used to fetch a frame (maybe not keyframe) from 140 * the given media resource that is located closest to or at the given time. 141 */ 142 AV_META_QUERY_CLOSEST, 143 }; 144 145 /** 146 * @brief Provides the definition of the returned pixelmap's configuration 147 */ 148 struct PixelMapParams { 149 /** 150 * Expected pixelmap's width, -1 means to keep consistent with the 151 * original dimensions of the given video resource. 152 */ 153 int32_t dstWidth = -1; 154 /** 155 * Expected pixelmap's width, -1 means to keep consistent with the 156 * original dimensions of the given video resource. 157 */ 158 int32_t dstHeight = -1; 159 /** 160 * Expected pixelmap's color format, see {@link PixelFormat}. Currently, 161 * RGB_565, RGB_888, RGBA_8888 are supported. 162 */ 163 PixelFormat colorFormat = PixelFormat::RGB_565; 164 }; 165 166 /** 167 * @brief Provides the interfaces to resolve metadata or fetch frame 168 * from a given media resource. 169 */ 170 class AVMetadataHelper { 171 public: 172 virtual ~AVMetadataHelper() = default; 173 174 /** 175 * Set the media source uri to resolve. Calling this method before the reset 176 * of the methods in this class. This method maybe time consuming. 177 * @param uri the URI of input media source. 178 * @param usage indicates which scene the avmedatahelper's instance will 179 * be used to, see {@link AVMetadataUsage}. If the usage need to be changed, 180 * this method must be called again. 181 * @return Returns {@link MSERR_OK} if the setting is successful; returns 182 * an error code otherwise. 183 */ 184 virtual int32_t SetSource(const std::string &uri, int32_t usage = AVMetadataUsage::AV_META_USAGE_PIXEL_MAP) = 0; 185 186 /** 187 * @brief Sets the media file descriptor source to resolve. Calling this method 188 * before the reset of the methods in this class. This method maybe time consuming. 189 * @param fd Indicates the file descriptor of media source. 190 * @param offset Indicates the offset of media source in file descriptor. 191 * @param size Indicates the size of media source. 192 * @param usage Indicates which scene the avmedatahelper's instance will 193 * be used to, see {@link AVMetadataUsage}. If the usage need to be changed, 194 * this method must be called again. 195 * @return Returns {@link MSERR_OK} if the setting is successful; returns 196 * an error code otherwise. 197 */ 198 virtual int32_t SetSource(int32_t fd, int64_t offset = 0, int64_t size = 0, 199 int32_t usage = AVMetadataUsage::AV_META_USAGE_PIXEL_MAP) = 0; 200 201 /** 202 * Retrieve the meta data associated with the specified key. This method must be 203 * called after the SetSource. 204 * @param key One of the constants listed above at the definition of {@link AVMetadataCode}. 205 * @return Returns the meta data value associate with the given key code on 206 * success; empty string on failure. 207 */ 208 virtual std::string ResolveMetadata(int32_t key) = 0; 209 210 /** 211 * Retrieve all meta data within the listed above at the definition of {@link AVMetadataCode}. 212 * This method must be called after the SetSource. 213 * @return Returns the meta data values on success; empty hash map on failure. 214 */ 215 virtual std::unordered_map<int32_t, std::string> ResolveMetadata() = 0; 216 217 /** 218 * Fetch the album art picture associated with the data source. If there are 219 * more than one pictures, the cover image will be returned preferably. 220 * @return Returns the a chunk of shared memory containing a picture, which can be 221 * null, if such a picture can not be fetched. 222 */ 223 virtual std::shared_ptr<AVSharedMemory> FetchArtPicture() = 0; 224 225 /** 226 * Fetch a representative video frame near a given timestamp by considering the given 227 * option if possible, and return a pixelmap with given parameters. This method must be 228 * called after the SetSource. 229 * @param timeUs The time position in microseconds where the frame will be fetched. 230 * When fetching the frame at the given time position, there is no guarantee that 231 * the video source has a frame located at the position. When this happens, a frame 232 * nearby will be returned. If timeUs is negative, time position and option will ignored, 233 * and any frame that the implementation considers as representative may be returned. 234 * @param option the hint about how to fetch a frame, see {@link AVMetadataQueryOption} 235 * @param param the desired configuration of returned pixelmap, see {@link PixelMapParams}. 236 * @return Returns a pixelmap containing a scaled video frame, which can be null, if such a 237 * frame cannot be fetched. 238 */ 239 virtual std::shared_ptr<PixelMap> FetchFrameAtTime(int64_t timeUs, int32_t option, const PixelMapParams ¶m) = 0; 240 241 /** 242 * Release the internel resource. After this method called, the avmetadatahelper instance 243 * can not be used again. 244 */ 245 virtual void Release() = 0; 246 }; 247 248 class __attribute__((visibility("default"))) AVMetadataHelperFactory { 249 public: 250 static std::shared_ptr<AVMetadataHelper> CreateAVMetadataHelper(); 251 252 private: 253 AVMetadataHelperFactory() = default; 254 ~AVMetadataHelperFactory() = default; 255 }; 256 } // namespace Media 257 } // namespace OHOS 258 #endif // AVMETADATAHELPER_H