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