blob: 82e6e50fc8187152d5e67116ccaedb59a0f1fcee [file] [log] [blame]
niklase@google.com470e71d2011-07-07 08:21:25 +00001/*
andrew@webrtc.org648af742012-02-08 01:57:29 +00002 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
niklase@google.com470e71d2011-07-07 08:21:25 +00003 *
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
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +000011#ifndef WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AUDIO_PROCESSING_H_
12#define WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AUDIO_PROCESSING_H_
niklase@google.com470e71d2011-07-07 08:21:25 +000013
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +000014#include <stddef.h> // size_t
henrikg@webrtc.org863b5362013-12-06 16:05:17 +000015#include <stdio.h> // FILE
ajm@google.com22e65152011-07-18 18:03:01 +000016
andrew@webrtc.org61e596f2013-07-25 18:28:29 +000017#include "webrtc/common.h"
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +000018#include "webrtc/modules/interface/module.h"
19#include "webrtc/typedefs.h"
niklase@google.com470e71d2011-07-07 08:21:25 +000020
bjornv@webrtc.org91d11b32013-03-05 16:53:09 +000021struct AecCore;
22
niklase@google.com470e71d2011-07-07 08:21:25 +000023namespace webrtc {
24
25class AudioFrame;
26class EchoCancellation;
27class EchoControlMobile;
28class GainControl;
29class HighPassFilter;
30class LevelEstimator;
31class NoiseSuppression;
32class VoiceDetection;
33
andrew@webrtc.org6b1e2192013-09-25 23:46:20 +000034// Use to enable the delay correction feature. This now engages an extended
35// filter mode in the AEC, along with robustness measures around the reported
36// system delays. It comes with a significant increase in AEC complexity, but is
37// much more robust to unreliable reported delays.
38//
39// Detailed changes to the algorithm:
40// - The filter length is changed from 48 to 128 ms. This comes with tuning of
41// several parameters: i) filter adaptation stepsize and error threshold;
42// ii) non-linear processing smoothing and overdrive.
43// - Option to ignore the reported delays on platforms which we deem
44// sufficiently unreliable. See WEBRTC_UNTRUSTED_DELAY in echo_cancellation.c.
45// - Faster startup times by removing the excessive "startup phase" processing
46// of reported delays.
47// - Much more conservative adjustments to the far-end read pointer. We smooth
48// the delay difference more heavily, and back off from the difference more.
49// Adjustments force a readaptation of the filter, so they should be avoided
50// except when really necessary.
51struct DelayCorrection {
52 DelayCorrection() : enabled(false) {}
andrew@webrtc.orgc7c7a532014-01-29 04:57:25 +000053 explicit DelayCorrection(bool enabled) : enabled(enabled) {}
54 bool enabled;
55};
andrew@webrtc.org6b1e2192013-09-25 23:46:20 +000056
andrew@webrtc.orgc7c7a532014-01-29 04:57:25 +000057// Must be provided through AudioProcessing::Create(Confg&). It will have no
58// impact if used with AudioProcessing::SetExtraOptions().
59struct ExperimentalAgc {
60 ExperimentalAgc() : enabled(true) {}
61 explicit ExperimentalAgc(bool enabled) : enabled(enabled) {}
andrew@webrtc.org6b1e2192013-09-25 23:46:20 +000062 bool enabled;
63};
64
niklase@google.com470e71d2011-07-07 08:21:25 +000065// The Audio Processing Module (APM) provides a collection of voice processing
66// components designed for real-time communications software.
67//
68// APM operates on two audio streams on a frame-by-frame basis. Frames of the
69// primary stream, on which all processing is applied, are passed to
70// |ProcessStream()|. Frames of the reverse direction stream, which are used for
71// analysis by some components, are passed to |AnalyzeReverseStream()|. On the
72// client-side, this will typically be the near-end (capture) and far-end
73// (render) streams, respectively. APM should be placed in the signal chain as
74// close to the audio hardware abstraction layer (HAL) as possible.
75//
76// On the server-side, the reverse stream will normally not be used, with
77// processing occurring on each incoming stream.
78//
79// Component interfaces follow a similar pattern and are accessed through
80// corresponding getters in APM. All components are disabled at create-time,
81// with default settings that are recommended for most situations. New settings
82// can be applied without enabling a component. Enabling a component triggers
83// memory allocation and initialization to allow it to start processing the
84// streams.
85//
86// Thread safety is provided with the following assumptions to reduce locking
87// overhead:
88// 1. The stream getters and setters are called from the same thread as
89// ProcessStream(). More precisely, stream functions are never called
90// concurrently with ProcessStream().
91// 2. Parameter getters are never called concurrently with the corresponding
92// setter.
93//
94// APM accepts only 16-bit linear PCM audio data in frames of 10 ms. Multiple
95// channels should be interleaved.
96//
97// Usage example, omitting error checking:
98// AudioProcessing* apm = AudioProcessing::Create(0);
niklase@google.com470e71d2011-07-07 08:21:25 +000099//
100// apm->high_pass_filter()->Enable(true);
101//
102// apm->echo_cancellation()->enable_drift_compensation(false);
103// apm->echo_cancellation()->Enable(true);
104//
105// apm->noise_reduction()->set_level(kHighSuppression);
106// apm->noise_reduction()->Enable(true);
107//
108// apm->gain_control()->set_analog_level_limits(0, 255);
109// apm->gain_control()->set_mode(kAdaptiveAnalog);
110// apm->gain_control()->Enable(true);
111//
112// apm->voice_detection()->Enable(true);
113//
114// // Start a voice call...
115//
116// // ... Render frame arrives bound for the audio HAL ...
117// apm->AnalyzeReverseStream(render_frame);
118//
119// // ... Capture frame arrives from the audio HAL ...
120// // Call required set_stream_ functions.
121// apm->set_stream_delay_ms(delay_ms);
122// apm->gain_control()->set_stream_analog_level(analog_level);
123//
124// apm->ProcessStream(capture_frame);
125//
126// // Call required stream_ functions.
127// analog_level = apm->gain_control()->stream_analog_level();
128// has_voice = apm->stream_has_voice();
129//
130// // Repeate render and capture processing for the duration of the call...
131// // Start a new call...
132// apm->Initialize();
133//
134// // Close the application...
andrew@webrtc.orgf3930e92013-09-18 22:37:32 +0000135// delete apm;
niklase@google.com470e71d2011-07-07 08:21:25 +0000136//
137class AudioProcessing : public Module {
138 public:
andrew@webrtc.org54744912014-02-05 06:30:29 +0000139 // Creates an APM instance. Use one instance for every primary audio stream
140 // requiring processing. On the client-side, this would typically be one
141 // instance for the near-end stream, and additional instances for each far-end
142 // stream which requires processing. On the server-side, this would typically
143 // be one instance for every incoming stream.
andrew@webrtc.orge84978f2014-01-25 02:09:06 +0000144 static AudioProcessing* Create();
andrew@webrtc.org54744912014-02-05 06:30:29 +0000145 // Allows passing in an optional configuration at create-time.
andrew@webrtc.orge84978f2014-01-25 02:09:06 +0000146 static AudioProcessing* Create(const Config& config);
147 // TODO(ajm): Deprecated; remove all calls to it.
niklase@google.com470e71d2011-07-07 08:21:25 +0000148 static AudioProcessing* Create(int id);
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +0000149 virtual ~AudioProcessing() {}
niklase@google.com470e71d2011-07-07 08:21:25 +0000150
niklase@google.com470e71d2011-07-07 08:21:25 +0000151 // Initializes internal states, while retaining all user settings. This
152 // should be called before beginning to process a new audio stream. However,
153 // it is not necessary to call before processing the first stream after
andrew@webrtc.org60730cf2014-01-07 17:45:09 +0000154 // creation. It is also not necessary to call if the audio parameters (sample
155 // rate and number of channels) have changed. Passing updated parameters
156 // directly to |ProcessStream()| and |AnalyzeReverseStream()| is permissible.
niklase@google.com470e71d2011-07-07 08:21:25 +0000157 virtual int Initialize() = 0;
158
andrew@webrtc.org61e596f2013-07-25 18:28:29 +0000159 // Pass down additional options which don't have explicit setters. This
160 // ensures the options are applied immediately.
161 virtual void SetExtraOptions(const Config& config) = 0;
162
aluebs@webrtc.org0b72f582013-11-19 15:17:51 +0000163 virtual int EnableExperimentalNs(bool enable) = 0;
164 virtual bool experimental_ns_enabled() const = 0;
165
andrew@webrtc.org60730cf2014-01-07 17:45:09 +0000166 // DEPRECATED: It is now possible to modify the sample rate directly in a call
167 // to |ProcessStream|.
niklase@google.com470e71d2011-07-07 08:21:25 +0000168 // Sets the sample |rate| in Hz for both the primary and reverse audio
169 // streams. 8000, 16000 or 32000 Hz are permitted.
170 virtual int set_sample_rate_hz(int rate) = 0;
171 virtual int sample_rate_hz() const = 0;
172
andrew@webrtc.org60730cf2014-01-07 17:45:09 +0000173 // DEPRECATED: It is now possible to modify the number of channels directly in
174 // a call to |ProcessStream|.
niklase@google.com470e71d2011-07-07 08:21:25 +0000175 // Sets the number of channels for the primary audio stream. Input frames must
176 // contain a number of channels given by |input_channels|, while output frames
177 // will be returned with number of channels given by |output_channels|.
178 virtual int set_num_channels(int input_channels, int output_channels) = 0;
179 virtual int num_input_channels() const = 0;
180 virtual int num_output_channels() const = 0;
181
andrew@webrtc.org60730cf2014-01-07 17:45:09 +0000182 // DEPRECATED: It is now possible to modify the number of channels directly in
183 // a call to |AnalyzeReverseStream|.
niklase@google.com470e71d2011-07-07 08:21:25 +0000184 // Sets the number of channels for the reverse audio stream. Input frames must
185 // contain a number of channels given by |channels|.
186 virtual int set_num_reverse_channels(int channels) = 0;
187 virtual int num_reverse_channels() const = 0;
188
189 // Processes a 10 ms |frame| of the primary audio stream. On the client-side,
190 // this is the near-end (or captured) audio.
191 //
192 // If needed for enabled functionality, any function with the set_stream_ tag
193 // must be called prior to processing the current frame. Any getter function
194 // with the stream_ tag which is needed should be called after processing.
195 //
andrew@webrtc.org63a50982012-05-02 23:56:37 +0000196 // The |sample_rate_hz_|, |num_channels_|, and |samples_per_channel_|
andrew@webrtc.org60730cf2014-01-07 17:45:09 +0000197 // members of |frame| must be valid. If changed from the previous call to this
198 // method, it will trigger an initialization.
niklase@google.com470e71d2011-07-07 08:21:25 +0000199 virtual int ProcessStream(AudioFrame* frame) = 0;
200
201 // Analyzes a 10 ms |frame| of the reverse direction audio stream. The frame
202 // will not be modified. On the client-side, this is the far-end (or to be
203 // rendered) audio.
204 //
205 // It is only necessary to provide this if echo processing is enabled, as the
206 // reverse stream forms the echo reference signal. It is recommended, but not
207 // necessary, to provide if gain control is enabled. On the server-side this
208 // typically will not be used. If you're not sure what to pass in here,
209 // chances are you don't need to use it.
210 //
andrew@webrtc.org63a50982012-05-02 23:56:37 +0000211 // The |sample_rate_hz_|, |num_channels_|, and |samples_per_channel_|
andrew@webrtc.org60730cf2014-01-07 17:45:09 +0000212 // members of |frame| must be valid. |sample_rate_hz_| must correspond to
213 // |sample_rate_hz()|
niklase@google.com470e71d2011-07-07 08:21:25 +0000214 //
215 // TODO(ajm): add const to input; requires an implementation fix.
216 virtual int AnalyzeReverseStream(AudioFrame* frame) = 0;
217
218 // This must be called if and only if echo processing is enabled.
219 //
220 // Sets the |delay| in ms between AnalyzeReverseStream() receiving a far-end
221 // frame and ProcessStream() receiving a near-end frame containing the
222 // corresponding echo. On the client-side this can be expressed as
223 // delay = (t_render - t_analyze) + (t_process - t_capture)
224 // where,
225 // - t_analyze is the time a frame is passed to AnalyzeReverseStream() and
226 // t_render is the time the first sample of the same frame is rendered by
227 // the audio hardware.
228 // - t_capture is the time the first sample of a frame is captured by the
229 // audio hardware and t_pull is the time the same frame is passed to
230 // ProcessStream().
231 virtual int set_stream_delay_ms(int delay) = 0;
232 virtual int stream_delay_ms() const = 0;
233
andrew@webrtc.org75dd2882014-02-11 20:52:30 +0000234 // Call to signal that a key press occurred (true) or did not occur (false)
235 // with this chunk of audio.
236 virtual void set_stream_key_pressed(bool key_pressed) = 0;
237 virtual bool stream_key_pressed() const = 0;
238
andrew@webrtc.org6f9f8172012-03-06 19:03:39 +0000239 // Sets a delay |offset| in ms to add to the values passed in through
240 // set_stream_delay_ms(). May be positive or negative.
241 //
242 // Note that this could cause an otherwise valid value passed to
243 // set_stream_delay_ms() to return an error.
244 virtual void set_delay_offset_ms(int offset) = 0;
245 virtual int delay_offset_ms() const = 0;
246
niklase@google.com470e71d2011-07-07 08:21:25 +0000247 // Starts recording debugging information to a file specified by |filename|,
248 // a NULL-terminated string. If there is an ongoing recording, the old file
249 // will be closed, and recording will continue in the newly specified file.
250 // An already existing file will be overwritten without warning.
andrew@webrtc.org5ae19de2011-12-13 22:59:33 +0000251 static const size_t kMaxFilenameSize = 1024;
niklase@google.com470e71d2011-07-07 08:21:25 +0000252 virtual int StartDebugRecording(const char filename[kMaxFilenameSize]) = 0;
253
henrikg@webrtc.org863b5362013-12-06 16:05:17 +0000254 // Same as above but uses an existing file handle. Takes ownership
255 // of |handle| and closes it at StopDebugRecording().
256 virtual int StartDebugRecording(FILE* handle) = 0;
257
niklase@google.com470e71d2011-07-07 08:21:25 +0000258 // Stops recording debugging information, and closes the file. Recording
259 // cannot be resumed in the same file (without overwriting it).
260 virtual int StopDebugRecording() = 0;
261
262 // These provide access to the component interfaces and should never return
263 // NULL. The pointers will be valid for the lifetime of the APM instance.
264 // The memory for these objects is entirely managed internally.
265 virtual EchoCancellation* echo_cancellation() const = 0;
266 virtual EchoControlMobile* echo_control_mobile() const = 0;
267 virtual GainControl* gain_control() const = 0;
268 virtual HighPassFilter* high_pass_filter() const = 0;
269 virtual LevelEstimator* level_estimator() const = 0;
270 virtual NoiseSuppression* noise_suppression() const = 0;
271 virtual VoiceDetection* voice_detection() const = 0;
272
273 struct Statistic {
274 int instant; // Instantaneous value.
275 int average; // Long-term average.
276 int maximum; // Long-term maximum.
277 int minimum; // Long-term minimum.
278 };
279
andrew@webrtc.org648af742012-02-08 01:57:29 +0000280 enum Error {
281 // Fatal errors.
niklase@google.com470e71d2011-07-07 08:21:25 +0000282 kNoError = 0,
283 kUnspecifiedError = -1,
284 kCreationFailedError = -2,
285 kUnsupportedComponentError = -3,
286 kUnsupportedFunctionError = -4,
287 kNullPointerError = -5,
288 kBadParameterError = -6,
289 kBadSampleRateError = -7,
290 kBadDataLengthError = -8,
291 kBadNumberChannelsError = -9,
292 kFileError = -10,
293 kStreamParameterNotSetError = -11,
andrew@webrtc.org648af742012-02-08 01:57:29 +0000294 kNotEnabledError = -12,
niklase@google.com470e71d2011-07-07 08:21:25 +0000295
andrew@webrtc.org648af742012-02-08 01:57:29 +0000296 // Warnings are non-fatal.
niklase@google.com470e71d2011-07-07 08:21:25 +0000297 // This results when a set_stream_ parameter is out of range. Processing
298 // will continue, but the parameter may have been truncated.
andrew@webrtc.org648af742012-02-08 01:57:29 +0000299 kBadStreamParameterWarning = -13
niklase@google.com470e71d2011-07-07 08:21:25 +0000300 };
301
302 // Inherited from Module.
pbos@webrtc.org91620802013-08-02 11:44:11 +0000303 virtual int32_t TimeUntilNextProcess() OVERRIDE;
304 virtual int32_t Process() OVERRIDE;
niklase@google.com470e71d2011-07-07 08:21:25 +0000305};
306
307// The acoustic echo cancellation (AEC) component provides better performance
308// than AECM but also requires more processing power and is dependent on delay
309// stability and reporting accuracy. As such it is well-suited and recommended
310// for PC and IP phone applications.
311//
312// Not recommended to be enabled on the server-side.
313class EchoCancellation {
314 public:
315 // EchoCancellation and EchoControlMobile may not be enabled simultaneously.
316 // Enabling one will disable the other.
317 virtual int Enable(bool enable) = 0;
318 virtual bool is_enabled() const = 0;
319
320 // Differences in clock speed on the primary and reverse streams can impact
321 // the AEC performance. On the client-side, this could be seen when different
322 // render and capture devices are used, particularly with webcams.
323 //
324 // This enables a compensation mechanism, and requires that
325 // |set_device_sample_rate_hz()| and |set_stream_drift_samples()| be called.
326 virtual int enable_drift_compensation(bool enable) = 0;
327 virtual bool is_drift_compensation_enabled() const = 0;
328
329 // Provides the sampling rate of the audio devices. It is assumed the render
330 // and capture devices use the same nominal sample rate. Required if and only
331 // if drift compensation is enabled.
332 virtual int set_device_sample_rate_hz(int rate) = 0;
333 virtual int device_sample_rate_hz() const = 0;
334
335 // Sets the difference between the number of samples rendered and captured by
336 // the audio devices since the last call to |ProcessStream()|. Must be called
andrew@webrtc.org6be1e932013-03-01 18:47:28 +0000337 // if drift compensation is enabled, prior to |ProcessStream()|.
338 virtual void set_stream_drift_samples(int drift) = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000339 virtual int stream_drift_samples() const = 0;
340
341 enum SuppressionLevel {
342 kLowSuppression,
343 kModerateSuppression,
344 kHighSuppression
345 };
346
347 // Sets the aggressiveness of the suppressor. A higher level trades off
348 // double-talk performance for increased echo suppression.
349 virtual int set_suppression_level(SuppressionLevel level) = 0;
350 virtual SuppressionLevel suppression_level() const = 0;
351
352 // Returns false if the current frame almost certainly contains no echo
353 // and true if it _might_ contain echo.
354 virtual bool stream_has_echo() const = 0;
355
356 // Enables the computation of various echo metrics. These are obtained
357 // through |GetMetrics()|.
358 virtual int enable_metrics(bool enable) = 0;
359 virtual bool are_metrics_enabled() const = 0;
360
361 // Each statistic is reported in dB.
362 // P_far: Far-end (render) signal power.
363 // P_echo: Near-end (capture) echo signal power.
364 // P_out: Signal power at the output of the AEC.
365 // P_a: Internal signal power at the point before the AEC's non-linear
366 // processor.
367 struct Metrics {
368 // RERL = ERL + ERLE
369 AudioProcessing::Statistic residual_echo_return_loss;
370
371 // ERL = 10log_10(P_far / P_echo)
372 AudioProcessing::Statistic echo_return_loss;
373
374 // ERLE = 10log_10(P_echo / P_out)
375 AudioProcessing::Statistic echo_return_loss_enhancement;
376
377 // (Pre non-linear processing suppression) A_NLP = 10log_10(P_echo / P_a)
378 AudioProcessing::Statistic a_nlp;
379 };
380
381 // TODO(ajm): discuss the metrics update period.
382 virtual int GetMetrics(Metrics* metrics) = 0;
383
bjornv@google.com1ba3dbe2011-10-03 08:18:10 +0000384 // Enables computation and logging of delay values. Statistics are obtained
385 // through |GetDelayMetrics()|.
386 virtual int enable_delay_logging(bool enable) = 0;
387 virtual bool is_delay_logging_enabled() const = 0;
388
389 // The delay metrics consists of the delay |median| and the delay standard
390 // deviation |std|. The values are averaged over the time period since the
391 // last call to |GetDelayMetrics()|.
392 virtual int GetDelayMetrics(int* median, int* std) = 0;
393
bjornv@webrtc.org91d11b32013-03-05 16:53:09 +0000394 // Returns a pointer to the low level AEC component. In case of multiple
395 // channels, the pointer to the first one is returned. A NULL pointer is
396 // returned when the AEC component is disabled or has not been initialized
397 // successfully.
398 virtual struct AecCore* aec_core() const = 0;
399
niklase@google.com470e71d2011-07-07 08:21:25 +0000400 protected:
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +0000401 virtual ~EchoCancellation() {}
niklase@google.com470e71d2011-07-07 08:21:25 +0000402};
403
404// The acoustic echo control for mobile (AECM) component is a low complexity
405// robust option intended for use on mobile devices.
406//
407// Not recommended to be enabled on the server-side.
408class EchoControlMobile {
409 public:
410 // EchoCancellation and EchoControlMobile may not be enabled simultaneously.
411 // Enabling one will disable the other.
412 virtual int Enable(bool enable) = 0;
413 virtual bool is_enabled() const = 0;
414
415 // Recommended settings for particular audio routes. In general, the louder
416 // the echo is expected to be, the higher this value should be set. The
417 // preferred setting may vary from device to device.
418 enum RoutingMode {
419 kQuietEarpieceOrHeadset,
420 kEarpiece,
421 kLoudEarpiece,
422 kSpeakerphone,
423 kLoudSpeakerphone
424 };
425
426 // Sets echo control appropriate for the audio routing |mode| on the device.
427 // It can and should be updated during a call if the audio routing changes.
428 virtual int set_routing_mode(RoutingMode mode) = 0;
429 virtual RoutingMode routing_mode() const = 0;
430
431 // Comfort noise replaces suppressed background noise to maintain a
432 // consistent signal level.
433 virtual int enable_comfort_noise(bool enable) = 0;
434 virtual bool is_comfort_noise_enabled() const = 0;
435
bjornv@google.comc4b939c2011-07-13 08:09:56 +0000436 // A typical use case is to initialize the component with an echo path from a
ajm@google.com22e65152011-07-18 18:03:01 +0000437 // previous call. The echo path is retrieved using |GetEchoPath()|, typically
438 // at the end of a call. The data can then be stored for later use as an
439 // initializer before the next call, using |SetEchoPath()|.
440 //
bjornv@google.comc4b939c2011-07-13 08:09:56 +0000441 // Controlling the echo path this way requires the data |size_bytes| to match
442 // the internal echo path size. This size can be acquired using
443 // |echo_path_size_bytes()|. |SetEchoPath()| causes an entire reset, worth
ajm@google.com22e65152011-07-18 18:03:01 +0000444 // noting if it is to be called during an ongoing call.
445 //
446 // It is possible that version incompatibilities may result in a stored echo
447 // path of the incorrect size. In this case, the stored path should be
448 // discarded.
449 virtual int SetEchoPath(const void* echo_path, size_t size_bytes) = 0;
450 virtual int GetEchoPath(void* echo_path, size_t size_bytes) const = 0;
451
452 // The returned path size is guaranteed not to change for the lifetime of
453 // the application.
454 static size_t echo_path_size_bytes();
bjornv@google.comc4b939c2011-07-13 08:09:56 +0000455
niklase@google.com470e71d2011-07-07 08:21:25 +0000456 protected:
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +0000457 virtual ~EchoControlMobile() {}
niklase@google.com470e71d2011-07-07 08:21:25 +0000458};
459
460// The automatic gain control (AGC) component brings the signal to an
461// appropriate range. This is done by applying a digital gain directly and, in
462// the analog mode, prescribing an analog gain to be applied at the audio HAL.
463//
464// Recommended to be enabled on the client-side.
465class GainControl {
466 public:
467 virtual int Enable(bool enable) = 0;
468 virtual bool is_enabled() const = 0;
469
470 // When an analog mode is set, this must be called prior to |ProcessStream()|
471 // to pass the current analog level from the audio HAL. Must be within the
472 // range provided to |set_analog_level_limits()|.
473 virtual int set_stream_analog_level(int level) = 0;
474
475 // When an analog mode is set, this should be called after |ProcessStream()|
476 // to obtain the recommended new analog level for the audio HAL. It is the
477 // users responsibility to apply this level.
478 virtual int stream_analog_level() = 0;
479
480 enum Mode {
481 // Adaptive mode intended for use if an analog volume control is available
482 // on the capture device. It will require the user to provide coupling
483 // between the OS mixer controls and AGC through the |stream_analog_level()|
484 // functions.
485 //
486 // It consists of an analog gain prescription for the audio device and a
487 // digital compression stage.
488 kAdaptiveAnalog,
489
490 // Adaptive mode intended for situations in which an analog volume control
491 // is unavailable. It operates in a similar fashion to the adaptive analog
492 // mode, but with scaling instead applied in the digital domain. As with
493 // the analog mode, it additionally uses a digital compression stage.
494 kAdaptiveDigital,
495
496 // Fixed mode which enables only the digital compression stage also used by
497 // the two adaptive modes.
498 //
499 // It is distinguished from the adaptive modes by considering only a
500 // short time-window of the input signal. It applies a fixed gain through
501 // most of the input level range, and compresses (gradually reduces gain
502 // with increasing level) the input signal at higher levels. This mode is
503 // preferred on embedded devices where the capture signal level is
504 // predictable, so that a known gain can be applied.
505 kFixedDigital
506 };
507
508 virtual int set_mode(Mode mode) = 0;
509 virtual Mode mode() const = 0;
510
511 // Sets the target peak |level| (or envelope) of the AGC in dBFs (decibels
512 // from digital full-scale). The convention is to use positive values. For
513 // instance, passing in a value of 3 corresponds to -3 dBFs, or a target
514 // level 3 dB below full-scale. Limited to [0, 31].
515 //
516 // TODO(ajm): use a negative value here instead, if/when VoE will similarly
517 // update its interface.
518 virtual int set_target_level_dbfs(int level) = 0;
519 virtual int target_level_dbfs() const = 0;
520
521 // Sets the maximum |gain| the digital compression stage may apply, in dB. A
522 // higher number corresponds to greater compression, while a value of 0 will
523 // leave the signal uncompressed. Limited to [0, 90].
524 virtual int set_compression_gain_db(int gain) = 0;
525 virtual int compression_gain_db() const = 0;
526
527 // When enabled, the compression stage will hard limit the signal to the
528 // target level. Otherwise, the signal will be compressed but not limited
529 // above the target level.
530 virtual int enable_limiter(bool enable) = 0;
531 virtual bool is_limiter_enabled() const = 0;
532
533 // Sets the |minimum| and |maximum| analog levels of the audio capture device.
534 // Must be set if and only if an analog mode is used. Limited to [0, 65535].
535 virtual int set_analog_level_limits(int minimum,
536 int maximum) = 0;
537 virtual int analog_level_minimum() const = 0;
538 virtual int analog_level_maximum() const = 0;
539
540 // Returns true if the AGC has detected a saturation event (period where the
541 // signal reaches digital full-scale) in the current frame and the analog
542 // level cannot be reduced.
543 //
544 // This could be used as an indicator to reduce or disable analog mic gain at
545 // the audio HAL.
546 virtual bool stream_is_saturated() const = 0;
547
548 protected:
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +0000549 virtual ~GainControl() {}
niklase@google.com470e71d2011-07-07 08:21:25 +0000550};
551
552// A filtering component which removes DC offset and low-frequency noise.
553// Recommended to be enabled on the client-side.
554class HighPassFilter {
555 public:
556 virtual int Enable(bool enable) = 0;
557 virtual bool is_enabled() const = 0;
558
559 protected:
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +0000560 virtual ~HighPassFilter() {}
niklase@google.com470e71d2011-07-07 08:21:25 +0000561};
562
563// An estimation component used to retrieve level metrics.
564class LevelEstimator {
565 public:
566 virtual int Enable(bool enable) = 0;
567 virtual bool is_enabled() const = 0;
568
andrew@webrtc.org755b04a2011-11-15 16:57:56 +0000569 // Returns the root mean square (RMS) level in dBFs (decibels from digital
570 // full-scale), or alternately dBov. It is computed over all primary stream
571 // frames since the last call to RMS(). The returned value is positive but
572 // should be interpreted as negative. It is constrained to [0, 127].
573 //
574 // The computation follows:
575 // http://tools.ietf.org/html/draft-ietf-avtext-client-to-mixer-audio-level-05
576 // with the intent that it can provide the RTP audio level indication.
577 //
578 // Frames passed to ProcessStream() with an |_energy| of zero are considered
579 // to have been muted. The RMS of the frame will be interpreted as -127.
580 virtual int RMS() = 0;
niklase@google.com470e71d2011-07-07 08:21:25 +0000581
582 protected:
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +0000583 virtual ~LevelEstimator() {}
niklase@google.com470e71d2011-07-07 08:21:25 +0000584};
585
586// The noise suppression (NS) component attempts to remove noise while
587// retaining speech. Recommended to be enabled on the client-side.
588//
589// Recommended to be enabled on the client-side.
590class NoiseSuppression {
591 public:
592 virtual int Enable(bool enable) = 0;
593 virtual bool is_enabled() const = 0;
594
595 // Determines the aggressiveness of the suppression. Increasing the level
596 // will reduce the noise level at the expense of a higher speech distortion.
597 enum Level {
598 kLow,
599 kModerate,
600 kHigh,
601 kVeryHigh
602 };
603
604 virtual int set_level(Level level) = 0;
605 virtual Level level() const = 0;
606
bjornv@webrtc.org08329f42012-07-12 21:00:43 +0000607 // Returns the internally computed prior speech probability of current frame
608 // averaged over output channels. This is not supported in fixed point, for
609 // which |kUnsupportedFunctionError| is returned.
610 virtual float speech_probability() const = 0;
611
niklase@google.com470e71d2011-07-07 08:21:25 +0000612 protected:
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +0000613 virtual ~NoiseSuppression() {}
niklase@google.com470e71d2011-07-07 08:21:25 +0000614};
615
616// The voice activity detection (VAD) component analyzes the stream to
617// determine if voice is present. A facility is also provided to pass in an
618// external VAD decision.
andrew@webrtc.orged083d42011-09-19 15:28:51 +0000619//
620// In addition to |stream_has_voice()| the VAD decision is provided through the
andrew@webrtc.org63a50982012-05-02 23:56:37 +0000621// |AudioFrame| passed to |ProcessStream()|. The |vad_activity_| member will be
andrew@webrtc.orged083d42011-09-19 15:28:51 +0000622// modified to reflect the current decision.
niklase@google.com470e71d2011-07-07 08:21:25 +0000623class VoiceDetection {
624 public:
625 virtual int Enable(bool enable) = 0;
626 virtual bool is_enabled() const = 0;
627
628 // Returns true if voice is detected in the current frame. Should be called
629 // after |ProcessStream()|.
630 virtual bool stream_has_voice() const = 0;
631
632 // Some of the APM functionality requires a VAD decision. In the case that
633 // a decision is externally available for the current frame, it can be passed
634 // in here, before |ProcessStream()| is called.
635 //
636 // VoiceDetection does _not_ need to be enabled to use this. If it happens to
637 // be enabled, detection will be skipped for any frame in which an external
638 // VAD decision is provided.
639 virtual int set_stream_has_voice(bool has_voice) = 0;
640
641 // Specifies the likelihood that a frame will be declared to contain voice.
642 // A higher value makes it more likely that speech will not be clipped, at
643 // the expense of more noise being detected as voice.
644 enum Likelihood {
645 kVeryLowLikelihood,
646 kLowLikelihood,
647 kModerateLikelihood,
648 kHighLikelihood
649 };
650
651 virtual int set_likelihood(Likelihood likelihood) = 0;
652 virtual Likelihood likelihood() const = 0;
653
654 // Sets the |size| of the frames in ms on which the VAD will operate. Larger
655 // frames will improve detection accuracy, but reduce the frequency of
656 // updates.
657 //
658 // This does not impact the size of frames passed to |ProcessStream()|.
659 virtual int set_frame_size_ms(int size) = 0;
660 virtual int frame_size_ms() const = 0;
661
662 protected:
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +0000663 virtual ~VoiceDetection() {}
niklase@google.com470e71d2011-07-07 08:21:25 +0000664};
665} // namespace webrtc
666
andrew@webrtc.orgd72b3d62012-11-15 21:46:06 +0000667#endif // WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AUDIO_PROCESSING_H_