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