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 // - Callbacks for RTP and RTCP events such as modified SSRC or CSRC. 13 // - SSRC handling. 14 // - Transmission of RTCP reports. 15 // - Obtaining RTCP data from incoming RTCP sender reports. 16 // - RTP and RTCP statistics (jitter, packet loss, RTT etc.). 17 // - Forward Error Correction (FEC). 18 // - Writing RTP and RTCP packets to binary files for offline analysis of the 19 // call quality. 20 // - Inserting extra RTP packets into active audio stream. 21 22 #ifndef WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_RTP_RTCP_H_ 23 #define WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_RTP_RTCP_H_ 24 25 #include "webrtc/common_types.h" 26 27 namespace webrtc { 28 29 class VideoEngine; 30 struct ReceiveBandwidthEstimatorStats; 31 32 // This enumerator sets the RTCP mode. 33 enum ViERTCPMode { 34 kRtcpNone = 0, 35 kRtcpCompound_RFC4585 = 1, 36 kRtcpNonCompound_RFC5506 = 2 37 }; 38 39 // This enumerator describes the key frame request mode. 40 enum ViEKeyFrameRequestMethod { 41 kViEKeyFrameRequestNone = 0, 42 kViEKeyFrameRequestPliRtcp = 1, 43 kViEKeyFrameRequestFirRtp = 2, 44 kViEKeyFrameRequestFirRtcp = 3 45 }; 46 47 enum StreamType { 48 kViEStreamTypeNormal = 0, // Normal media stream 49 kViEStreamTypeRtx = 1 // Retransmission media stream 50 }; 51 52 // This class declares an abstract interface for a user defined observer. It is 53 // up to the VideoEngine user to implement a derived class which implements the 54 // observer class. The observer is registered using RegisterRTPObserver() and 55 // deregistered using DeregisterRTPObserver(). 56 class WEBRTC_DLLEXPORT ViERTPObserver { 57 public: 58 // This method is called if SSRC of the incoming stream is changed. 59 virtual void IncomingSSRCChanged(const int video_channel, 60 const unsigned int SSRC) = 0; 61 62 // This method is called if a field in CSRC changes or if the number of 63 // CSRCs changes. 64 virtual void IncomingCSRCChanged(const int video_channel, 65 const unsigned int CSRC, 66 const bool added) = 0; 67 protected: 68 virtual ~ViERTPObserver() {} 69 }; 70 71 // This class declares an abstract interface for a user defined observer. It is 72 // up to the VideoEngine user to implement a derived class which implements the 73 // observer class. The observer is registered using RegisterRTCPObserver() and 74 // deregistered using DeregisterRTCPObserver(). 75 76 class WEBRTC_DLLEXPORT ViERTCPObserver { 77 public: 78 // This method is called if a application-defined RTCP packet has been 79 // received. 80 virtual void OnApplicationDataReceived( 81 const int video_channel, 82 const unsigned char sub_type, 83 const unsigned int name, 84 const char* data, 85 const unsigned short data_length_in_bytes) = 0; 86 protected: 87 virtual ~ViERTCPObserver() {} 88 }; 89 90 class WEBRTC_DLLEXPORT ViERTP_RTCP { 91 public: 92 enum { KDefaultDeltaTransmitTimeSeconds = 15 }; 93 enum { KMaxRTCPCNameLength = 256 }; 94 95 // Factory for the ViERTP_RTCP subAPI and increases an internal reference 96 // counter if successful. Returns NULL if the API is not supported or if 97 // construction fails. 98 static ViERTP_RTCP* GetInterface(VideoEngine* video_engine); 99 100 // Releases the ViERTP_RTCP sub-API and decreases an internal reference 101 // counter. Returns the new reference count. This value should be zero 102 // for all sub-API:s before the VideoEngine object can be safely deleted. 103 virtual int Release() = 0; 104 105 // This function enables you to specify the RTP synchronization source 106 // identifier (SSRC) explicitly. 107 virtual int SetLocalSSRC(const int video_channel, 108 const unsigned int SSRC, 109 const StreamType usage = kViEStreamTypeNormal, 110 const unsigned char simulcast_idx = 0) = 0; 111 112 // This function gets the SSRC for the outgoing RTP stream for the specified 113 // channel. 114 virtual int GetLocalSSRC(const int video_channel, 115 unsigned int& SSRC) const = 0; 116 117 // This function map a incoming SSRC to a StreamType so that the engine 118 // can know which is the normal stream and which is the RTX 119 virtual int SetRemoteSSRCType(const int video_channel, 120 const StreamType usage, 121 const unsigned int SSRC) const = 0; 122 123 // This function gets the SSRC for the incoming RTP stream for the specified 124 // channel. 125 virtual int GetRemoteSSRC(const int video_channel, 126 unsigned int& SSRC) const = 0; 127 128 // This function returns the CSRCs of the incoming RTP packets. 129 virtual int GetRemoteCSRCs(const int video_channel, 130 unsigned int CSRCs[kRtpCsrcSize]) const = 0; 131 132 // This sets a specific payload type for the RTX stream. Note that this 133 // doesn't enable RTX, SetLocalSSRC must still be called to enable RTX. 134 virtual int SetRtxSendPayloadType(const int video_channel, 135 const uint8_t payload_type) = 0; 136 137 // This enables sending redundant payloads when padding up the bitrate instead 138 // of sending dummy padding packets. This feature is off by default and will 139 // only have an effect if RTX is also enabled. 140 // TODO(holmer): Remove default implementation once this has been implemented 141 // in libjingle. 142 virtual int SetPadWithRedundantPayloads(int video_channel, bool enable) { 143 return 0; 144 } 145 146 virtual int SetRtxReceivePayloadType(const int video_channel, 147 const uint8_t payload_type) = 0; 148 149 // This function enables manual initialization of the sequence number. The 150 // start sequence number is normally a random number. 151 virtual int SetStartSequenceNumber(const int video_channel, 152 unsigned short sequence_number) = 0; 153 154 // This function sets the RTCP status for the specified channel. 155 // Default mode is kRtcpCompound_RFC4585. 156 virtual int SetRTCPStatus(const int video_channel, 157 const ViERTCPMode rtcp_mode) = 0; 158 159 // This function gets the RTCP status for the specified channel. 160 virtual int GetRTCPStatus(const int video_channel, 161 ViERTCPMode& rtcp_mode) const = 0; 162 163 // This function sets the RTCP canonical name (CNAME) for the RTCP reports 164 // on a specific channel. 165 virtual int SetRTCPCName(const int video_channel, 166 const char rtcp_cname[KMaxRTCPCNameLength]) = 0; 167 168 // This function gets the RTCP canonical name (CNAME) for the RTCP reports 169 // sent the specified channel. 170 virtual int GetRTCPCName(const int video_channel, 171 char rtcp_cname[KMaxRTCPCNameLength]) const = 0; 172 173 // This function gets the RTCP canonical name (CNAME) for the RTCP reports 174 // received on the specified channel. 175 virtual int GetRemoteRTCPCName( 176 const int video_channel, 177 char rtcp_cname[KMaxRTCPCNameLength]) const = 0; 178 179 // This function sends an RTCP APP packet on a specific channel. 180 virtual int SendApplicationDefinedRTCPPacket( 181 const int video_channel, 182 const unsigned char sub_type, 183 unsigned int name, 184 const char* data, 185 unsigned short data_length_in_bytes) = 0; 186 187 // This function enables Negative Acknowledgment (NACK) using RTCP, 188 // implemented based on RFC 4585. NACK retransmits RTP packets if lost on 189 // the network. This creates a lossless transport at the expense of delay. 190 // If using NACK, NACK should be enabled on both endpoints in a call. 191 virtual int SetNACKStatus(const int video_channel, const bool enable) = 0; 192 193 // This function enables Forward Error Correction (FEC) using RTCP, 194 // implemented based on RFC 5109, to improve packet loss robustness. Extra 195 // FEC packets are sent together with the usual media packets, hence 196 // part of the bitrate will be used for FEC packets. 197 virtual int SetFECStatus(const int video_channel, 198 const bool enable, 199 const unsigned char payload_typeRED, 200 const unsigned char payload_typeFEC) = 0; 201 202 // This function enables hybrid Negative Acknowledgment using RTCP 203 // and Forward Error Correction (FEC) implemented based on RFC 5109, 204 // to improve packet loss robustness. Extra 205 // FEC packets are sent together with the usual media packets, hence will 206 // part of the bitrate be used for FEC packets. 207 // The hybrid mode will choose between nack only, fec only and both based on 208 // network conditions. When both are applied, only packets that were not 209 // recovered by the FEC will be nacked. 210 virtual int SetHybridNACKFECStatus(const int video_channel, 211 const bool enable, 212 const unsigned char payload_typeRED, 213 const unsigned char payload_typeFEC) = 0; 214 215 // Sets send side support for delayed video buffering (actual delay will 216 // be exhibited on the receiver side). 217 // Target delay should be set to zero for real-time mode. 218 virtual int SetSenderBufferingMode(int video_channel, 219 int target_delay_ms) = 0; 220 // Sets receive side support for delayed video buffering. Target delay should 221 // be set to zero for real-time mode. 222 virtual int SetReceiverBufferingMode(int video_channel, 223 int target_delay_ms) = 0; 224 225 // This function enables RTCP key frame requests. 226 virtual int SetKeyFrameRequestMethod( 227 const int video_channel, const ViEKeyFrameRequestMethod method) = 0; 228 229 // This function enables signaling of temporary bitrate constraints using 230 // RTCP, implemented based on RFC4585. 231 virtual int SetTMMBRStatus(const int video_channel, const bool enable) = 0; 232 233 // Enables and disables REMB packets for this channel. |sender| indicates 234 // this channel is encoding, |receiver| tells the bitrate estimate for 235 // this channel should be included in the REMB packet. 236 virtual int SetRembStatus(int video_channel, 237 bool sender, 238 bool receiver) = 0; 239 240 // Enables RTP timestamp extension offset described in RFC 5450. This call 241 // must be done before ViECodec::SetSendCodec is called. 242 virtual int SetSendTimestampOffsetStatus(int video_channel, 243 bool enable, 244 int id) = 0; 245 246 virtual int SetReceiveTimestampOffsetStatus(int video_channel, 247 bool enable, 248 int id) = 0; 249 250 // Enables RTP absolute send time header extension. This call must be done 251 // before ViECodec::SetSendCodec is called. 252 virtual int SetSendAbsoluteSendTimeStatus(int video_channel, 253 bool enable, 254 int id) = 0; 255 256 // When enabled for a channel, *all* channels on the same transport will be 257 // expected to include the absolute send time header extension. 258 virtual int SetReceiveAbsoluteSendTimeStatus(int video_channel, 259 bool enable, 260 int id) = 0; 261 262 // Enables/disables RTCP Receiver Reference Time Report Block extension/ 263 // DLRR Report Block extension (RFC 3611). 264 // TODO(asapersson): Remove default implementation. 265 virtual int SetRtcpXrRrtrStatus(int video_channel, bool enable) { return -1; } 266 267 // Enables transmission smoothening, i.e. packets belonging to the same frame 268 // will be sent over a longer period of time instead of sending them 269 // back-to-back. 270 virtual int SetTransmissionSmoothingStatus(int video_channel, 271 bool enable) = 0; 272 273 // Sets a minimal bitrate which will be padded to when the encoder doesn't 274 // produce enough bitrate. 275 // TODO(pbos): Remove default implementation when libjingle's 276 // FakeWebRtcVideoEngine is updated. 277 virtual int SetMinTransmitBitrate(int video_channel, 278 int min_transmit_bitrate_kbps) { 279 return -1; 280 }; 281 282 // Set a constant amount to deduct from received bitrate estimates before 283 // using it to allocate capacity among outgoing video streams. 284 virtual int SetReservedTransmitBitrate( 285 int video_channel, unsigned int reserved_transmit_bitrate_bps) { 286 return 0; 287 } 288 289 // This function returns our locally created statistics of the received RTP 290 // stream. 291 virtual int GetReceiveChannelRtcpStatistics(const int video_channel, 292 RtcpStatistics& basic_stats, 293 int& rtt_ms) const = 0; 294 295 // This function returns statistics reported by the remote client in a RTCP 296 // packet. 297 virtual int GetSendChannelRtcpStatistics(const int video_channel, 298 RtcpStatistics& basic_stats, 299 int& rtt_ms) const = 0; 300 301 // TODO(sprang): Temporary hacks to prevent libjingle build from failing, 302 // remove when libjingle has been lifted to support webrtc issue 2589 303 virtual int GetReceivedRTCPStatistics(const int video_channel, 304 unsigned short& fraction_lost, 305 unsigned int& cumulative_lost, 306 unsigned int& extended_max, 307 unsigned int& jitter, 308 int& rtt_ms) const { 309 RtcpStatistics stats; 310 int ret_code = GetReceiveChannelRtcpStatistics(video_channel, 311 stats, 312 rtt_ms); 313 fraction_lost = stats.fraction_lost; 314 cumulative_lost = stats.cumulative_lost; 315 extended_max = stats.extended_max_sequence_number; 316 jitter = stats.jitter; 317 return ret_code; 318 } 319 virtual int GetSentRTCPStatistics(const int video_channel, 320 unsigned short& fraction_lost, 321 unsigned int& cumulative_lost, 322 unsigned int& extended_max, 323 unsigned int& jitter, 324 int& rtt_ms) const { 325 RtcpStatistics stats; 326 int ret_code = GetSendChannelRtcpStatistics(video_channel, 327 stats, 328 rtt_ms); 329 fraction_lost = stats.fraction_lost; 330 cumulative_lost = stats.cumulative_lost; 331 extended_max = stats.extended_max_sequence_number; 332 jitter = stats.jitter; 333 return ret_code; 334 } 335 336 337 virtual int RegisterSendChannelRtcpStatisticsCallback( 338 int video_channel, RtcpStatisticsCallback* callback) = 0; 339 340 virtual int DeregisterSendChannelRtcpStatisticsCallback( 341 int video_channel, RtcpStatisticsCallback* callback) = 0; 342 343 virtual int RegisterReceiveChannelRtcpStatisticsCallback( 344 int video_channel, RtcpStatisticsCallback* callback) = 0; 345 346 virtual int DeregisterReceiveChannelRtcpStatisticsCallback( 347 int video_channel, RtcpStatisticsCallback* callback) = 0; 348 349 // The function gets statistics from the sent and received RTP streams. 350 virtual int GetRtpStatistics(const int video_channel, 351 StreamDataCounters& sent, 352 StreamDataCounters& received) const = 0; 353 354 // TODO(sprang): Temporary hacks to prevent libjingle build from failing, 355 // remove when libjingle has been lifted to support webrtc issue 2589 356 virtual int GetRTPStatistics(const int video_channel, 357 unsigned int& bytes_sent, 358 unsigned int& packets_sent, 359 unsigned int& bytes_received, 360 unsigned int& packets_received) const { 361 StreamDataCounters sent; 362 StreamDataCounters received; 363 int ret_code = GetRtpStatistics(video_channel, sent, received); 364 bytes_sent = sent.bytes; 365 packets_sent = sent.packets; 366 bytes_received = received.bytes; 367 packets_received = received.packets; 368 return ret_code; 369 } 370 371 virtual int RegisterSendChannelRtpStatisticsCallback( 372 int video_channel, StreamDataCountersCallback* callback) = 0; 373 374 virtual int DeregisterSendChannelRtpStatisticsCallback( 375 int video_channel, StreamDataCountersCallback* callback) = 0; 376 377 virtual int RegisterReceiveChannelRtpStatisticsCallback( 378 int video_channel, StreamDataCountersCallback* callback) = 0; 379 380 virtual int DeregisterReceiveChannelRtpStatisticsCallback( 381 int video_channel, StreamDataCountersCallback* callback) = 0; 382 383 384 // Gets sent and received RTCP packet types. 385 // TODO(asapersson): Remove default implementation. 386 virtual int GetRtcpPacketTypeCounters( 387 int video_channel, 388 RtcpPacketTypeCounter* packets_sent, 389 RtcpPacketTypeCounter* packets_received) const { return -1; } 390 391 // The function gets bandwidth usage statistics from the sent RTP streams in 392 // bits/s. 393 virtual int GetBandwidthUsage(const int video_channel, 394 unsigned int& total_bitrate_sent, 395 unsigned int& video_bitrate_sent, 396 unsigned int& fec_bitrate_sent, 397 unsigned int& nackBitrateSent) const = 0; 398 399 // (De)Register an observer, called whenever the send bitrate is updated 400 virtual int RegisterSendBitrateObserver( 401 int video_channel, 402 BitrateStatisticsObserver* observer) = 0; 403 404 virtual int DeregisterSendBitrateObserver( 405 int video_channel, 406 BitrateStatisticsObserver* observer) = 0; 407 408 // This function gets the send-side estimated bandwidth available for video, 409 // including overhead, in bits/s. 410 virtual int GetEstimatedSendBandwidth( 411 const int video_channel, 412 unsigned int* estimated_bandwidth) const = 0; 413 414 // This function gets the receive-side estimated bandwidth available for 415 // video, including overhead, in bits/s. |estimated_bandwidth| is 0 if there 416 // is no valid estimate. 417 virtual int GetEstimatedReceiveBandwidth( 418 const int video_channel, 419 unsigned int* estimated_bandwidth) const = 0; 420 421 // This function gets the receive-side bandwidth esitmator statistics. 422 // TODO(jiayl): remove the default impl when libjingle's FakeWebRtcVideoEngine 423 // is updated. 424 virtual int GetReceiveBandwidthEstimatorStats( 425 const int video_channel, 426 ReceiveBandwidthEstimatorStats* output) const { return -1; } 427 428 // This function gets the PacedSender queuing delay for the last sent frame. 429 // TODO(jiayl): remove the default impl when libjingle is updated. 430 virtual int GetPacerQueuingDelayMs( 431 const int video_channel, int* delay_ms) const { 432 return -1; 433 } 434 435 // This function enables capturing of RTP packets to a binary file on a 436 // specific channel and for a given direction. The file can later be 437 // replayed using e.g. RTP Tools rtpplay since the binary file format is 438 // compatible with the rtpdump format. 439 virtual int StartRTPDump(const int video_channel, 440 const char file_nameUTF8[1024], 441 RTPDirections direction) = 0; 442 443 // This function disables capturing of RTP packets to a binary file on a 444 // specific channel and for a given direction. 445 virtual int StopRTPDump(const int video_channel, 446 RTPDirections direction) = 0; 447 448 // Registers an instance of a user implementation of the ViERTPObserver. 449 virtual int RegisterRTPObserver(const int video_channel, 450 ViERTPObserver& observer) = 0; 451 452 // Removes a registered instance of ViERTPObserver. 453 virtual int DeregisterRTPObserver(const int video_channel) = 0; 454 455 // Registers an instance of a user implementation of the ViERTCPObserver. 456 virtual int RegisterRTCPObserver(const int video_channel, 457 ViERTCPObserver& observer) = 0; 458 459 // Removes a registered instance of ViERTCPObserver. 460 virtual int DeregisterRTCPObserver(const int video_channel) = 0; 461 462 // Registers and instance of a user implementation of ViEFrameCountObserver 463 virtual int RegisterSendFrameCountObserver( 464 int video_channel, FrameCountObserver* observer) = 0; 465 466 // Removes a registered instance of a ViEFrameCountObserver 467 virtual int DeregisterSendFrameCountObserver( 468 int video_channel, FrameCountObserver* observer) = 0; 469 470 protected: 471 virtual ~ViERTP_RTCP() {} 472 }; 473 474 } // namespace webrtc 475 476 #endif // WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_RTP_RTCP_H_ 477
