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