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