webrtc_video_stats_db.h 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178
  1. // Copyright 2022 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef MEDIA_CAPABILITIES_WEBRTC_VIDEO_STATS_DB_H_
  5. #define MEDIA_CAPABILITIES_WEBRTC_VIDEO_STATS_DB_H_
  6. #include <memory>
  7. #include <string>
  8. #include <vector>
  9. #include "base/callback_forward.h"
  10. #include "base/check.h"
  11. #include "base/containers/flat_map.h"
  12. #include "base/time/time.h"
  13. #include "media/base/media_export.h"
  14. #include "media/base/video_codecs.h"
  15. #include "third_party/abseil-cpp/absl/types/optional.h"
  16. #include "ui/gfx/geometry/size.h"
  17. namespace media {
  18. // This defines the interface to be used by various media capabilities services
  19. // to store/retrieve video encoding and decoding performance statistics.
  20. class MEDIA_EXPORT WebrtcVideoStatsDB {
  21. public:
  22. // Simple description of video encode/decode complexity, serving as a key to
  23. // look up associated VideoStatsEntries in the database.
  24. struct MEDIA_EXPORT VideoDescKey {
  25. static VideoDescKey MakeBucketedKey(bool is_decode_stats,
  26. VideoCodecProfile codec_profile,
  27. bool hardware_accelerated,
  28. int pixels);
  29. // Returns a concise string representation of the key for storing in DB.
  30. std::string Serialize() const;
  31. // Returns a concise string representation of the key without pixels for
  32. // querying the DB.
  33. std::string SerializeWithoutPixels() const;
  34. // For debug logging. NOT interchangeable with Serialize().
  35. std::string ToLogStringForDebug() const;
  36. static absl::optional<int> ParsePixelsFromKey(std::string key);
  37. // Note: operator == and != are defined outside this class.
  38. const bool is_decode_stats;
  39. const VideoCodecProfile codec_profile;
  40. const bool hardware_accelerated;
  41. const int pixels;
  42. private:
  43. // All key's should be "bucketed" using MakeBucketedKey(...).
  44. VideoDescKey(bool is_decode_stats,
  45. VideoCodecProfile codec_profile,
  46. bool hardware_accelerated,
  47. int pixels);
  48. };
  49. struct MEDIA_EXPORT VideoStats {
  50. VideoStats(uint32_t frames_processed,
  51. uint32_t key_frames_processed,
  52. float p99_processing_time_ms);
  53. VideoStats(double timestamp,
  54. uint32_t frames_processed,
  55. uint32_t key_frames_processed,
  56. float p99_processing_time_ms);
  57. VideoStats(const VideoStats& entry);
  58. VideoStats& operator=(const VideoStats& entry);
  59. // For debug logging.
  60. std::string ToLogString() const;
  61. // Note: operator == and != are defined outside this class.
  62. double timestamp;
  63. uint32_t frames_processed;
  64. uint32_t key_frames_processed;
  65. float p99_processing_time_ms;
  66. };
  67. // VideoStatsEntry saved to identify the capabilities related to a given
  68. // |VideoDescKey|.
  69. using VideoStatsEntry = std::vector<VideoStats>;
  70. // VideoStatsCollection is used to return a collection of entries
  71. // corresponding to a certain key except for the number of pixels used. The
  72. // number of pixels is instead used as a key in the map for each
  73. // VideoStatsEntry.
  74. using VideoStatsCollection = base::flat_map<int, VideoStatsEntry>;
  75. virtual ~WebrtcVideoStatsDB() = default;
  76. // The maximum number of pixels that a stats key can have without being
  77. // considered out of range. This is used in sanity checks and is higher than
  78. // the maximum pixels value that can be saved to the database. For example, a
  79. // user may query the API for 8K resolution even though no data will be stored
  80. // for anything higher than 4K resolution.
  81. static constexpr int kPixelsAbsoluteMaxValue = 10 * 3840 * 2160;
  82. // The minimum number of pixels that a stats key can have to be considered to
  83. // be saved to the database. Set to 80% of the minimum pixels bucket.
  84. static constexpr int kPixelsMinValueToSave = 0.8 * 1280 * 720;
  85. // The maximum number of pixels that a stats key can have to be considered to
  86. // be saved to the database. Set to 120% of the largest pixels bucket.
  87. static constexpr int kPixelsMaxValueToSave = 1.2 * 3840 * 2160;
  88. // The minimum number of frames processed that a stats entry is based on. The
  89. // 99th percentile is not useful for anything less than 100 samples.
  90. static constexpr uint32_t kFramesProcessedMinValue = 100;
  91. // The maximum number of frames processed that a stats entry is based on.
  92. // Expected max number is around 30000.
  93. static constexpr uint32_t kFramesProcessedMaxValue = 60000;
  94. // Minimum valid 99th percentile of the processing time, which is either the
  95. // time needed for encoding or decoding.
  96. static constexpr float kP99ProcessingTimeMinValueMs = 0.0;
  97. // Maximum valid 99th percentile of the processing time, which is either the
  98. // time needed for encoding or decoding.
  99. static constexpr float kP99ProcessingTimeMaxValueMs = 10000.0;
  100. // Number of stats entries that are stored per configuration. The oldest
  101. // stats entry will be discarded when new stats are added if the list is
  102. // already full.
  103. static int GetMaxEntriesPerConfig();
  104. // Number of days after which a stats entry will be discarded. This
  105. // avoids users getting stuck with a bad capability prediction that may have
  106. // been due to one-off circumstances.
  107. static base::TimeDelta GetMaxTimeToKeepStats();
  108. // Run asynchronous initialization of database. Initialization must complete
  109. // before calling other APIs. |init_cb| must not be
  110. // a null callback.
  111. using InitializeCB = base::OnceCallback<void(bool)>;
  112. virtual void Initialize(InitializeCB init_cb) = 0;
  113. // Appends `video_stats` to existing entry associated with `key`. Will create
  114. // a new entry if none exists. The operation is asynchronous. The caller
  115. // should be aware of potential race conditions when calling this method for
  116. // the same `key` very close to other calls. `append_done_cb` will be run with
  117. // a bool to indicate whether the save succeeded.
  118. using AppendVideoStatsCB = base::OnceCallback<void(bool)>;
  119. virtual void AppendVideoStats(const VideoDescKey& key,
  120. const VideoStats& video_stats,
  121. AppendVideoStatsCB append_done_cb) = 0;
  122. // Returns the stats associated with `key`. The `get_stats_cb` will receive
  123. // the stats in addition to a boolean signaling if the call was successful.
  124. // VideoStatsEntry can be nullopt if there was no data associated with `key`.
  125. using GetVideoStatsCB =
  126. base::OnceCallback<void(bool, absl::optional<VideoStatsEntry>)>;
  127. virtual void GetVideoStats(const VideoDescKey& key,
  128. GetVideoStatsCB get_stats_cb) = 0;
  129. // Returns a collection of stats associated with `key` disregarding pixels.
  130. // The `get_stats_cb` will receive the stats in addition to a boolean
  131. // signaling if the call was successful. VideoStatsEntry can be nullopt if
  132. // there was no data associated with `key`.
  133. using GetVideoStatsCollectionCB =
  134. base::OnceCallback<void(bool, absl::optional<VideoStatsCollection>)>;
  135. virtual void GetVideoStatsCollection(
  136. const VideoDescKey& key,
  137. GetVideoStatsCollectionCB get_stats_cb) = 0;
  138. // Clear all statistics from the DB.
  139. virtual void ClearStats(base::OnceClosure clear_done_cb) = 0;
  140. };
  141. MEDIA_EXPORT bool operator==(const WebrtcVideoStatsDB::VideoDescKey& x,
  142. const WebrtcVideoStatsDB::VideoDescKey& y);
  143. MEDIA_EXPORT bool operator!=(const WebrtcVideoStatsDB::VideoDescKey& x,
  144. const WebrtcVideoStatsDB::VideoDescKey& y);
  145. MEDIA_EXPORT bool operator==(const WebrtcVideoStatsDB::VideoStats& x,
  146. const WebrtcVideoStatsDB::VideoStats& y);
  147. MEDIA_EXPORT bool operator!=(const WebrtcVideoStatsDB::VideoStats& x,
  148. const WebrtcVideoStatsDB::VideoStats& y);
  149. } // namespace media
  150. #endif // MEDIA_CAPABILITIES_WEBRTC_VIDEO_STATS_DB_H_