Note: We no longer publish the latest version of our code here. We primarily use a kumc-bmi github organization. The heron ETL repository, in particular, is not public. Peers in the informatics community should see MultiSiteDev for details on requesting access.

source: webrtc/webrtc/modules/audio_processing/include/audio_processing.h @ 0:4bda6873e34c

pub_scrub_3792 tip
Last change on this file since 0:4bda6873e34c was 0:4bda6873e34c, checked in by Michael Prittie <mprittie@…>, 6 years ago

Scrubbed password for publication.

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