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