blob: 253fb04306c3fbbd17015d66981d0ef0169e94a3 [file] [log] [blame]
Niels Möller0327c2d2018-05-21 14:09:31 +02001/*
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
Elad Alon8f01c4e2019-06-28 15:19:43 +020016#include "api/fec_controller_override.h"
Steve Anton10542f22019-01-11 09:11:00 -080017#include "api/rtp_parameters.h" // For DegradationPreference.
Erik Språng610c7632019-03-06 15:37:33 +010018#include "api/units/data_rate.h"
Niels Möllerefd70342019-01-22 10:35:42 +010019#include "api/video/video_bitrate_allocator.h"
Niels Möller0327c2d2018-05-21 14:09:31 +020020#include "api/video/video_sink_interface.h"
21#include "api/video/video_source_interface.h"
22#include "api/video_codecs/video_encoder.h"
23#include "api/video_codecs/video_encoder_config.h"
24
25namespace webrtc {
26
Niels Möller0327c2d2018-05-21 14:09:31 +020027// This interface represents a class responsible for creating and driving the
28// encoder(s) for a single video stream. It is also responsible for adaptation
29// decisions related to video quality, requesting reduced frame rate or
30// resolution from the VideoSource when needed.
31// TODO(bugs.webrtc.org/8830): This interface is under development. Changes
32// under consideration include:
33//
34// 1. Taking out responsibility for adaptation decisions, instead only reporting
35// per-frame measurements to the decision maker.
36//
37// 2. Moving responsibility for simulcast and for software fallback into this
38// class.
39class VideoStreamEncoderInterface : public rtc::VideoSinkInterface<VideoFrame> {
40 public:
41 // Interface for receiving encoded video frames and notifications about
42 // configuration changes.
43 class EncoderSink : public EncodedImageCallback {
44 public:
45 virtual void OnEncoderConfigurationChanged(
46 std::vector<VideoStream> streams,
Rasmus Brandtc402dbe2019-02-04 11:09:46 +010047 VideoEncoderConfig::ContentType content_type,
Niels Möller0327c2d2018-05-21 14:09:31 +020048 int min_transmit_bitrate_bps) = 0;
49 };
50
Niels Möller0327c2d2018-05-21 14:09:31 +020051 // Sets the source that will provide video frames to the VideoStreamEncoder's
52 // OnFrame method. |degradation_preference| control whether or not resolution
53 // or frame rate may be reduced. The VideoStreamEncoder registers itself with
54 // |source|, and signals adaptation decisions to the source in the form of
55 // VideoSinkWants.
56 // TODO(nisse): When adaptation logic is extracted from this class,
57 // it no longer needs to know the source.
58 virtual void SetSource(
59 rtc::VideoSourceInterface<VideoFrame>* source,
60 const DegradationPreference& degradation_preference) = 0;
61
62 // Sets the |sink| that gets the encoded frames. |rotation_applied| means
63 // that the source must support rotation. Only set |rotation_applied| if the
64 // remote side does not support the rotation extension.
65 virtual void SetSink(EncoderSink* sink, bool rotation_applied) = 0;
66
67 // Sets an initial bitrate, later overriden by OnBitrateUpdated. Mainly
68 // affects the resolution of the initial key frame: If incoming frames are
69 // larger than reasonable for the start bitrate, and scaling is enabled,
70 // VideoStreamEncoder asks the source to scale down and drops a few initial
71 // frames.
72 // TODO(nisse): This is a poor interface, and mixes bandwidth estimation and
73 // codec configuration in an undesired way. For the actual send bandwidth, we
74 // should always be somewhat conservative, but we may nevertheless want to let
75 // the application configure a more optimistic quality for the initial
76 // resolution. Should be replaced by a construction time setting.
77 virtual void SetStartBitrate(int start_bitrate_bps) = 0;
78
79 // Request a key frame. Used for signalling from the remote receiver.
80 virtual void SendKeyFrame() = 0;
81
Elad Alonb6ef99b2019-04-10 16:37:07 +020082 // Inform the encoder that a loss has occurred.
83 virtual void OnLossNotification(
84 const VideoEncoder::LossNotification& loss_notification) = 0;
85
Erik Språng4c6ca302019-04-08 15:14:01 +020086 // Set the currently estimated network properties. A |target_bitrate|
Niels Möller0327c2d2018-05-21 14:09:31 +020087 // of zero pauses the encoder.
Florent Castellia8336d32019-09-09 13:36:55 +020088 // |stable_target_bitrate| is a filtered version of |target_bitrate|. It is
89 // always less or equal to it. It can be used to avoid rapid changes of
90 // expensive encoding settings, such as resolution.
Erik Språng4c6ca302019-04-08 15:14:01 +020091 // |link_allocation| is the bandwidth available for this video stream on the
92 // network link. It is always at least |target_bitrate| but may be higher
93 // if we are not network constrained.
Erik Språng610c7632019-03-06 15:37:33 +010094 virtual void OnBitrateUpdated(DataRate target_bitrate,
Florent Castellia8336d32019-09-09 13:36:55 +020095 DataRate stable_target_bitrate,
Erik Språng4c6ca302019-04-08 15:14:01 +020096 DataRate link_allocation,
Niels Möller0327c2d2018-05-21 14:09:31 +020097 uint8_t fraction_lost,
Ying Wang9b881ab2020-02-07 14:29:32 +010098 int64_t round_trip_time_ms,
99 double cwnd_reduce_ratio) = 0;
Niels Möller0327c2d2018-05-21 14:09:31 +0200100
101 // Register observer for the bitrate allocation between the temporal
102 // and spatial layers.
103 virtual void SetBitrateAllocationObserver(
104 VideoBitrateAllocationObserver* bitrate_observer) = 0;
105
Elad Alon8f01c4e2019-06-28 15:19:43 +0200106 // Set a FecControllerOverride, through which the encoder may override
107 // decisions made by FecController.
Elad Alon8f01c4e2019-06-28 15:19:43 +0200108 virtual void SetFecControllerOverride(
Elad Alona63aede2019-06-28 18:20:58 +0200109 FecControllerOverride* fec_controller_override) = 0;
Elad Alon8f01c4e2019-06-28 15:19:43 +0200110
Niels Möller0327c2d2018-05-21 14:09:31 +0200111 // Creates and configures an encoder with the given |config|. The
112 // |max_data_payload_length| is used to support single NAL unit
113 // packetization for H.264.
114 virtual void ConfigureEncoder(VideoEncoderConfig config,
115 size_t max_data_payload_length) = 0;
116
117 // Permanently stop encoding. After this method has returned, it is
118 // guaranteed that no encoded frames will be delivered to the sink.
119 virtual void Stop() = 0;
120};
121
122} // namespace webrtc
123
124#endif // API_VIDEO_VIDEO_STREAM_ENCODER_INTERFACE_H_