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#ifndef MODULES_AUDIO_DEVICE_INCLUDE_AUDIO_DEVICE_H_
12#define MODULES_AUDIO_DEVICE_INCLUDE_AUDIO_DEVICE_H_
13
14#include "webrtc/modules/audio_device/include/audio_device_defines.h"
15#include "webrtc/modules/interface/module.h"
16
17namespace webrtc {
18
19class AudioDeviceModule : public RefCountedModule {
20 public:
21  enum ErrorCode {
22    kAdmErrNone = 0,
23    kAdmErrArgument = 1
24  };
25
26  enum AudioLayer {
27    kPlatformDefaultAudio = 0,
28    kWindowsWaveAudio = 1,
29    kWindowsCoreAudio = 2,
30    kLinuxAlsaAudio = 3,
31    kLinuxPulseAudio = 4,
32    kDummyAudio = 5
33  };
34
35  enum WindowsDeviceType {
36    kDefaultCommunicationDevice = -1,
37    kDefaultDevice = -2
38  };
39
40  enum BufferType {
41    kFixedBufferSize  = 0,
42    kAdaptiveBufferSize = 1
43  };
44
45  enum ChannelType {
46    kChannelLeft = 0,
47    kChannelRight = 1,
48    kChannelBoth = 2
49  };
50
51 public:
52  // Retrieve the currently utilized audio layer
53  virtual int32_t ActiveAudioLayer(AudioLayer* audioLayer) const = 0;
54
55  // Error handling
56  virtual ErrorCode LastError() const = 0;
57  virtual int32_t RegisterEventObserver(AudioDeviceObserver* eventCallback) = 0;
58
59  // Full-duplex transportation of PCM audio
60  virtual int32_t RegisterAudioCallback(AudioTransport* audioCallback) = 0;
61
62  // Main initialization and termination
63  virtual int32_t Init() = 0;
64  virtual int32_t Terminate() = 0;
65  virtual bool Initialized() const = 0;
66
67  // Device enumeration
68  virtual int16_t PlayoutDevices() = 0;
69  virtual int16_t RecordingDevices() = 0;
70  virtual int32_t PlayoutDeviceName(uint16_t index,
71                                    char name[kAdmMaxDeviceNameSize],
72                                    char guid[kAdmMaxGuidSize]) = 0;
73  virtual int32_t RecordingDeviceName(uint16_t index,
74                                      char name[kAdmMaxDeviceNameSize],
75                                      char guid[kAdmMaxGuidSize]) = 0;
76
77  // Device selection
78  virtual int32_t SetPlayoutDevice(uint16_t index) = 0;
79  virtual int32_t SetPlayoutDevice(WindowsDeviceType device) = 0;
80  virtual int32_t SetRecordingDevice(uint16_t index) = 0;
81  virtual int32_t SetRecordingDevice(WindowsDeviceType device) = 0;
82
83  // Audio transport initialization
84  virtual int32_t PlayoutIsAvailable(bool* available) = 0;
85  virtual int32_t InitPlayout() = 0;
86  virtual bool PlayoutIsInitialized() const = 0;
87  virtual int32_t RecordingIsAvailable(bool* available) = 0;
88  virtual int32_t InitRecording() = 0;
89  virtual bool RecordingIsInitialized() const = 0;
90
91  // Audio transport control
92  virtual int32_t StartPlayout() = 0;
93  virtual int32_t StopPlayout() = 0;
94  virtual bool Playing() const = 0;
95  virtual int32_t StartRecording() = 0;
96  virtual int32_t StopRecording() = 0;
97  virtual bool Recording() const = 0;
98
99  // Microphone Automatic Gain Control (AGC)
100  virtual int32_t SetAGC(bool enable) = 0;
101  virtual bool AGC() const = 0;
102
103  // Volume control based on the Windows Wave API (Windows only)
104  virtual int32_t SetWaveOutVolume(uint16_t volumeLeft,
105                                   uint16_t volumeRight) = 0;
106  virtual int32_t WaveOutVolume(uint16_t* volumeLeft,
107                                uint16_t* volumeRight) const = 0;
108
109  // Audio mixer initialization
110  virtual int32_t InitSpeaker() = 0;
111  virtual bool SpeakerIsInitialized() const = 0;
112  virtual int32_t InitMicrophone() = 0;
113  virtual bool MicrophoneIsInitialized() const = 0;
114
115  // Speaker volume controls
116  virtual int32_t SpeakerVolumeIsAvailable(bool* available) = 0;
117  virtual int32_t SetSpeakerVolume(uint32_t volume) = 0;
118  virtual int32_t SpeakerVolume(uint32_t* volume) const = 0;
119  virtual int32_t MaxSpeakerVolume(uint32_t* maxVolume) const = 0;
120  virtual int32_t MinSpeakerVolume(uint32_t* minVolume) const = 0;
121  virtual int32_t SpeakerVolumeStepSize(uint16_t* stepSize) const = 0;
122
123  // Microphone volume controls
124  virtual int32_t MicrophoneVolumeIsAvailable(bool* available) = 0;
125  virtual int32_t SetMicrophoneVolume(uint32_t volume) = 0;
126  virtual int32_t MicrophoneVolume(uint32_t* volume) const = 0;
127  virtual int32_t MaxMicrophoneVolume(uint32_t* maxVolume) const = 0;
128  virtual int32_t MinMicrophoneVolume(uint32_t* minVolume) const = 0;
129  virtual int32_t MicrophoneVolumeStepSize(uint16_t* stepSize) const = 0;
130
131  // Speaker mute control
132  virtual int32_t SpeakerMuteIsAvailable(bool* available) = 0;
133  virtual int32_t SetSpeakerMute(bool enable) = 0;
134  virtual int32_t SpeakerMute(bool* enabled) const = 0;
135
136  // Microphone mute control
137  virtual int32_t MicrophoneMuteIsAvailable(bool* available) = 0;
138  virtual int32_t SetMicrophoneMute(bool enable) = 0;
139  virtual int32_t MicrophoneMute(bool* enabled) const = 0;
140
141  // Microphone boost control
142  virtual int32_t MicrophoneBoostIsAvailable(bool* available) = 0;
143  virtual int32_t SetMicrophoneBoost(bool enable) = 0;
144  virtual int32_t MicrophoneBoost(bool* enabled) const = 0;
145
146  // Stereo support
147  virtual int32_t StereoPlayoutIsAvailable(bool* available) const = 0;
148  virtual int32_t SetStereoPlayout(bool enable) = 0;
149  virtual int32_t StereoPlayout(bool* enabled) const = 0;
150  virtual int32_t StereoRecordingIsAvailable(bool* available) const = 0;
151  virtual int32_t SetStereoRecording(bool enable) = 0;
152  virtual int32_t StereoRecording(bool* enabled) const = 0;
153  virtual int32_t SetRecordingChannel(const ChannelType channel) = 0;
154  virtual int32_t RecordingChannel(ChannelType* channel) const = 0;
155
156  // Delay information and control
157  virtual int32_t SetPlayoutBuffer(const BufferType type,
158                                   uint16_t sizeMS = 0) = 0;
159  virtual int32_t PlayoutBuffer(BufferType* type, uint16_t* sizeMS) const = 0;
160  virtual int32_t PlayoutDelay(uint16_t* delayMS) const = 0;
161  virtual int32_t RecordingDelay(uint16_t* delayMS) const = 0;
162
163  // CPU load
164  virtual int32_t CPULoad(uint16_t* load) const = 0;
165
166  // Recording of raw PCM data
167  virtual int32_t StartRawOutputFileRecording(
168      const char pcmFileNameUTF8[kAdmMaxFileNameSize]) = 0;
169  virtual int32_t StopRawOutputFileRecording() = 0;
170  virtual int32_t StartRawInputFileRecording(
171      const char pcmFileNameUTF8[kAdmMaxFileNameSize]) = 0;
172  virtual int32_t StopRawInputFileRecording() = 0;
173
174  // Native sample rate controls (samples/sec)
175  virtual int32_t SetRecordingSampleRate(const uint32_t samplesPerSec) = 0;
176  virtual int32_t RecordingSampleRate(uint32_t* samplesPerSec) const = 0;
177  virtual int32_t SetPlayoutSampleRate(const uint32_t samplesPerSec) = 0;
178  virtual int32_t PlayoutSampleRate(uint32_t* samplesPerSec) const = 0;
179
180  // Mobile device specific functions
181  virtual int32_t ResetAudioDevice() = 0;
182  virtual int32_t SetLoudspeakerStatus(bool enable) = 0;
183  virtual int32_t GetLoudspeakerStatus(bool* enabled) const = 0;
184
185  // *Experimental - not recommended for use.*
186  // Enables the Windows Core Audio built-in AEC. Fails on other platforms.
187  //
188  // Must be called before InitRecording(). When enabled:
189  // 1. StartPlayout() must be called before StartRecording().
190  // 2. StopRecording() should be called before StopPlayout().
191  //    The reverse order may cause garbage audio to be rendered or the
192  //    capture side to halt until StopRecording() is called.
193  virtual int32_t EnableBuiltInAEC(bool enable) { return -1; }
194  virtual bool BuiltInAECIsEnabled() const { return false; }
195
196 protected:
197  virtual ~AudioDeviceModule() {};
198};
199
200AudioDeviceModule* CreateAudioDeviceModule(
201    int32_t id, AudioDeviceModule::AudioLayer audioLayer);
202
203}  // namespace webrtc
204
205#endif  // MODULES_AUDIO_DEVICE_INCLUDE_AUDIO_DEVICE_H_
206