1 /* 2 * Copyright (c) 2012 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 // This sub-API supports the following functionalities: 12 // - Setting send and receive codecs. 13 // - Codec specific settings. 14 // - Key frame signaling. 15 // - Stream management settings. 16 17 #ifndef WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_CODEC_H_ 18 #define WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_CODEC_H_ 19 20 #include "webrtc/common_types.h" 21 22 namespace webrtc { 23 24 class VideoEngine; 25 struct VideoCodec; 26 27 // This class declares an abstract interface for a user defined observer. It is 28 // up to the VideoEngine user to implement a derived class which implements the 29 // observer class. The observer is registered using RegisterEncoderObserver() 30 // and deregistered using DeregisterEncoderObserver(). 31 class WEBRTC_DLLEXPORT ViEEncoderObserver { 32 public: 33 // This method is called once per second with the current encoded frame rate 34 // and bit rate. 35 virtual void OutgoingRate(const int video_channel, 36 const unsigned int framerate, 37 const unsigned int bitrate) = 0; 38 39 // This method is called whenever the state of the SuspendBelowMinBitrate 40 // changes, i.e., when |is_suspended| toggles. 41 virtual void SuspendChange(int video_channel, bool is_suspended) = 0; 42 43 protected: 44 virtual ~ViEEncoderObserver() {} 45 }; 46 47 // This class declares an abstract interface for a user defined observer. It is 48 // up to the VideoEngine user to implement a derived class which implements the 49 // observer class. The observer is registered using RegisterDecoderObserver() 50 // and deregistered using DeregisterDecoderObserver(). 51 class WEBRTC_DLLEXPORT ViEDecoderObserver { 52 public: 53 // This method is called when a new incoming stream is detected, normally 54 // triggered by a new incoming SSRC or payload type. 55 virtual void IncomingCodecChanged(const int video_channel, 56 const VideoCodec& video_codec) = 0; 57 58 // This method is called once per second containing the frame rate and bit 59 // rate for the incoming stream 60 virtual void IncomingRate(const int video_channel, 61 const unsigned int framerate, 62 const unsigned int bitrate) = 0; 63 64 // Called periodically with decoder timing information. All values are 65 // "current" snapshots unless decorated with a min_/max_ prefix. 66 virtual void DecoderTiming(int decode_ms, 67 int max_decode_ms, 68 int current_delay_ms, 69 int target_delay_ms, 70 int jitter_buffer_ms, 71 int min_playout_delay_ms, 72 int render_delay_ms) = 0; 73 74 // This method is called when the decoder needs a new key frame from encoder 75 // on the sender. 76 virtual void RequestNewKeyFrame(const int video_channel) = 0; 77 78 protected: 79 virtual ~ViEDecoderObserver() {} 80 }; 81 82 class WEBRTC_DLLEXPORT ViECodec { 83 public: 84 // Factory for the ViECodec subAPI and increases an internal reference 85 // counter if successful. Returns NULL if the API is not supported or if 86 // construction fails. 87 static ViECodec* GetInterface(VideoEngine* video_engine); 88 89 // Releases the ViECodec sub-API and decreases an internal reference 90 // counter. 91 // Returns the new reference count. This value should be zero 92 // for all sub-API:s before the VideoEngine object can be safely deleted. 93 virtual int Release() = 0; 94 95 // Gets the number of available codecs for the VideoEngine build. 96 virtual int NumberOfCodecs() const = 0; 97 98 // Gets a VideoCodec struct for a codec containing the default configuration 99 // for that codec type. 100 virtual int GetCodec(const unsigned char list_number, 101 VideoCodec& video_codec) const = 0; 102 103 // Sets the send codec to use for a specified channel. 104 virtual int SetSendCodec(const int video_channel, 105 const VideoCodec& video_codec) = 0; 106 107 // Gets the current send codec settings. 108 virtual int GetSendCodec(const int video_channel, 109 VideoCodec& video_codec) const = 0; 110 111 // Prepares VideoEngine to receive a certain codec type and setting for a 112 // specified payload type. 113 virtual int SetReceiveCodec(const int video_channel, 114 const VideoCodec& video_codec) = 0; 115 116 // Gets the current receive codec. 117 virtual int GetReceiveCodec(const int video_channel, 118 VideoCodec& video_codec) const = 0; 119 120 // This function is used to get codec configuration parameters to be 121 // signaled from the encoder to the decoder in the call setup. 122 virtual int GetCodecConfigParameters( 123 const int video_channel, 124 unsigned char config_parameters[kConfigParameterSize], 125 unsigned char& config_parameters_size) const = 0; 126 127 // Enables advanced scaling of the captured video stream if the stream 128 // differs from the send codec settings. 129 virtual int SetImageScaleStatus(const int video_channel, 130 const bool enable) = 0; 131 132 // Gets the number of sent key frames and number of sent delta frames. 133 virtual int GetSendCodecStastistics(const int video_channel, 134 unsigned int& key_frames, 135 unsigned int& delta_frames) const = 0; 136 137 // Gets the number of decoded key frames and number of decoded delta frames. 138 virtual int GetReceiveCodecStastistics(const int video_channel, 139 unsigned int& key_frames, 140 unsigned int& delta_frames) const = 0; 141 142 // Estimate of the min required buffer time from the expected arrival time 143 // until rendering to get smooth playback. 144 virtual int GetReceiveSideDelay(const int video_channel, 145 int* delay_ms) const = 0; 146 147 // Gets the bitrate targeted by the video codec rate control in kbit/s. 148 virtual int GetCodecTargetBitrate(const int video_channel, 149 unsigned int* bitrate) const = 0; 150 151 // Gets the number of packets discarded by the jitter buffer because they 152 // arrived too late. 153 virtual unsigned int GetDiscardedPackets(const int video_channel) const = 0; 154 155 // Enables key frame request callback in ViEDecoderObserver. 156 virtual int SetKeyFrameRequestCallbackStatus(const int video_channel, 157 const bool enable) = 0; 158 159 // Enables key frame requests for detected lost packets. 160 virtual int SetSignalKeyPacketLossStatus( 161 const int video_channel, 162 const bool enable, 163 const bool only_key_frames = false) = 0; 164 165 // Registers an instance of a user implementation of the ViEEncoderObserver. 166 virtual int RegisterEncoderObserver(const int video_channel, 167 ViEEncoderObserver& observer) = 0; 168 169 // Removes an already registered instance of ViEEncoderObserver. 170 virtual int DeregisterEncoderObserver(const int video_channel) = 0; 171 172 // Registers an instance of a user implementation of the ViEDecoderObserver. 173 virtual int RegisterDecoderObserver(const int video_channel, 174 ViEDecoderObserver& observer) = 0; 175 176 // Removes an already registered instance of ViEDecoderObserver. 177 virtual int DeregisterDecoderObserver(const int video_channel) = 0; 178 179 // This function forces the next encoded frame to be a key frame. This is 180 // normally used when the remote endpoint only supports outband key frame 181 // request. 182 virtual int SendKeyFrame(const int video_channel) = 0; 183 184 // This function makes the decoder wait for a key frame before starting to 185 // decode the incoming video stream. 186 virtual int WaitForFirstKeyFrame(const int video_channel, 187 const bool wait) = 0; 188 189 // Enables recording of debugging information. 190 virtual int StartDebugRecording(int video_channel, 191 const char* file_name_utf8) = 0; 192 // Disables recording of debugging information. 193 virtual int StopDebugRecording(int video_channel) = 0; 194 195 // Lets the sender suspend video when the rate drops below 196 // |threshold_bps|, and turns back on when the rate goes back up above 197 // |threshold_bps| + |window_bps|. 198 // This is under development; not tested. 199 virtual void SuspendBelowMinBitrate(int video_channel) = 0; 200 201 // TODO(holmer): Remove this default implementation when possible. 202 virtual bool GetSendSideDelay(int video_channel, int* avg_delay_ms, 203 int* max_delay_ms) const { return false; } 204 205 protected: 206 ViECodec() {} 207 virtual ~ViECodec() {} 208 }; 209 210 } // namespace webrtc 211 212 #endif // WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_CODEC_H_ 213