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 //
13 //  - Enables full duplex VoIP sessions via RTP using G.711 (mu-Law or A-Law).
14 //  - Initialization and termination.
15 //  - Trace information on text files or via callbacks.
16 //  - Multi-channel support (mixing, sending to multiple destinations etc.).
17 //
18 // To support other codecs than G.711, the VoECodec sub-API must be utilized.
19 //
20 // Usage example, omitting error checking:
21 //
22 //  using namespace webrtc;
23 //  VoiceEngine* voe = VoiceEngine::Create();
24 //  VoEBase* base = VoEBase::GetInterface(voe);
25 //  base->Init();
26 //  int ch = base->CreateChannel();
27 //  base->StartPlayout(ch);
28 //  ...
29 //  base->DeleteChannel(ch);
30 //  base->Terminate();
31 //  base->Release();
32 //  VoiceEngine::Delete(voe);
33 //
34 #ifndef VOICE_ENGINE_VOE_BASE_H_
35 #define VOICE_ENGINE_VOE_BASE_H_
36 
37 #include "api/audio_codecs/audio_decoder_factory.h"
38 #include "common_types.h"  // NOLINT(build/include)
39 #include "modules/audio_coding/include/audio_coding_module.h"
40 #include "rtc_base/scoped_ref_ptr.h"
41 
42 namespace webrtc {
43 
44 class AudioDeviceModule;
45 class AudioProcessing;
46 class AudioTransport;
47 namespace voe {
48 class TransmitMixer;
49 }  // namespace voe
50 
51 // VoiceEngine
52 class WEBRTC_DLLEXPORT VoiceEngine {
53  public:
54   // Creates a VoiceEngine object, which can then be used to acquire
55   // sub-APIs. Returns NULL on failure.
56   static VoiceEngine* Create();
57 
58   // Deletes a created VoiceEngine object and releases the utilized resources.
59   // Note that if there are outstanding references held via other interfaces,
60   // the voice engine instance will not actually be deleted until those
61   // references have been released.
62   static bool Delete(VoiceEngine*& voiceEngine);
63 
64  protected:
VoiceEngine()65   VoiceEngine() {}
~VoiceEngine()66   ~VoiceEngine() {}
67 
68  private:
69   // VS 2015 (others?) gets confused by a baseclass with no vtbl, and
70   // static_cast<VoiceEngineImpl*>(mVoiceEngine) produces a bad ptr.  It
71   // might also be related to the total size of the object.
72 
73   // Add a virtual method to assuage the poor compiler.
DummyVS2015BugFix()74   virtual void DummyVS2015BugFix() {};
75 };
76 
77 // VoEBase
78 class WEBRTC_DLLEXPORT VoEBase {
79  public:
80   struct ChannelConfig {
81     AudioCodingModule::Config acm_config;
82     bool enable_voice_pacing = false;
83   };
84 
85   // Factory for the VoEBase sub-API. Increases an internal reference
86   // counter if successful. Returns NULL if the API is not supported or if
87   // construction fails.
88   static VoEBase* GetInterface(VoiceEngine* voiceEngine);
89 
90   // Releases the VoEBase sub-API and decreases an internal reference
91   // counter. Returns the new reference count. This value should be zero
92   // for all sub-APIs before the VoiceEngine object can be safely deleted.
93   virtual int Release() = 0;
94 
95   // Initializes all common parts of the VoiceEngine; e.g. all
96   // encoders/decoders, the sound card and core receiving components.
97   // This method also makes it possible to install some user-defined external
98   // modules:
99   // - The Audio Device Module (ADM) which implements all the audio layer
100   // functionality in a separate (reference counted) module.
101   // - The AudioProcessing module handles capture-side processing.
102   // - An AudioDecoderFactory - used to create audio decoders.
103   virtual int Init(
104       AudioDeviceModule* audio_device,
105       AudioProcessing* audio_processing,
106       const rtc::scoped_refptr<AudioDecoderFactory>& decoder_factory) = 0;
107 
108   // This method is WIP - DO NOT USE!
109   // Returns NULL before Init() is called.
110   virtual voe::TransmitMixer* transmit_mixer() = 0;
111 
112   // Terminates all VoiceEngine functions and releases allocated resources.
113   virtual void Terminate() = 0;
114 
115   // Creates a new channel and allocates the required resources for it.
116   // The second version accepts a |config| struct which includes an Audio Coding
117   // Module config and an option to enable voice pacing. Note that the
118   // decoder_factory member of the ACM config will be ignored (the decoder
119   // factory set through Init() will always be used).
120   // Returns channel ID or -1 in case of an error.
121   virtual int CreateChannel() = 0;
122   virtual int CreateChannel(const ChannelConfig& config) = 0;
123 
124   // Deletes an existing channel and releases the utilized resources.
125   // Returns -1 in case of an error, 0 otherwise.
126   virtual int DeleteChannel(int channel) = 0;
127 
128   // Starts forwarding the packets to the mixer/soundcard for a
129   // specified |channel|.
130   virtual int StartPlayout(int channel) = 0;
131 
132   // Stops forwarding the packets to the mixer/soundcard for a
133   // specified |channel|.
134   virtual int StopPlayout(int channel) = 0;
135 
136   // Starts sending packets to an already specified IP address and
137   // port number for a specified |channel|.
138   virtual int StartSend(int channel) = 0;
139 
140   // Stops sending packets from a specified |channel|.
141   virtual int StopSend(int channel) = 0;
142 
143   // Enable or disable playout to the underlying device. Takes precedence over
144   // StartPlayout. Though calls to StartPlayout are remembered; if
145   // SetPlayout(true) is called after StartPlayout, playout will be started.
146   //
147   // By default, playout is enabled.
148   virtual int SetPlayout(bool enabled) = 0;
149 
150   // Enable or disable recording (which drives sending of encoded audio packtes)
151   // from the underlying device. Takes precedence over StartSend. Though calls
152   // to StartSend are remembered; if SetRecording(true) is called after
153   // StartSend, recording will be started.
154   //
155   // By default, recording is enabled.
156   virtual int SetRecording(bool enabled) = 0;
157 
158   // TODO(xians): Make the interface pure virtual after libjingle
159   // implements the interface in its FakeWebRtcVoiceEngine.
audio_transport()160   virtual AudioTransport* audio_transport() { return NULL; }
161 
162  protected:
VoEBase()163   VoEBase() {}
~VoEBase()164   virtual ~VoEBase() {}
165 };
166 
167 }  // namespace webrtc
168 
169 #endif  //  VOICE_ENGINE_VOE_BASE_H_
170