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 <memory> 20 #include <map> 21 #include <string> 22 #include <unordered_map> 23 #include "buffer/avsharedmemory.h" 24 #include "meta/format.h" 25 #include "media_data_source.h" 26 #include "nocopyable.h" 27 #include "pixel_map.h" 28 29 namespace OHOS { 30 namespace Media { 31 /** 32 * @brief Enumerates avmetadata helper callback error type. 33 */ 34 enum HelperErrorType : int32_t { 35 /* State error, current operation is invalid. */ 36 INVALID_OPERATION, 37 /* Result error, current result is invalid. */ 38 INVALID_RESULT, 39 }; 40 41 /** 42 * @brief Enumerates avmetadata helper listener info type. 43 */ 44 enum HelperOnInfoType : int32_t { 45 /* Current State changed, notify NAPI with onInfo callback. */ 46 HELPER_INFO_TYPE_STATE_CHANGE, 47 }; 48 49 /** 50 * @brief Enumerates avmetadata helper states. 51 */ 52 enum HelperStates : int32_t { 53 /* error states */ 54 HELPER_STATE_ERROR = 0, 55 /* idle states */ 56 HELPER_IDLE = 1, 57 /* prepared states */ 58 HELPER_PREPARED = 2, 59 /* call done states */ 60 HELPER_CALL_DONE = 3, 61 /* released states */ 62 HELPER_RELEASED = 4, 63 }; 64 65 /** 66 * The meta data mappings from meta data enum keys to the string key. 67 */ 68 static const std::map<int32_t, const char*> g_MetadataCodeMap = { 69 {0, "album"}, 70 {1, "albumArtist"}, 71 {2, "artist"}, 72 {3, "author"}, 73 {4, "dateTime"}, 74 {5, "dateTimeFormat"}, 75 {12, "composer"}, 76 {15, "duration"}, 77 {18, "genre"}, 78 {19, "hasAudio"}, 79 {21, "hasVideo"}, 80 {29, "mimeType"}, 81 {30, "trackCount"}, 82 {31, "sampleRate"}, 83 {33, "title"}, 84 {35, "videoHeight"}, 85 {37, "videoWidth"}, 86 {38, "videoOrientation"}, 87 }; 88 89 /** 90 * @brief Enumerates avmetadata usage. 91 */ 92 enum AVMetadataUsage : int32_t { 93 /** 94 * Indicates that the avmetadahelper's instance will only be used for resolving the 95 * metadata from the given media resource. 96 */ 97 AV_META_USAGE_META_ONLY, 98 /** 99 * Indicates that the avmetadahelper's instance will be used for fetching the video frame 100 * and resolving metadata from the given media resource. 101 */ 102 AV_META_USAGE_PIXEL_MAP, 103 }; 104 105 /** 106 * @brief Enumerates avmetadata's metadata key. 107 */ 108 enum AVMetadataCode : int32_t { 109 /** 110 * The metadata key to retrieve the information about the album title 111 * of the media source. 112 */ 113 AV_KEY_ALBUM = 0, 114 /** 115 * The metadata key to retrieve the information about the performers or 116 * artist associated with the media source. 117 */ 118 AV_KEY_ALBUM_ARTIST = 1, 119 /** 120 * The metadata key to retrieve the information about the artist of 121 * the media source. 122 */ 123 AV_KEY_ARTIST = 2, 124 /** 125 * The metadata key to retrieve the information about the author of 126 * the media source. 127 */ 128 AV_KEY_AUTHOR = 3, 129 /** 130 * The metadata key to retrieve the information about the created time of 131 * the media source. 132 */ 133 AV_KEY_DATE_TIME = 4, 134 /** 135 * The metadata key to retrieve the information about the created time of 136 * the media source. This keyword is provided for the media library. 137 */ 138 AV_KEY_DATE_TIME_FORMAT = 5, 139 /** 140 * The metadata key to retrieve the information about the composer of 141 * the media source. 142 */ 143 AV_KEY_COMPOSER = 12, 144 /** 145 * The metadata key to retrieve the playback duration of the media source. 146 */ 147 AV_KEY_DURATION = 15, 148 /** 149 * The metadata key to retrieve the content type or genre of the data 150 * source. 151 */ 152 AV_KEY_GENRE = 18, 153 /** 154 * If this key exists the media contains audio content. 155 */ 156 AV_KEY_HAS_AUDIO = 19, 157 /** 158 * If this key exists the media contains video content. 159 */ 160 AV_KEY_HAS_VIDEO = 21, 161 /** 162 * The metadata key to retrieve the mime type of the media source. Some 163 * example mime types include: "video/mp4", "audio/mp4", "audio/amr-wb", 164 * etc. 165 */ 166 AV_KEY_MIME_TYPE = 29, 167 /** 168 * The metadata key to retrieve the number of tracks, such as audio, video, 169 * text, in the media source, such as a mp4 or 3gpp file. 170 */ 171 AV_KEY_NUM_TRACKS = 30, 172 /** 173 * This key retrieves the sample rate, if available. 174 */ 175 AV_KEY_SAMPLE_RATE = 31, 176 /** 177 * The metadata key to retrieve the media source title. 178 */ 179 AV_KEY_TITLE = 33, 180 /** 181 * If the media contains video, this key retrieves its height. 182 */ 183 AV_KEY_VIDEO_HEIGHT = 35, 184 /** 185 * If the media contains video, this key retrieves its width. 186 */ 187 AV_KEY_VIDEO_WIDTH = 37, 188 /** 189 * The metadata key to retrieve the information about the video 190 * orientation. 191 */ 192 AV_KEY_VIDEO_ORIENTATION = 38, 193 }; 194 195 /** 196 * @brief Enumerates avmetadata's query option. 197 */ 198 enum AVMetadataQueryOption : int32_t { 199 /** 200 * This option is used to fetch a key frame from the given media 201 * resource that is located right after or at the given time. 202 */ 203 AV_META_QUERY_NEXT_SYNC, 204 /** 205 * This option is used to fetch a key frame from the given media 206 * resource that is located right before or at the given time. 207 */ 208 AV_META_QUERY_PREVIOUS_SYNC, 209 /** 210 * This option is used to fetch a key frame from the given media 211 * resource that is located closest to or at the given time. 212 */ 213 AV_META_QUERY_CLOSEST_SYNC, 214 /** 215 * This option is used to fetch a frame (maybe not keyframe) from 216 * the given media resource that is located closest to or at the given time. 217 */ 218 AV_META_QUERY_CLOSEST, 219 }; 220 221 /** 222 * @brief Provides the definition of the returned pixelmap's configuration 223 */ 224 struct PixelMapParams { 225 /** 226 * Expected pixelmap's width, -1 means to keep consistent with the 227 * original dimensions of the given video resource. 228 */ 229 int32_t dstWidth = -1; 230 /** 231 * Expected pixelmap's width, -1 means to keep consistent with the 232 * original dimensions of the given video resource. 233 */ 234 int32_t dstHeight = -1; 235 /** 236 * Expected pixelmap's color format, see {@link PixelFormat}. Currently, 237 * RGB_565, RGB_888, RGBA_8888 are supported. 238 */ 239 PixelFormat colorFormat = PixelFormat::RGB_565; 240 }; 241 242 /** 243 * @brief Provides the callback interfaces to notify client about errors or infos. 244 */ 245 class HelperCallback { 246 public: 247 virtual ~HelperCallback() = default; 248 /** 249 * Called when a metadata helper message is notified. 250 * 251 * @param type Indicates the information type. For details, see {@link HelperOnInfoType}. 252 * @param extra Indicates other information, for example, the current state in metadata helper server. 253 * @param infoBody According to the info type, the information carrier passed. Is an optional parameter. 254 */ 255 virtual void OnInfo(HelperOnInfoType type, int32_t extra, const Format &infoBody = {}) = 0; 256 257 /** 258 * Called when an error occurred 259 * 260 * @param errorCode Error code. 261 * @param errorMsg Error message. 262 */ 263 virtual void OnError(int32_t errorCode, const std::string &errorMsg) = 0; 264 }; 265 266 /** 267 * @brief Provides the interfaces to resolve metadata or fetch frame 268 * from a given media resource. 269 */ 270 class AVMetadataHelper { 271 public: 272 virtual ~AVMetadataHelper() = default; 273 274 /** 275 * Set the media source uri to resolve. Calling this method before the reset 276 * of the methods in this class. This method maybe time consuming. 277 * @param uri the URI of input media source. 278 * @param usage indicates which scene the avmedatahelper's instance will 279 * be used to, see {@link AVMetadataUsage}. If the usage need to be changed, 280 * this method must be called again. 281 * @return Returns {@link MSERR_OK} if the setting is successful; returns 282 * an error code otherwise. 283 */ 284 virtual int32_t SetSource(const std::string &uri, int32_t usage = AVMetadataUsage::AV_META_USAGE_PIXEL_MAP) = 0; 285 286 /** 287 * @brief Sets the media file descriptor source to resolve. Calling this method 288 * before the reset of the methods in this class. This method maybe time consuming. 289 * @param fd Indicates the file descriptor of media source. 290 * @param offset Indicates the offset of media source in file descriptor. 291 * @param size Indicates the size of media source. 292 * @param usage Indicates which scene the avmedatahelper's instance will 293 * be used to, see {@link AVMetadataUsage}. If the usage need to be changed, 294 * this method must be called again. 295 * @return Returns {@link MSERR_OK} if the setting is successful; returns 296 * an error code otherwise. 297 */ 298 virtual int32_t SetSource(int32_t fd, int64_t offset = 0, int64_t size = 0, 299 int32_t usage = AVMetadataUsage::AV_META_USAGE_PIXEL_MAP) = 0; 300 301 /** 302 * @brief Sets the playback media data source for the meta data helper. 303 * 304 * @param dataSrc Indicates the media data source. in {@link media_data_source.h} 305 * @return Returns {@link MSERR_OK} if the mediadatasource is set successfully; returns an error code defined 306 * in {@link media_errors.h} otherwise. 307 */ 308 virtual int32_t SetSource(const std::shared_ptr<IMediaDataSource> &dataSrc) = 0; 309 310 /** 311 * Retrieve the meta data associated with the specified key. This method must be 312 * called after the SetSource. 313 * @param key One of the constants listed above at the definition of {@link AVMetadataCode}. 314 * @return Returns the meta data value associate with the given key code on 315 * success; empty string on failure. 316 */ 317 virtual std::string ResolveMetadata(int32_t key) = 0; 318 319 /** 320 * Retrieve all meta data within the listed above at the definition of {@link AVMetadataCode}. 321 * This method must be called after the SetSource. 322 * @return Returns the meta data values on success; empty hash map on failure. 323 */ 324 virtual std::unordered_map<int32_t, std::string> ResolveMetadata() = 0; 325 326 /** 327 * Fetch the album art picture associated with the data source. If there are 328 * more than one pictures, the cover image will be returned preferably. 329 * @return Returns the a chunk of shared memory containing a picture, which can be 330 * null, if such a picture can not be fetched. 331 */ 332 virtual std::shared_ptr<AVSharedMemory> FetchArtPicture() = 0; 333 334 /** 335 * Fetch a representative video frame near a given timestamp by considering the given 336 * option if possible, and return a pixelmap with given parameters. This method must be 337 * called after the SetSource. 338 * @param timeUs The time position in microseconds where the frame will be fetched. 339 * When fetching the frame at the given time position, there is no guarantee that 340 * the video source has a frame located at the position. When this happens, a frame 341 * nearby will be returned. If timeUs is negative, time position and option will ignored, 342 * and any frame that the implementation considers as representative may be returned. 343 * @param option the hint about how to fetch a frame, see {@link AVMetadataQueryOption} 344 * @param param the desired configuration of returned pixelmap, see {@link PixelMapParams}. 345 * @return Returns a pixelmap containing a scaled video frame, which can be null, if such a 346 * frame cannot be fetched. 347 */ 348 virtual std::shared_ptr<PixelMap> FetchFrameAtTime(int64_t timeUs, int32_t option, const PixelMapParams ¶m) = 0; 349 350 /** 351 * Release the internel resource. After this method called, the avmetadatahelper instance 352 * can not be used again. 353 */ 354 virtual void Release() = 0; 355 356 /** 357 * @brief Method to set the meta data helper callback. 358 * 359 * @param callback object pointer. 360 * @return Returns {@link MSERR_OK} if the meta data helper callback is set; returns an error code defined 361 * in {@link media_errors.h} otherwise. 362 */ 363 virtual int32_t SetHelperCallback(const std::shared_ptr<HelperCallback> &callback) = 0; 364 }; 365 366 class __attribute__((visibility("default"))) AVMetadataHelperFactory { 367 public: 368 #ifdef UNSUPPORT_METADATA CreateAVMetadataHelper()369 static std::shared_ptr<AVMetadataHelper> CreateAVMetadataHelper() 370 { 371 return nullptr; 372 } 373 #else 374 static std::shared_ptr<AVMetadataHelper> CreateAVMetadataHelper(); 375 #endif 376 private: 377 AVMetadataHelperFactory() = default; 378 ~AVMetadataHelperFactory() = default; 379 }; 380 } // namespace Media 381 } // namespace OHOS 382 #endif // AVMETADATAHELPER_H