webrtc/modules/video_coding/include/video_coding.h

/*
 *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
 *
 *  Use of this source code is governed by a BSD-style license
 *  that can be found in the LICENSE file in the root of the source
 *  tree. An additional intellectual property rights grant can be found
 *  in the file PATENTS.  All contributing project authors may
 *  be found in the AUTHORS file in the root of the source tree.
 */

#ifndef WEBRTC_MODULES_VIDEO_CODING_INCLUDE_VIDEO_CODING_H_
#define WEBRTC_MODULES_VIDEO_CODING_INCLUDE_VIDEO_CODING_H_

#if defined(WEBRTC_WIN)
// This is a workaround on Windows due to the fact that some Windows
// headers define CreateEvent as a macro to either CreateEventW or CreateEventA.
// This can cause problems since we use that name as well and could
// declare them as one thing here whereas in another place a windows header
// may have been included and then implementing CreateEvent() causes compilation
// errors.  So for consistency, we include the main windows header here.
#include <windows.h>
#endif

#include "webrtc/modules/include/module.h"
#include "webrtc/modules/include/module_common_types.h"
#include "webrtc/modules/video_coding/include/video_coding_defines.h"
#include "webrtc/system_wrappers/include/event_wrapper.h"
#include "webrtc/video_frame.h"

namespace webrtc {

class Clock;
class EncodedImageCallback;
class VideoEncoder;
class VideoDecoder;
struct CodecSpecificInfo;

class EventFactory {
 public:
  virtual ~EventFactory() {}

  virtual EventWrapper* CreateEvent() = 0;
};

class EventFactoryImpl : public EventFactory {
 public:
  virtual ~EventFactoryImpl() {}

  virtual EventWrapper* CreateEvent() { return EventWrapper::Create(); }
};

// Used to indicate which decode with errors mode should be used.
enum VCMDecodeErrorMode {
  kNoErrors,         // Never decode with errors. Video will freeze
                     // if nack is disabled.
  kSelectiveErrors,  // Frames that are determined decodable in
                     // VCMSessionInfo may be decoded with missing
                     // packets. As not all incomplete frames will be
                     // decodable, video will freeze if nack is disabled.
  kWithErrors        // Release frames as needed. Errors may be
                     // introduced as some encoded frames may not be
                     // complete.
};

class VideoCodingModule : public Module {
 public:
  enum SenderNackMode { kNackNone, kNackAll, kNackSelective };

  enum ReceiverRobustness { kNone, kHardNack, kSoftNack, kReferenceSelection };

  static VideoCodingModule* Create(
      Clock* clock,
      VideoEncoderRateObserver* encoder_rate_observer,
      VCMQMSettingsCallback* qm_settings_callback);

  static VideoCodingModule* Create(Clock* clock, EventFactory* event_factory);

  static void Destroy(VideoCodingModule* module);

  // Get number of supported codecs
  //
  // Return value     : Number of supported codecs
  static uint8_t NumberOfCodecs();

  // Get supported codec settings with using id
  //
  // Input:
  //      - listId         : Id or index of the codec to look up
  //      - codec          : Memory where the codec settings will be stored
  //
  // Return value     : VCM_OK,              on success
  //                    VCM_PARAMETER_ERROR  if codec not supported or id too
  //                    high
  static int32_t Codec(const uint8_t listId, VideoCodec* codec);

  // Get supported codec settings using codec type
  //
  // Input:
  //      - codecType      : The codec type to get settings for
  //      - codec          : Memory where the codec settings will be stored
  //
  // Return value     : VCM_OK,              on success
  //                    VCM_PARAMETER_ERROR  if codec not supported
  static int32_t Codec(VideoCodecType codecType, VideoCodec* codec);

  /*
  *   Sender
  */

  // Registers a codec to be used for encoding. Calling this
  // API multiple times overwrites any previously registered codecs.
  //
  // NOTE: Must be called on the thread that constructed the VCM instance.
  //
  // Input:
  //      - sendCodec      : Settings for the codec to be registered.
  //      - numberOfCores  : The number of cores the codec is allowed
  //                         to use.
  //      - maxPayloadSize : The maximum size each payload is allowed
  //                                to have. Usually MTU - overhead.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t RegisterSendCodec(const VideoCodec* sendCodec,
                                    uint32_t numberOfCores,
                                    uint32_t maxPayloadSize) = 0;

  // Get the current send codec in use.
  //
  // If a codec has not been set yet, the |id| property of the return value
  // will be 0 and |name| empty.
  //
  // NOTE: This method intentionally does not hold locks and minimizes data
  // copying.  It must be called on the thread where the VCM was constructed.
  virtual const VideoCodec& GetSendCodec() const = 0;

  // DEPRECATED: Use GetSendCodec() instead.
  //
  // API to get the current send codec in use.
  //
  // Input:
  //      - currentSendCodec : Address where the sendCodec will be written.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  //
  // NOTE: The returned codec information is not guaranteed to be current when
  // the call returns.  This method acquires a lock that is aligned with
  // video encoding, so it should be assumed to be allowed to block for
  // several milliseconds.
  virtual int32_t SendCodec(VideoCodec* currentSendCodec) const = 0;

  // DEPRECATED: Use GetSendCodec() instead.
  //
  // API to get the current send codec type
  //
  // Return value      : Codec type, on success.
  //                     kVideoCodecUnknown, on error or if no send codec is set
  // NOTE: Same notes apply as for SendCodec() above.
  virtual VideoCodecType SendCodec() const = 0;

  // Register an external encoder object. This can not be used together with
  // external decoder callbacks.
  //
  // Input:
  //      - externalEncoder : Encoder object to be used for encoding frames
  //      inserted
  //                          with the AddVideoFrame API.
  //      - payloadType     : The payload type bound which this encoder is bound
  //      to.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  // TODO(pbos): Remove return type when unused elsewhere.
  virtual int32_t RegisterExternalEncoder(VideoEncoder* externalEncoder,
                                          uint8_t payloadType,
                                          bool internalSource = false) = 0;

  // API to get currently configured encoder target bitrate in bits/s.
  //
  // Return value      : 0,   on success.
  //                     < 0, on error.
  virtual int Bitrate(unsigned int* bitrate) const = 0;

  // API to get currently configured encoder target frame rate.
  //
  // Return value      : 0,   on success.
  //                     < 0, on error.
  virtual int FrameRate(unsigned int* framerate) const = 0;

  // Sets the parameters describing the send channel. These parameters are
  // inputs to the
  // Media Optimization inside the VCM and also specifies the target bit rate
  // for the
  // encoder. Bit rate used by NACK should already be compensated for by the
  // user.
  //
  // Input:
  //      - target_bitrate        : The target bitrate for VCM in bits/s.
  //      - lossRate              : Fractions of lost packets the past second.
  //                                (loss rate in percent = 100 * packetLoss /
  //                                255)
  //      - rtt                   : Current round-trip time in ms.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,         on error.
  virtual int32_t SetChannelParameters(uint32_t target_bitrate,
                                       uint8_t lossRate,
                                       int64_t rtt) = 0;

  // Sets the parameters describing the receive channel. These parameters are
  // inputs to the
  // Media Optimization inside the VCM.
  //
  // Input:
  //      - rtt                   : Current round-trip time in ms.
  //                                with the most amount available bandwidth in
  //                                a conference
  //                                scenario
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t SetReceiveChannelParameters(int64_t rtt) = 0;

  // Register a transport callback which will be called to deliver the encoded
  // data and
  // side information.
  //
  // Input:
  //      - transport  : The callback object to register.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t RegisterTransportCallback(
      VCMPacketizationCallback* transport) = 0;

  // Register video output information callback which will be called to deliver
  // information
  // about the video stream produced by the encoder, for instance the average
  // frame rate and
  // bit rate.
  //
  // Input:
  //      - outputInformation  : The callback object to register.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t RegisterSendStatisticsCallback(
      VCMSendStatisticsCallback* sendStats) = 0;

  // Register a video protection callback which will be called to deliver
  // the requested FEC rate and NACK status (on/off).
  //
  // Input:
  //      - protection  : The callback object to register.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t RegisterProtectionCallback(
      VCMProtectionCallback* protection) = 0;

  // Enable or disable a video protection method.
  //
  // Input:
  //      - videoProtection  : The method to enable or disable.
  //      - enable           : True if the method should be enabled, false if
  //                           it should be disabled.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t SetVideoProtection(VCMVideoProtection videoProtection,
                                     bool enable) = 0;

  // Add one raw video frame to the encoder. This function does all the
  // necessary
  // processing, then decides what frame type to encode, or if the frame should
  // be
  // dropped. If the frame should be encoded it passes the frame to the encoder
  // before it returns.
  //
  // Input:
  //      - videoFrame        : Video frame to encode.
  //      - codecSpecificInfo : Extra codec information, e.g., pre-parsed
  //      in-band signaling.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t AddVideoFrame(
      const VideoFrame& videoFrame,
      const VideoContentMetrics* contentMetrics = NULL,
      const CodecSpecificInfo* codecSpecificInfo = NULL) = 0;

  // Next frame encoded should be an intra frame (keyframe).
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t IntraFrameRequest(int stream_index) = 0;

  // Frame Dropper enable. Can be used to disable the frame dropping when the
  // encoder
  // over-uses its bit rate. This API is designed to be used when the encoded
  // frames
  // are supposed to be stored to an AVI file, or when the I420 codec is used
  // and the
  // target bit rate shouldn't affect the frame rate.
  //
  // Input:
  //      - enable            : True to enable the setting, false to disable it.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t EnableFrameDropper(bool enable) = 0;

  /*
  *   Receiver
  */

  // Register possible receive codecs, can be called multiple times for
  // different codecs.
  // The module will automatically switch between registered codecs depending on
  // the
  // payload type of incoming frames. The actual decoder will be created when
  // needed.
  //
  // Input:
  //      - receiveCodec      : Settings for the codec to be registered.
  //      - numberOfCores     : Number of CPU cores that the decoder is allowed
  //      to use.
  //      - requireKeyFrame   : Set this to true if you don't want any delta
  //      frames
  //                            to be decoded until the first key frame has been
  //                            decoded.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t RegisterReceiveCodec(const VideoCodec* receiveCodec,
                                       int32_t numberOfCores,
                                       bool requireKeyFrame = false) = 0;

  // Register an externally defined decoder/renderer object. Can be a decoder
  // only or a
  // decoder coupled with a renderer. Note that RegisterReceiveCodec must be
  // called to
  // be used for decoding incoming streams.
  //
  // Input:
  //      - externalDecoder        : The external decoder/renderer object.
  //      - payloadType            : The payload type which this decoder should
  //      be
  //                                 registered to.
  //
  virtual void RegisterExternalDecoder(VideoDecoder* externalDecoder,
                                       uint8_t payloadType) = 0;

  // Register a receive callback. Will be called whenever there is a new frame
  // ready
  // for rendering.
  //
  // Input:
  //      - receiveCallback        : The callback object to be used by the
  //      module when a
  //                                 frame is ready for rendering.
  //                                 De-register with a NULL pointer.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t RegisterReceiveCallback(
      VCMReceiveCallback* receiveCallback) = 0;

  // Register a receive statistics callback which will be called to deliver
  // information
  // about the video stream received by the receiving side of the VCM, for
  // instance the
  // average frame rate and bit rate.
  //
  // Input:
  //      - receiveStats  : The callback object to register.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t RegisterReceiveStatisticsCallback(
      VCMReceiveStatisticsCallback* receiveStats) = 0;

  // Register a decoder timing callback which will be called to deliver
  // information about the timing of the decoder in the receiving side of the
  // VCM, for instance the current and maximum frame decode latency.
  //
  // Input:
  //      - decoderTiming  : The callback object to register.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t RegisterDecoderTimingCallback(
      VCMDecoderTimingCallback* decoderTiming) = 0;

  // Register a frame type request callback. This callback will be called when
  // the
  // module needs to request specific frame types from the send side.
  //
  // Input:
  //      - frameTypeCallback      : The callback object to be used by the
  //      module when
  //                                 requesting a specific type of frame from
  //                                 the send side.
  //                                 De-register with a NULL pointer.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t RegisterFrameTypeCallback(
      VCMFrameTypeCallback* frameTypeCallback) = 0;

  // Registers a callback which is called whenever the receive side of the VCM
  // encounters holes in the packet sequence and needs packets to be
  // retransmitted.
  //
  // Input:
  //              - callback      : The callback to be registered in the VCM.
  //
  // Return value     : VCM_OK,     on success.
  //                    <0,         on error.
  virtual int32_t RegisterPacketRequestCallback(
      VCMPacketRequestCallback* callback) = 0;

  // Waits for the next frame in the jitter buffer to become complete
  // (waits no longer than maxWaitTimeMs), then passes it to the decoder for
  // decoding.
  // Should be called as often as possible to get the most out of the decoder.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t Decode(uint16_t maxWaitTimeMs = 200) = 0;

  // Registers a callback which conveys the size of the render buffer.
  virtual int RegisterRenderBufferSizeCallback(
      VCMRenderBufferSizeCallback* callback) = 0;

  // Reset the decoder state to the initial state.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t ResetDecoder() = 0;

  // API to get the codec which is currently used for decoding by the module.
  //
  // Input:
  //      - currentReceiveCodec      : Settings for the codec to be registered.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t ReceiveCodec(VideoCodec* currentReceiveCodec) const = 0;

  // API to get the codec type currently used for decoding by the module.
  //
  // Return value      : codecy type,            on success.
  //                     kVideoCodecUnknown, on error or if no receive codec is
  //                     registered
  virtual VideoCodecType ReceiveCodec() const = 0;

  // Insert a parsed packet into the receiver side of the module. Will be placed
  // in the
  // jitter buffer waiting for the frame to become complete. Returns as soon as
  // the packet
  // has been placed in the jitter buffer.
  //
  // Input:
  //      - incomingPayload      : Payload of the packet.
  //      - payloadLength        : Length of the payload.
  //      - rtpInfo              : The parsed header.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t IncomingPacket(const uint8_t* incomingPayload,
                                 size_t payloadLength,
                                 const WebRtcRTPHeader& rtpInfo) = 0;

  // Minimum playout delay (Used for lip-sync). This is the minimum delay
  // required
  // to sync with audio. Not included in  VideoCodingModule::Delay()
  // Defaults to 0 ms.
  //
  // Input:
  //      - minPlayoutDelayMs   : Additional delay in ms.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t SetMinimumPlayoutDelay(uint32_t minPlayoutDelayMs) = 0;

  // Set the time required by the renderer to render a frame.
  //
  // Input:
  //      - timeMS        : The time in ms required by the renderer to render a
  //      frame.
  //
  // Return value      : VCM_OK, on success.
  //                     < 0,    on error.
  virtual int32_t SetRenderDelay(uint32_t timeMS) = 0;

  // The total delay desired by the VCM. Can be less than the minimum
  // delay set with SetMinimumPlayoutDelay.
  //
  // Return value      : Total delay in ms, on success.
  //                     < 0,               on error.
  virtual int32_t Delay() const = 0;

  // Returns the number of packets discarded by the jitter buffer due to being
  // too late. This can include duplicated packets which arrived after the
  // frame was sent to the decoder. Therefore packets which were prematurely
  // NACKed will be counted.
  virtual uint32_t DiscardedPackets() const = 0;

  // Robustness APIs

  // Set the receiver robustness mode. The mode decides how the receiver
  // responds to losses in the stream. The type of counter-measure (soft or
  // hard NACK, dual decoder, RPS, etc.) is selected through the
  // robustnessMode parameter. The errorMode parameter decides if it is
  // allowed to display frames corrupted by losses. Note that not all
  // combinations of the two parameters are feasible. An error will be
  // returned for invalid combinations.
  // Input:
  //      - robustnessMode : selected robustness mode.
  //      - errorMode      : selected error mode.
  //
  // Return value      : VCM_OK, on success;
  //                     < 0, on error.
  virtual int SetReceiverRobustnessMode(ReceiverRobustness robustnessMode,
                                        VCMDecodeErrorMode errorMode) = 0;

  // Set the decode error mode. The mode decides which errors (if any) are
  // allowed in decodable frames. Note that setting decode_error_mode to
  // anything other than kWithErrors without enabling nack will cause
  // long-term freezes (resulting from frequent key frame requests) if
  // packet loss occurs.
  virtual void SetDecodeErrorMode(VCMDecodeErrorMode decode_error_mode) = 0;

  // Sets the maximum number of sequence numbers that we are allowed to NACK
  // and the oldest sequence number that we will consider to NACK. If a
  // sequence number older than |max_packet_age_to_nack| is missing
  // a key frame will be requested. A key frame will also be requested if the
  // time of incomplete or non-continuous frames in the jitter buffer is above
  // |max_incomplete_time_ms|.
  virtual void SetNackSettings(size_t max_nack_list_size,
                               int max_packet_age_to_nack,
                               int max_incomplete_time_ms) = 0;

  // Setting a desired delay to the VCM receiver. Video rendering will be
  // delayed by at least desired_delay_ms.
  virtual int SetMinReceiverDelay(int desired_delay_ms) = 0;

  // Lets the sender suspend video when the rate drops below
  // |threshold_bps|, and turns back on when the rate goes back up above
  // |threshold_bps| + |window_bps|.
  virtual void SuspendBelowMinBitrate() = 0;

  // Returns true if SuspendBelowMinBitrate is engaged and the video has been
  // suspended due to bandwidth limitations; otherwise false.
  virtual bool VideoSuspended() const = 0;

  virtual void RegisterPreDecodeImageCallback(
      EncodedImageCallback* observer) = 0;
  virtual void RegisterPostEncodeImageCallback(
      EncodedImageCallback* post_encode_callback) = 0;
  // Releases pending decode calls, permitting faster thread shutdown.
  virtual void TriggerDecoderShutdown() = 0;
};

}  // namespace webrtc

#endif  // WEBRTC_MODULES_VIDEO_CODING_INCLUDE_VIDEO_CODING_H_