Home | History | Annotate | Download | only in include 
      1 /*
      2  *  Copyright (c) 2011 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 //
     13 //  - RTP header modification (time stamp and sequence number fields).
     14 //  - Playout delay tuning to synchronize the voice with video.
     15 //  - Playout delay monitoring.
     16 //
     17 // Usage example, omitting error checking:
     18 //
     19 //  using namespace webrtc;
     20 //  VoiceEngine* voe = VoiceEngine::Create();
     21 //  VoEBase* base = VoEBase::GetInterface(voe);
     22 //  VoEVideoSync* vsync  = VoEVideoSync::GetInterface(voe);
     23 //  base->Init();
     24 //  ...
     25 //  int buffer_ms(0);
     26 //  vsync->GetPlayoutBufferSize(buffer_ms);
     27 //  ...
     28 //  base->Terminate();
     29 //  base->Release();
     30 //  vsync->Release();
     31 //  VoiceEngine::Delete(voe);
     32 //
     33 #ifndef WEBRTC_VOICE_ENGINE_VOE_VIDEO_SYNC_H
     34 #define WEBRTC_VOICE_ENGINE_VOE_VIDEO_SYNC_H
     35 
     36 #include "webrtc/common_types.h"
     37 
     38 namespace webrtc {
     39 
     40 class RtpReceiver;
     41 class RtpRtcp;
     42 class VoiceEngine;
     43 
     44 class WEBRTC_DLLEXPORT VoEVideoSync
     45 {
     46 public:
     47     // Factory for the VoEVideoSync sub-API. Increases an internal
     48     // reference counter if successful. Returns NULL if the API is not
     49     // supported or if construction fails.
     50     static VoEVideoSync* GetInterface(VoiceEngine* voiceEngine);
     51 
     52     // Releases the VoEVideoSync sub-API and decreases an internal
     53     // reference counter. Returns the new reference count. This value should
     54     // be zero for all sub-API:s before the VoiceEngine object can be safely
     55     // deleted.
     56     virtual int Release() = 0;
     57 
     58     // Gets the current sound card buffer size (playout delay).
     59     virtual int GetPlayoutBufferSize(int& buffer_ms) = 0;
     60 
     61     // Sets a minimum target delay for the jitter buffer. This delay is
     62     // maintained by the jitter buffer, unless channel condition (jitter in
     63     // inter-arrival times) dictates a higher required delay. The overall
     64     // jitter buffer delay is max of |delay_ms| and the latency that NetEq
     65     // computes based on inter-arrival times and its playout mode.
     66     virtual int SetMinimumPlayoutDelay(int channel, int delay_ms) = 0;
     67 
     68     // Sets an initial delay for the playout jitter buffer. The playout of the
     69     // audio is delayed by |delay_ms| in milliseconds. Thereafter, the delay is
     70     // maintained, unless NetEq's internal mechanism requires a higher latency.
     71     // Such a latency is computed based on inter-arrival times and NetEq's
     72     // playout mode.
     73     virtual int SetInitialPlayoutDelay(int channel, int delay_ms) = 0;
     74 
     75     // Gets the |jitter_buffer_delay_ms| (including the algorithmic delay), and
     76     // the |playout_buffer_delay_ms| for a specified |channel|.
     77     virtual int GetDelayEstimate(int channel,
     78                                  int* jitter_buffer_delay_ms,
     79                                  int* playout_buffer_delay_ms) = 0;
     80 
     81     // Returns the least required jitter buffer delay. This is computed by the
     82     // the jitter buffer based on the inter-arrival time of RTP packets and
     83     // playout mode. NetEq maintains this latency unless a higher value is
     84     // requested by calling SetMinimumPlayoutDelay().
     85     virtual int GetLeastRequiredDelayMs(int channel) const = 0;
     86 
     87     // Manual initialization of the RTP timestamp.
     88     virtual int SetInitTimestamp(int channel, unsigned int timestamp) = 0;
     89 
     90     // Manual initialization of the RTP sequence number.
     91     virtual int SetInitSequenceNumber(int channel, short sequenceNumber) = 0;
     92 
     93     // Get the received RTP timestamp
     94     virtual int GetPlayoutTimestamp(int channel, unsigned int& timestamp) = 0;
     95 
     96     virtual int GetRtpRtcp (int channel, RtpRtcp** rtpRtcpModule,
     97                             RtpReceiver** rtp_receiver) = 0;
     98 
     99 protected:
    100     VoEVideoSync() { }
    101     virtual ~VoEVideoSync() { }
    102 };
    103 
    104 }  // namespace webrtc
    105 
    106 #endif  // #ifndef WEBRTC_VOICE_ENGINE_VOE_VIDEO_SYNC_H
    107