Home | History | Annotate | Download | only in include
      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