1 /* 2 * Copyright (c) 2018 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef API_VIDEO_VIDEO_STREAM_ENCODER_INTERFACE_H_ 12 #define API_VIDEO_VIDEO_STREAM_ENCODER_INTERFACE_H_ 13 14 #include <vector> 15 16 #include "api/adaptation/resource.h" 17 #include "api/fec_controller_override.h" 18 #include "api/rtp_parameters.h" // For DegradationPreference. 19 #include "api/scoped_refptr.h" 20 #include "api/units/data_rate.h" 21 #include "api/video/video_bitrate_allocator.h" 22 #include "api/video/video_sink_interface.h" 23 #include "api/video/video_source_interface.h" 24 #include "api/video_codecs/video_encoder.h" 25 #include "api/video_codecs/video_encoder_config.h" 26 27 namespace webrtc { 28 29 // This interface represents a class responsible for creating and driving the 30 // encoder(s) for a single video stream. It is also responsible for adaptation 31 // decisions related to video quality, requesting reduced frame rate or 32 // resolution from the VideoSource when needed. 33 // TODO(bugs.webrtc.org/8830): This interface is under development. Changes 34 // under consideration include: 35 // 36 // 1. Taking out responsibility for adaptation decisions, instead only reporting 37 // per-frame measurements to the decision maker. 38 // 39 // 2. Moving responsibility for simulcast and for software fallback into this 40 // class. 41 class VideoStreamEncoderInterface : public rtc::VideoSinkInterface<VideoFrame> { 42 public: 43 // Interface for receiving encoded video frames and notifications about 44 // configuration changes. 45 class EncoderSink : public EncodedImageCallback { 46 public: 47 virtual void OnEncoderConfigurationChanged( 48 std::vector<VideoStream> streams, 49 bool is_svc, 50 VideoEncoderConfig::ContentType content_type, 51 int min_transmit_bitrate_bps) = 0; 52 }; 53 54 // If the resource is overusing, the VideoStreamEncoder will try to reduce 55 // resolution or frame rate until no resource is overusing. 56 // TODO(https://crbug.com/webrtc/11565): When the ResourceAdaptationProcessor 57 // is moved to Call this method could be deleted altogether in favor of 58 // Call-level APIs only. 59 virtual void AddAdaptationResource(rtc::scoped_refptr<Resource> resource) = 0; 60 virtual std::vector<rtc::scoped_refptr<Resource>> 61 GetAdaptationResources() = 0; 62 63 // Sets the source that will provide video frames to the VideoStreamEncoder's 64 // OnFrame method. |degradation_preference| control whether or not resolution 65 // or frame rate may be reduced. The VideoStreamEncoder registers itself with 66 // |source|, and signals adaptation decisions to the source in the form of 67 // VideoSinkWants. 68 // TODO(nisse): When adaptation logic is extracted from this class, 69 // it no longer needs to know the source. 70 virtual void SetSource( 71 rtc::VideoSourceInterface<VideoFrame>* source, 72 const DegradationPreference& degradation_preference) = 0; 73 74 // Sets the |sink| that gets the encoded frames. |rotation_applied| means 75 // that the source must support rotation. Only set |rotation_applied| if the 76 // remote side does not support the rotation extension. 77 virtual void SetSink(EncoderSink* sink, bool rotation_applied) = 0; 78 79 // Sets an initial bitrate, later overriden by OnBitrateUpdated. Mainly 80 // affects the resolution of the initial key frame: If incoming frames are 81 // larger than reasonable for the start bitrate, and scaling is enabled, 82 // VideoStreamEncoder asks the source to scale down and drops a few initial 83 // frames. 84 // TODO(nisse): This is a poor interface, and mixes bandwidth estimation and 85 // codec configuration in an undesired way. For the actual send bandwidth, we 86 // should always be somewhat conservative, but we may nevertheless want to let 87 // the application configure a more optimistic quality for the initial 88 // resolution. Should be replaced by a construction time setting. 89 virtual void SetStartBitrate(int start_bitrate_bps) = 0; 90 91 // Request a key frame. Used for signalling from the remote receiver. 92 virtual void SendKeyFrame() = 0; 93 94 // Inform the encoder that a loss has occurred. 95 virtual void OnLossNotification( 96 const VideoEncoder::LossNotification& loss_notification) = 0; 97 98 // Set the currently estimated network properties. A |target_bitrate| 99 // of zero pauses the encoder. 100 // |stable_target_bitrate| is a filtered version of |target_bitrate|. It is 101 // always less or equal to it. It can be used to avoid rapid changes of 102 // expensive encoding settings, such as resolution. 103 // |link_allocation| is the bandwidth available for this video stream on the 104 // network link. It is always at least |target_bitrate| but may be higher 105 // if we are not network constrained. 106 virtual void OnBitrateUpdated(DataRate target_bitrate, 107 DataRate stable_target_bitrate, 108 DataRate link_allocation, 109 uint8_t fraction_lost, 110 int64_t round_trip_time_ms, 111 double cwnd_reduce_ratio) = 0; 112 113 // Register observer for the bitrate allocation between the temporal 114 // and spatial layers. 115 virtual void SetBitrateAllocationObserver( 116 VideoBitrateAllocationObserver* bitrate_observer) = 0; 117 118 // Set a FecControllerOverride, through which the encoder may override 119 // decisions made by FecController. 120 virtual void SetFecControllerOverride( 121 FecControllerOverride* fec_controller_override) = 0; 122 123 // Creates and configures an encoder with the given |config|. The 124 // |max_data_payload_length| is used to support single NAL unit 125 // packetization for H.264. 126 virtual void ConfigureEncoder(VideoEncoderConfig config, 127 size_t max_data_payload_length) = 0; 128 129 // Permanently stop encoding. After this method has returned, it is 130 // guaranteed that no encoded frames will be delivered to the sink. 131 virtual void Stop() = 0; 132 }; 133 134 } // namespace webrtc 135 136 #endif // API_VIDEO_VIDEO_STREAM_ENCODER_INTERFACE_H_ 137