webrtc/modules/video_coding/main/interface/video_coding.h - src - Git at Google

 /*
  *  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_INTERFACE_VIDEO_CODING_H_
 #define WEBRTC_MODULES_INTERFACE_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/interface/module.h"
 #include "webrtc/modules/interface/module_common_types.h"
 #include "webrtc/modules/video_coding/main/interface/video_coding_defines.h"
 #include "webrtc/system_wrappers/interface/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.
     virtual int32_t RegisterExternalEncoder(VideoEncoder* externalEncoder,
                                             uint8_t payloadType,
                                             bool internalSource = false) = 0;

     // API to get codec config parameters to be sent out-of-band to a receiver.
     //
     // Input:
     //      - buffer          : Memory where the codec config parameters should be written.
     //      - size            : Size of the memory available.
     //
     // Return value      : Number of bytes written, on success.
     //                     < 0,                     on error.
     virtual int32_t CodecConfigParameters(uint8_t* buffer, int32_t size) = 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;

     // Sent frame counters
     virtual int32_t SentFrameCount(VCMFrameCount& frameCount) const = 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.
     //      - internalRenderTiming   : True if the internal renderer (if any) of the decoder
     //                                 object can make sure to render at a given time in ms.
     //
     // Return value      : VCM_OK, on success.
     //                     < 0,         on error.
     virtual int32_t RegisterExternalDecoder(VideoDecoder* externalDecoder,
                                             uint8_t payloadType,
                                             bool internalRenderTiming) = 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_INTERFACE_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_INTERFACE_VIDEO_CODING_H_
	#define WEBRTC_MODULES_INTERFACE_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/interface/module.h"
	#include "webrtc/modules/interface/module_common_types.h"
	#include "webrtc/modules/video_coding/main/interface/video_coding_defines.h"
	#include "webrtc/system_wrappers/interface/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.
	virtual int32_t RegisterExternalEncoder(VideoEncoder* externalEncoder,
	uint8_t payloadType,
	bool internalSource = false) = 0;

	// API to get codec config parameters to be sent out-of-band to a receiver.
	//
	// Input:
	// - buffer : Memory where the codec config parameters should be written.
	// - size : Size of the memory available.
	//
	// Return value : Number of bytes written, on success.
	// < 0, on error.
	virtual int32_t CodecConfigParameters(uint8_t* buffer, int32_t size) = 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;

	// Sent frame counters
	virtual int32_t SentFrameCount(VCMFrameCount& frameCount) const = 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.
	// - internalRenderTiming : True if the internal renderer (if any) of the decoder
	// object can make sure to render at a given time in ms.
	//
	// Return value : VCM_OK, on success.
	// < 0, on error.
	virtual int32_t RegisterExternalDecoder(VideoDecoder* externalDecoder,
	uint8_t payloadType,
	bool internalRenderTiming) = 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_INTERFACE_VIDEO_CODING_H_