/* * Copyright (c) 2018 The WebRTC project authors. All Rights Reserved. * * Use of this source code is governed by a BSD-style license * that can be found in the LICENSE file in the root of the source * tree. An additional intellectual property rights grant can be found * in the file PATENTS. All contributing project authors may * be found in the AUTHORS file in the root of the source tree. */ #ifndef API_TEST_VIDEO_QUALITY_ANALYZER_INTERFACE_H_ #define API_TEST_VIDEO_QUALITY_ANALYZER_INTERFACE_H_ #include #include #include "absl/strings/string_view.h" #include "absl/types/optional.h" #include "api/array_view.h" #include "api/test/stats_observer_interface.h" #include "api/video/encoded_image.h" #include "api/video/video_frame.h" #include "api/video_codecs/video_encoder.h" namespace webrtc { namespace webrtc_pc_e2e { // API is in development and can be changed without notice. // Base interface for video quality analyzer for peer connection level end-2-end // tests. Interface has only one abstract method, which have to return frame id. // Other methods have empty implementation by default, so user can override only // required parts. // // VideoQualityAnalyzerInterface will be injected into WebRTC pipeline on both // sides of the call. Here is video data flow in WebRTC pipeline // // Alice: // ___________ ________ _________ // | | | | | | // | Frame |-(A)→| WebRTC |-(B)→| Video |-(C)┐ // | Generator | | Stack | | Decoder | | // ¯¯¯¯¯¯¯¯¯¯¯ ¯¯¯¯¯¯¯¯ ¯¯¯¯¯¯¯¯¯ | // __↓________ // | Transport | // | & | // | Network | // ¯¯|¯¯¯¯¯¯¯¯ // Bob: | // _______ ________ _________ | // | | | | | | | // | Video |←(F)-| WebRTC |←(E)-| Video |←(D)----┘ // | Sink | | Stack | | Decoder | // ¯¯¯¯¯¯¯ ¯¯¯¯¯¯¯¯ ¯¯¯¯¯¯¯¯¯ // The analyzer will be injected in all points from A to F. class VideoQualityAnalyzerInterface : public StatsObserverInterface { public: // Contains extra statistic provided by video encoder. struct EncoderStats { // TODO(hbos) https://crbug.com/webrtc/9547, // https://crbug.com/webrtc/11443: improve stats API to make available // there. uint32_t target_encode_bitrate; }; // Contains extra statistic provided by video decoder. struct DecoderStats { // Decode time provided by decoder itself. If decoder doesn’t produce such // information can be omitted. absl::optional decode_time_ms; }; ~VideoQualityAnalyzerInterface() override = default; // Will be called by framework before test. // |test_case_name| is name of test case, that should be used to report all // video metrics. // |threads_count| is number of threads that analyzer can use for heavy // calculations. Analyzer can perform simple calculations on the calling // thread in each method, but should remember, that it is the same thread, // that is used in video pipeline. virtual void Start(std::string test_case_name, rtc::ArrayView peer_names, int max_threads_count) {} // Will be called when frame was generated from the input stream. // |peer_name| is name of the peer on which side frame was captured. // Returns frame id, that will be set by framework to the frame. virtual uint16_t OnFrameCaptured(absl::string_view peer_name, const std::string& stream_label, const VideoFrame& frame) = 0; // Will be called before calling the encoder. // |peer_name| is name of the peer on which side frame came to encoder. virtual void OnFramePreEncode(absl::string_view peer_name, const VideoFrame& frame) {} // Will be called for each EncodedImage received from encoder. Single // VideoFrame can produce multiple EncodedImages. Each encoded image will // have id from VideoFrame. // |peer_name| is name of the peer on which side frame was encoded. virtual void OnFrameEncoded(absl::string_view peer_name, uint16_t frame_id, const EncodedImage& encoded_image, const EncoderStats& stats) {} // Will be called for each frame dropped by encoder. // |peer_name| is name of the peer on which side frame drop was detected. virtual void OnFrameDropped(absl::string_view peer_name, EncodedImageCallback::DropReason reason) {} // Will be called before calling the decoder. // |peer_name| is name of the peer on which side frame was received. virtual void OnFramePreDecode(absl::string_view peer_name, uint16_t frame_id, const EncodedImage& encoded_image) {} // Will be called after decoding the frame. // |peer_name| is name of the peer on which side frame was decoded. virtual void OnFrameDecoded(absl::string_view peer_name, const VideoFrame& frame, const DecoderStats& stats) {} // Will be called when frame will be obtained from PeerConnection stack. // |peer_name| is name of the peer on which side frame was rendered. virtual void OnFrameRendered(absl::string_view peer_name, const VideoFrame& frame) {} // Will be called if encoder return not WEBRTC_VIDEO_CODEC_OK. // All available codes are listed in // modules/video_coding/include/video_error_codes.h // |peer_name| is name of the peer on which side error acquired. virtual void OnEncoderError(absl::string_view peer_name, const VideoFrame& frame, int32_t error_code) {} // Will be called if decoder return not WEBRTC_VIDEO_CODEC_OK. // All available codes are listed in // modules/video_coding/include/video_error_codes.h // |peer_name| is name of the peer on which side error acquired. virtual void OnDecoderError(absl::string_view peer_name, uint16_t frame_id, int32_t error_code) {} // Will be called every time new stats reports are available for the // Peer Connection identified by |pc_label|. void OnStatsReports( absl::string_view pc_label, const rtc::scoped_refptr& report) override {} // Tells analyzer that analysis complete and it should calculate final // statistics. virtual void Stop() {} virtual std::string GetStreamLabel(uint16_t frame_id) = 0; }; } // namespace webrtc_pc_e2e } // namespace webrtc #endif // API_TEST_VIDEO_QUALITY_ANALYZER_INTERFACE_H_