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 //  - 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   // TODO(asapersson): Remove default implementation.
    154   virtual int GetNumDiscardedPackets(int video_channel) const { return -1; }
    155 
    156   // TODO(asapersson): Remove once the api has been removed from
    157   // fakewebrtcvideoengine.h.
    158   virtual unsigned int GetDiscardedPackets(
    159       const int video_channel) const { return 0; }
    160 
    161   // Enables key frame request callback in ViEDecoderObserver.
    162   virtual int SetKeyFrameRequestCallbackStatus(const int video_channel,
    163                                                const bool enable) = 0;
    164 
    165   // Enables key frame requests for detected lost packets.
    166   virtual int SetSignalKeyPacketLossStatus(
    167       const int video_channel,
    168       const bool enable,
    169       const bool only_key_frames = false) = 0;
    170 
    171   // Registers an instance of a user implementation of the ViEEncoderObserver.
    172   virtual int RegisterEncoderObserver(const int video_channel,
    173                                       ViEEncoderObserver& observer) = 0;
    174 
    175   // Removes an already registered instance of ViEEncoderObserver.
    176   virtual int DeregisterEncoderObserver(const int video_channel) = 0;
    177 
    178   // Registers an instance of a user implementation of the ViEDecoderObserver.
    179   virtual int RegisterDecoderObserver(const int video_channel,
    180                                       ViEDecoderObserver& observer) = 0;
    181 
    182   // Removes an already registered instance of ViEDecoderObserver.
    183   virtual int DeregisterDecoderObserver(const int video_channel) = 0;
    184 
    185   // This function forces the next encoded frame to be a key frame. This is
    186   // normally used when the remote endpoint only supports outband key frame
    187   // request.
    188   virtual int SendKeyFrame(const int video_channel) = 0;
    189 
    190   // This function makes the decoder wait for a key frame before starting to
    191   // decode the incoming video stream.
    192   virtual int WaitForFirstKeyFrame(const int video_channel,
    193                                    const bool wait) = 0;
    194 
    195   // Enables recording of debugging information.
    196   virtual int StartDebugRecording(int video_channel,
    197                                   const char* file_name_utf8) = 0;
    198   // Disables recording of debugging information.
    199   virtual int StopDebugRecording(int video_channel) = 0;
    200 
    201   // Lets the sender suspend video when the rate drops below
    202   // |threshold_bps|, and turns back on when the rate goes back up above
    203   // |threshold_bps| + |window_bps|.
    204   // This is under development; not tested.
    205   virtual void SuspendBelowMinBitrate(int video_channel) = 0;
    206 
    207   // TODO(holmer): Remove this default implementation when possible.
    208   virtual bool GetSendSideDelay(int video_channel, int* avg_delay_ms,
    209                                 int* max_delay_ms) const { return false; }
    210 
    211  protected:
    212   ViECodec() {}
    213   virtual ~ViECodec() {}
    214 };
    215 
    216 }  // namespace webrtc
    217 
    218 #endif  // WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_CODEC_H_
    219