2 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
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.
11 #ifndef WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AUDIO_PROCESSING_H_
12 #define WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AUDIO_PROCESSING_H_
14 #include <stddef.h> // size_t
15 #include <stdio.h> // FILE
17 #include "webrtc/common.h"
18 #include "webrtc/typedefs.h"
25 class EchoCancellation;
26 class EchoControlMobile;
30 class NoiseSuppression;
33 // Use to enable the delay correction feature. This now engages an extended
34 // filter mode in the AEC, along with robustness measures around the reported
35 // system delays. It comes with a significant increase in AEC complexity, but is
36 // much more robust to unreliable reported delays.
38 // Detailed changes to the algorithm:
39 // - The filter length is changed from 48 to 128 ms. This comes with tuning of
40 // several parameters: i) filter adaptation stepsize and error threshold;
41 // ii) non-linear processing smoothing and overdrive.
42 // - Option to ignore the reported delays on platforms which we deem
43 // sufficiently unreliable. See WEBRTC_UNTRUSTED_DELAY in echo_cancellation.c.
44 // - Faster startup times by removing the excessive "startup phase" processing
45 // of reported delays.
46 // - Much more conservative adjustments to the far-end read pointer. We smooth
47 // the delay difference more heavily, and back off from the difference more.
48 // Adjustments force a readaptation of the filter, so they should be avoided
49 // except when really necessary.
50 struct DelayCorrection {
51 DelayCorrection() : enabled(false) {}
52 explicit DelayCorrection(bool enabled) : enabled(enabled) {}
56 // Use to disable the reported system delays. By disabling the reported system
57 // delays the echo cancellation algorithm assumes the process and reverse
58 // streams to be aligned. This configuration only applies to EchoCancellation
59 // and not EchoControlMobile and is set with AudioProcessing::SetExtraOptions().
60 // Note that by disabling reported system delays the EchoCancellation may
61 // regress in performance.
62 struct ReportedDelay {
63 ReportedDelay() : enabled(true) {}
64 explicit ReportedDelay(bool enabled) : enabled(enabled) {}
68 // Must be provided through AudioProcessing::Create(Confg&). It will have no
69 // impact if used with AudioProcessing::SetExtraOptions().
70 struct ExperimentalAgc {
71 ExperimentalAgc() : enabled(true) {}
72 explicit ExperimentalAgc(bool enabled) : enabled(enabled) {}
76 // Use to enable experimental noise suppression. It can be set in the
77 // constructor or using AudioProcessing::SetExtraOptions().
78 struct ExperimentalNs {
79 ExperimentalNs() : enabled(false) {}
80 explicit ExperimentalNs(bool enabled) : enabled(enabled) {}
84 static const int kAudioProcMaxNativeSampleRateHz = 32000;
86 // The Audio Processing Module (APM) provides a collection of voice processing
87 // components designed for real-time communications software.
89 // APM operates on two audio streams on a frame-by-frame basis. Frames of the
90 // primary stream, on which all processing is applied, are passed to
91 // |ProcessStream()|. Frames of the reverse direction stream, which are used for
92 // analysis by some components, are passed to |AnalyzeReverseStream()|. On the
93 // client-side, this will typically be the near-end (capture) and far-end
94 // (render) streams, respectively. APM should be placed in the signal chain as
95 // close to the audio hardware abstraction layer (HAL) as possible.
97 // On the server-side, the reverse stream will normally not be used, with
98 // processing occurring on each incoming stream.
100 // Component interfaces follow a similar pattern and are accessed through
101 // corresponding getters in APM. All components are disabled at create-time,
102 // with default settings that are recommended for most situations. New settings
103 // can be applied without enabling a component. Enabling a component triggers
104 // memory allocation and initialization to allow it to start processing the
107 // Thread safety is provided with the following assumptions to reduce locking
109 // 1. The stream getters and setters are called from the same thread as
110 // ProcessStream(). More precisely, stream functions are never called
111 // concurrently with ProcessStream().
112 // 2. Parameter getters are never called concurrently with the corresponding
115 // APM accepts only linear PCM audio data in chunks of 10 ms. The int16
116 // interfaces use interleaved data, while the float interfaces use deinterleaved
119 // Usage example, omitting error checking:
120 // AudioProcessing* apm = AudioProcessing::Create(0);
122 // apm->high_pass_filter()->Enable(true);
124 // apm->echo_cancellation()->enable_drift_compensation(false);
125 // apm->echo_cancellation()->Enable(true);
127 // apm->noise_reduction()->set_level(kHighSuppression);
128 // apm->noise_reduction()->Enable(true);
130 // apm->gain_control()->set_analog_level_limits(0, 255);
131 // apm->gain_control()->set_mode(kAdaptiveAnalog);
132 // apm->gain_control()->Enable(true);
134 // apm->voice_detection()->Enable(true);
136 // // Start a voice call...
138 // // ... Render frame arrives bound for the audio HAL ...
139 // apm->AnalyzeReverseStream(render_frame);
141 // // ... Capture frame arrives from the audio HAL ...
142 // // Call required set_stream_ functions.
143 // apm->set_stream_delay_ms(delay_ms);
144 // apm->gain_control()->set_stream_analog_level(analog_level);
146 // apm->ProcessStream(capture_frame);
148 // // Call required stream_ functions.
149 // analog_level = apm->gain_control()->stream_analog_level();
150 // has_voice = apm->stream_has_voice();
152 // // Repeate render and capture processing for the duration of the call...
153 // // Start a new call...
154 // apm->Initialize();
156 // // Close the application...
159 class AudioProcessing {
165 // Mono, keyboard mic.
167 // Left, right, keyboard mic.
171 // Creates an APM instance. Use one instance for every primary audio stream
172 // requiring processing. On the client-side, this would typically be one
173 // instance for the near-end stream, and additional instances for each far-end
174 // stream which requires processing. On the server-side, this would typically
175 // be one instance for every incoming stream.
176 static AudioProcessing* Create();
177 // Allows passing in an optional configuration at create-time.
178 static AudioProcessing* Create(const Config& config);
179 // TODO(ajm): Deprecated; remove all calls to it.
180 static AudioProcessing* Create(int id);
181 virtual ~AudioProcessing() {}
183 // Initializes internal states, while retaining all user settings. This
184 // should be called before beginning to process a new audio stream. However,
185 // it is not necessary to call before processing the first stream after
188 // It is also not necessary to call if the audio parameters (sample
189 // rate and number of channels) have changed. Passing updated parameters
190 // directly to |ProcessStream()| and |AnalyzeReverseStream()| is permissible.
191 // If the parameters are known at init-time though, they may be provided.
192 virtual int Initialize() = 0;
194 // The int16 interfaces require:
195 // - only |NativeRate|s be used
196 // - that the input, output and reverse rates must match
197 // - that |output_layout| matches |input_layout|
199 // The float interfaces accept arbitrary rates and support differing input
200 // and output layouts, but the output may only remove channels, not add.
201 virtual int Initialize(int input_sample_rate_hz,
202 int output_sample_rate_hz,
203 int reverse_sample_rate_hz,
204 ChannelLayout input_layout,
205 ChannelLayout output_layout,
206 ChannelLayout reverse_layout) = 0;
208 // Pass down additional options which don't have explicit setters. This
209 // ensures the options are applied immediately.
210 virtual void SetExtraOptions(const Config& config) = 0;
213 // TODO(ajm): Remove after Chromium has upgraded to using Initialize().
214 virtual int set_sample_rate_hz(int rate) = 0;
215 // TODO(ajm): Remove after voice engine no longer requires it to resample
216 // the reverse stream to the forward rate.
217 virtual int input_sample_rate_hz() const = 0;
218 // TODO(ajm): Remove after Chromium no longer depends on it.
219 virtual int sample_rate_hz() const = 0;
221 // TODO(ajm): Only intended for internal use. Make private and friend the
222 // necessary classes?
223 virtual int proc_sample_rate_hz() const = 0;
224 virtual int proc_split_sample_rate_hz() const = 0;
225 virtual int num_input_channels() const = 0;
226 virtual int num_output_channels() const = 0;
227 virtual int num_reverse_channels() const = 0;
229 // Set to true when the output of AudioProcessing will be muted or in some
230 // other way not used. Ideally, the captured audio would still be processed,
231 // but some components may change behavior based on this information.
233 virtual void set_output_will_be_muted(bool muted) = 0;
234 virtual bool output_will_be_muted() const = 0;
236 // Processes a 10 ms |frame| of the primary audio stream. On the client-side,
237 // this is the near-end (or captured) audio.
239 // If needed for enabled functionality, any function with the set_stream_ tag
240 // must be called prior to processing the current frame. Any getter function
241 // with the stream_ tag which is needed should be called after processing.
243 // The |sample_rate_hz_|, |num_channels_|, and |samples_per_channel_|
244 // members of |frame| must be valid. If changed from the previous call to this
245 // method, it will trigger an initialization.
246 virtual int ProcessStream(AudioFrame* frame) = 0;
248 // Accepts deinterleaved float audio with the range [-1, 1]. Each element
249 // of |src| points to a channel buffer, arranged according to
250 // |input_layout|. At output, the channels will be arranged according to
251 // |output_layout| at |output_sample_rate_hz| in |dest|.
253 // The output layout may only remove channels, not add. |src| and |dest|
254 // may use the same memory, if desired.
255 virtual int ProcessStream(const float* const* src,
256 int samples_per_channel,
257 int input_sample_rate_hz,
258 ChannelLayout input_layout,
259 int output_sample_rate_hz,
260 ChannelLayout output_layout,
261 float* const* dest) = 0;
263 // Analyzes a 10 ms |frame| of the reverse direction audio stream. The frame
264 // will not be modified. On the client-side, this is the far-end (or to be
267 // It is only necessary to provide this if echo processing is enabled, as the
268 // reverse stream forms the echo reference signal. It is recommended, but not
269 // necessary, to provide if gain control is enabled. On the server-side this
270 // typically will not be used. If you're not sure what to pass in here,
271 // chances are you don't need to use it.
273 // The |sample_rate_hz_|, |num_channels_|, and |samples_per_channel_|
274 // members of |frame| must be valid. |sample_rate_hz_| must correspond to
275 // |input_sample_rate_hz()|
277 // TODO(ajm): add const to input; requires an implementation fix.
278 virtual int AnalyzeReverseStream(AudioFrame* frame) = 0;
280 // Accepts deinterleaved float audio with the range [-1, 1]. Each element
281 // of |data| points to a channel buffer, arranged according to |layout|.
282 virtual int AnalyzeReverseStream(const float* const* data,
283 int samples_per_channel,
285 ChannelLayout layout) = 0;
287 // This must be called if and only if echo processing is enabled.
289 // Sets the |delay| in ms between AnalyzeReverseStream() receiving a far-end
290 // frame and ProcessStream() receiving a near-end frame containing the
291 // corresponding echo. On the client-side this can be expressed as
292 // delay = (t_render - t_analyze) + (t_process - t_capture)
294 // - t_analyze is the time a frame is passed to AnalyzeReverseStream() and
295 // t_render is the time the first sample of the same frame is rendered by
296 // the audio hardware.
297 // - t_capture is the time the first sample of a frame is captured by the
298 // audio hardware and t_pull is the time the same frame is passed to
300 virtual int set_stream_delay_ms(int delay) = 0;
301 virtual int stream_delay_ms() const = 0;
302 virtual bool was_stream_delay_set() const = 0;
304 // Call to signal that a key press occurred (true) or did not occur (false)
305 // with this chunk of audio.
306 virtual void set_stream_key_pressed(bool key_pressed) = 0;
307 virtual bool stream_key_pressed() const = 0;
309 // Sets a delay |offset| in ms to add to the values passed in through
310 // set_stream_delay_ms(). May be positive or negative.
312 // Note that this could cause an otherwise valid value passed to
313 // set_stream_delay_ms() to return an error.
314 virtual void set_delay_offset_ms(int offset) = 0;
315 virtual int delay_offset_ms() const = 0;
317 // Starts recording debugging information to a file specified by |filename|,
318 // a NULL-terminated string. If there is an ongoing recording, the old file
319 // will be closed, and recording will continue in the newly specified file.
320 // An already existing file will be overwritten without warning.
321 static const size_t kMaxFilenameSize = 1024;
322 virtual int StartDebugRecording(const char filename[kMaxFilenameSize]) = 0;
324 // Same as above but uses an existing file handle. Takes ownership
325 // of |handle| and closes it at StopDebugRecording().
326 virtual int StartDebugRecording(FILE* handle) = 0;
328 // Stops recording debugging information, and closes the file. Recording
329 // cannot be resumed in the same file (without overwriting it).
330 virtual int StopDebugRecording() = 0;
332 // These provide access to the component interfaces and should never return
333 // NULL. The pointers will be valid for the lifetime of the APM instance.
334 // The memory for these objects is entirely managed internally.
335 virtual EchoCancellation* echo_cancellation() const = 0;
336 virtual EchoControlMobile* echo_control_mobile() const = 0;
337 virtual GainControl* gain_control() const = 0;
338 virtual HighPassFilter* high_pass_filter() const = 0;
339 virtual LevelEstimator* level_estimator() const = 0;
340 virtual NoiseSuppression* noise_suppression() const = 0;
341 virtual VoiceDetection* voice_detection() const = 0;
344 int instant; // Instantaneous value.
345 int average; // Long-term average.
346 int maximum; // Long-term maximum.
347 int minimum; // Long-term minimum.
353 kUnspecifiedError = -1,
354 kCreationFailedError = -2,
355 kUnsupportedComponentError = -3,
356 kUnsupportedFunctionError = -4,
357 kNullPointerError = -5,
358 kBadParameterError = -6,
359 kBadSampleRateError = -7,
360 kBadDataLengthError = -8,
361 kBadNumberChannelsError = -9,
363 kStreamParameterNotSetError = -11,
364 kNotEnabledError = -12,
366 // Warnings are non-fatal.
367 // This results when a set_stream_ parameter is out of range. Processing
368 // will continue, but the parameter may have been truncated.
369 kBadStreamParameterWarning = -13
373 kSampleRate8kHz = 8000,
374 kSampleRate16kHz = 16000,
375 kSampleRate32kHz = 32000
378 static const int kChunkSizeMs = 10;
381 // The acoustic echo cancellation (AEC) component provides better performance
382 // than AECM but also requires more processing power and is dependent on delay
383 // stability and reporting accuracy. As such it is well-suited and recommended
384 // for PC and IP phone applications.
386 // Not recommended to be enabled on the server-side.
387 class EchoCancellation {
389 // EchoCancellation and EchoControlMobile may not be enabled simultaneously.
390 // Enabling one will disable the other.
391 virtual int Enable(bool enable) = 0;
392 virtual bool is_enabled() const = 0;
394 // Differences in clock speed on the primary and reverse streams can impact
395 // the AEC performance. On the client-side, this could be seen when different
396 // render and capture devices are used, particularly with webcams.
398 // This enables a compensation mechanism, and requires that
399 // set_stream_drift_samples() be called.
400 virtual int enable_drift_compensation(bool enable) = 0;
401 virtual bool is_drift_compensation_enabled() const = 0;
403 // Sets the difference between the number of samples rendered and captured by
404 // the audio devices since the last call to |ProcessStream()|. Must be called
405 // if drift compensation is enabled, prior to |ProcessStream()|.
406 virtual void set_stream_drift_samples(int drift) = 0;
407 virtual int stream_drift_samples() const = 0;
409 enum SuppressionLevel {
411 kModerateSuppression,
415 // Sets the aggressiveness of the suppressor. A higher level trades off
416 // double-talk performance for increased echo suppression.
417 virtual int set_suppression_level(SuppressionLevel level) = 0;
418 virtual SuppressionLevel suppression_level() const = 0;
420 // Returns false if the current frame almost certainly contains no echo
421 // and true if it _might_ contain echo.
422 virtual bool stream_has_echo() const = 0;
424 // Enables the computation of various echo metrics. These are obtained
425 // through |GetMetrics()|.
426 virtual int enable_metrics(bool enable) = 0;
427 virtual bool are_metrics_enabled() const = 0;
429 // Each statistic is reported in dB.
430 // P_far: Far-end (render) signal power.
431 // P_echo: Near-end (capture) echo signal power.
432 // P_out: Signal power at the output of the AEC.
433 // P_a: Internal signal power at the point before the AEC's non-linear
437 AudioProcessing::Statistic residual_echo_return_loss;
439 // ERL = 10log_10(P_far / P_echo)
440 AudioProcessing::Statistic echo_return_loss;
442 // ERLE = 10log_10(P_echo / P_out)
443 AudioProcessing::Statistic echo_return_loss_enhancement;
445 // (Pre non-linear processing suppression) A_NLP = 10log_10(P_echo / P_a)
446 AudioProcessing::Statistic a_nlp;
449 // TODO(ajm): discuss the metrics update period.
450 virtual int GetMetrics(Metrics* metrics) = 0;
452 // Enables computation and logging of delay values. Statistics are obtained
453 // through |GetDelayMetrics()|.
454 virtual int enable_delay_logging(bool enable) = 0;
455 virtual bool is_delay_logging_enabled() const = 0;
457 // The delay metrics consists of the delay |median| and the delay standard
458 // deviation |std|. The values are averaged over the time period since the
459 // last call to |GetDelayMetrics()|.
460 virtual int GetDelayMetrics(int* median, int* std) = 0;
462 // Returns a pointer to the low level AEC component. In case of multiple
463 // channels, the pointer to the first one is returned. A NULL pointer is
464 // returned when the AEC component is disabled or has not been initialized
466 virtual struct AecCore* aec_core() const = 0;
469 virtual ~EchoCancellation() {}
472 // The acoustic echo control for mobile (AECM) component is a low complexity
473 // robust option intended for use on mobile devices.
475 // Not recommended to be enabled on the server-side.
476 class EchoControlMobile {
478 // EchoCancellation and EchoControlMobile may not be enabled simultaneously.
479 // Enabling one will disable the other.
480 virtual int Enable(bool enable) = 0;
481 virtual bool is_enabled() const = 0;
483 // Recommended settings for particular audio routes. In general, the louder
484 // the echo is expected to be, the higher this value should be set. The
485 // preferred setting may vary from device to device.
487 kQuietEarpieceOrHeadset,
494 // Sets echo control appropriate for the audio routing |mode| on the device.
495 // It can and should be updated during a call if the audio routing changes.
496 virtual int set_routing_mode(RoutingMode mode) = 0;
497 virtual RoutingMode routing_mode() const = 0;
499 // Comfort noise replaces suppressed background noise to maintain a
500 // consistent signal level.
501 virtual int enable_comfort_noise(bool enable) = 0;
502 virtual bool is_comfort_noise_enabled() const = 0;
504 // A typical use case is to initialize the component with an echo path from a
505 // previous call. The echo path is retrieved using |GetEchoPath()|, typically
506 // at the end of a call. The data can then be stored for later use as an
507 // initializer before the next call, using |SetEchoPath()|.
509 // Controlling the echo path this way requires the data |size_bytes| to match
510 // the internal echo path size. This size can be acquired using
511 // |echo_path_size_bytes()|. |SetEchoPath()| causes an entire reset, worth
512 // noting if it is to be called during an ongoing call.
514 // It is possible that version incompatibilities may result in a stored echo
515 // path of the incorrect size. In this case, the stored path should be
517 virtual int SetEchoPath(const void* echo_path, size_t size_bytes) = 0;
518 virtual int GetEchoPath(void* echo_path, size_t size_bytes) const = 0;
520 // The returned path size is guaranteed not to change for the lifetime of
522 static size_t echo_path_size_bytes();
525 virtual ~EchoControlMobile() {}
528 // The automatic gain control (AGC) component brings the signal to an
529 // appropriate range. This is done by applying a digital gain directly and, in
530 // the analog mode, prescribing an analog gain to be applied at the audio HAL.
532 // Recommended to be enabled on the client-side.
535 virtual int Enable(bool enable) = 0;
536 virtual bool is_enabled() const = 0;
538 // When an analog mode is set, this must be called prior to |ProcessStream()|
539 // to pass the current analog level from the audio HAL. Must be within the
540 // range provided to |set_analog_level_limits()|.
541 virtual int set_stream_analog_level(int level) = 0;
543 // When an analog mode is set, this should be called after |ProcessStream()|
544 // to obtain the recommended new analog level for the audio HAL. It is the
545 // users responsibility to apply this level.
546 virtual int stream_analog_level() = 0;
549 // Adaptive mode intended for use if an analog volume control is available
550 // on the capture device. It will require the user to provide coupling
551 // between the OS mixer controls and AGC through the |stream_analog_level()|
554 // It consists of an analog gain prescription for the audio device and a
555 // digital compression stage.
558 // Adaptive mode intended for situations in which an analog volume control
559 // is unavailable. It operates in a similar fashion to the adaptive analog
560 // mode, but with scaling instead applied in the digital domain. As with
561 // the analog mode, it additionally uses a digital compression stage.
564 // Fixed mode which enables only the digital compression stage also used by
565 // the two adaptive modes.
567 // It is distinguished from the adaptive modes by considering only a
568 // short time-window of the input signal. It applies a fixed gain through
569 // most of the input level range, and compresses (gradually reduces gain
570 // with increasing level) the input signal at higher levels. This mode is
571 // preferred on embedded devices where the capture signal level is
572 // predictable, so that a known gain can be applied.
576 virtual int set_mode(Mode mode) = 0;
577 virtual Mode mode() const = 0;
579 // Sets the target peak |level| (or envelope) of the AGC in dBFs (decibels
580 // from digital full-scale). The convention is to use positive values. For
581 // instance, passing in a value of 3 corresponds to -3 dBFs, or a target
582 // level 3 dB below full-scale. Limited to [0, 31].
584 // TODO(ajm): use a negative value here instead, if/when VoE will similarly
585 // update its interface.
586 virtual int set_target_level_dbfs(int level) = 0;
587 virtual int target_level_dbfs() const = 0;
589 // Sets the maximum |gain| the digital compression stage may apply, in dB. A
590 // higher number corresponds to greater compression, while a value of 0 will
591 // leave the signal uncompressed. Limited to [0, 90].
592 virtual int set_compression_gain_db(int gain) = 0;
593 virtual int compression_gain_db() const = 0;
595 // When enabled, the compression stage will hard limit the signal to the
596 // target level. Otherwise, the signal will be compressed but not limited
597 // above the target level.
598 virtual int enable_limiter(bool enable) = 0;
599 virtual bool is_limiter_enabled() const = 0;
601 // Sets the |minimum| and |maximum| analog levels of the audio capture device.
602 // Must be set if and only if an analog mode is used. Limited to [0, 65535].
603 virtual int set_analog_level_limits(int minimum,
605 virtual int analog_level_minimum() const = 0;
606 virtual int analog_level_maximum() const = 0;
608 // Returns true if the AGC has detected a saturation event (period where the
609 // signal reaches digital full-scale) in the current frame and the analog
610 // level cannot be reduced.
612 // This could be used as an indicator to reduce or disable analog mic gain at
614 virtual bool stream_is_saturated() const = 0;
617 virtual ~GainControl() {}
620 // A filtering component which removes DC offset and low-frequency noise.
621 // Recommended to be enabled on the client-side.
622 class HighPassFilter {
624 virtual int Enable(bool enable) = 0;
625 virtual bool is_enabled() const = 0;
628 virtual ~HighPassFilter() {}
631 // An estimation component used to retrieve level metrics.
632 class LevelEstimator {
634 virtual int Enable(bool enable) = 0;
635 virtual bool is_enabled() const = 0;
637 // Returns the root mean square (RMS) level in dBFs (decibels from digital
638 // full-scale), or alternately dBov. It is computed over all primary stream
639 // frames since the last call to RMS(). The returned value is positive but
640 // should be interpreted as negative. It is constrained to [0, 127].
642 // The computation follows: https://tools.ietf.org/html/rfc6465
643 // with the intent that it can provide the RTP audio level indication.
645 // Frames passed to ProcessStream() with an |_energy| of zero are considered
646 // to have been muted. The RMS of the frame will be interpreted as -127.
647 virtual int RMS() = 0;
650 virtual ~LevelEstimator() {}
653 // The noise suppression (NS) component attempts to remove noise while
654 // retaining speech. Recommended to be enabled on the client-side.
656 // Recommended to be enabled on the client-side.
657 class NoiseSuppression {
659 virtual int Enable(bool enable) = 0;
660 virtual bool is_enabled() const = 0;
662 // Determines the aggressiveness of the suppression. Increasing the level
663 // will reduce the noise level at the expense of a higher speech distortion.
671 virtual int set_level(Level level) = 0;
672 virtual Level level() const = 0;
674 // Returns the internally computed prior speech probability of current frame
675 // averaged over output channels. This is not supported in fixed point, for
676 // which |kUnsupportedFunctionError| is returned.
677 virtual float speech_probability() const = 0;
680 virtual ~NoiseSuppression() {}
683 // The voice activity detection (VAD) component analyzes the stream to
684 // determine if voice is present. A facility is also provided to pass in an
685 // external VAD decision.
687 // In addition to |stream_has_voice()| the VAD decision is provided through the
688 // |AudioFrame| passed to |ProcessStream()|. The |vad_activity_| member will be
689 // modified to reflect the current decision.
690 class VoiceDetection {
692 virtual int Enable(bool enable) = 0;
693 virtual bool is_enabled() const = 0;
695 // Returns true if voice is detected in the current frame. Should be called
696 // after |ProcessStream()|.
697 virtual bool stream_has_voice() const = 0;
699 // Some of the APM functionality requires a VAD decision. In the case that
700 // a decision is externally available for the current frame, it can be passed
701 // in here, before |ProcessStream()| is called.
703 // VoiceDetection does _not_ need to be enabled to use this. If it happens to
704 // be enabled, detection will be skipped for any frame in which an external
705 // VAD decision is provided.
706 virtual int set_stream_has_voice(bool has_voice) = 0;
708 // Specifies the likelihood that a frame will be declared to contain voice.
709 // A higher value makes it more likely that speech will not be clipped, at
710 // the expense of more noise being detected as voice.
718 virtual int set_likelihood(Likelihood likelihood) = 0;
719 virtual Likelihood likelihood() const = 0;
721 // Sets the |size| of the frames in ms on which the VAD will operate. Larger
722 // frames will improve detection accuracy, but reduce the frequency of
725 // This does not impact the size of frames passed to |ProcessStream()|.
726 virtual int set_frame_size_ms(int size) = 0;
727 virtual int frame_size_ms() const = 0;
730 virtual ~VoiceDetection() {}
732 } // namespace webrtc
734 #endif // WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AUDIO_PROCESSING_H_