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
38namespace webrtc {
39
40class RtpReceiver;
41class RtpRtcp;
42class VoiceEngine;
43
44class WEBRTC_DLLEXPORT VoEVideoSync {
45 public:
46  // Factory for the VoEVideoSync sub-API. Increases an internal
47  // reference counter if successful. Returns NULL if the API is not
48  // supported or if construction fails.
49  static VoEVideoSync* GetInterface(VoiceEngine* voiceEngine);
50
51  // Releases the VoEVideoSync sub-API and decreases an internal
52  // reference counter. Returns the new reference count. This value should
53  // be zero for all sub-API:s before the VoiceEngine object can be safely
54  // deleted.
55  virtual int Release() = 0;
56
57  // Gets the current sound card buffer size (playout delay).
58  virtual int GetPlayoutBufferSize(int& buffer_ms) = 0;
59
60  // Sets a minimum target delay for the jitter buffer. This delay is
61  // maintained by the jitter buffer, unless channel condition (jitter in
62  // inter-arrival times) dictates a higher required delay. The overall
63  // jitter buffer delay is max of |delay_ms| and the latency that NetEq
64  // computes based on inter-arrival times and its playout mode.
65  virtual int SetMinimumPlayoutDelay(int channel, int delay_ms) = 0;
66
67  // Gets the |jitter_buffer_delay_ms| (including the algorithmic delay), and
68  // the |playout_buffer_delay_ms| for a specified |channel|.
69  virtual int GetDelayEstimate(int channel,
70                               int* jitter_buffer_delay_ms,
71                               int* playout_buffer_delay_ms) = 0;
72
73  // Returns the least required jitter buffer delay. This is computed by the
74  // the jitter buffer based on the inter-arrival time of RTP packets and
75  // playout mode. NetEq maintains this latency unless a higher value is
76  // requested by calling SetMinimumPlayoutDelay().
77  virtual int GetLeastRequiredDelayMs(int channel) const = 0;
78
79  // Manual initialization of the RTP timestamp.
80  virtual int SetInitTimestamp(int channel, unsigned int timestamp) = 0;
81
82  // Manual initialization of the RTP sequence number.
83  virtual int SetInitSequenceNumber(int channel, short sequenceNumber) = 0;
84
85  // Get the received RTP timestamp
86  virtual int GetPlayoutTimestamp(int channel, unsigned int& timestamp) = 0;
87
88  virtual int GetRtpRtcp(int channel,
89                         RtpRtcp** rtpRtcpModule,
90                         RtpReceiver** rtp_receiver) = 0;
91
92 protected:
93  VoEVideoSync() {}
94  virtual ~VoEVideoSync() {}
95};
96
97}  // namespace webrtc
98
99#endif  // #ifndef WEBRTC_VOICE_ENGINE_VOE_VIDEO_SYNC_H
100