1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef MEDIA_AUDIO_AGC_AUDIO_STREAM_H_
6#define MEDIA_AUDIO_AGC_AUDIO_STREAM_H_
7
8#include "base/logging.h"
9#include "base/memory/scoped_ptr.h"
10#include "base/synchronization/lock.h"
11#include "base/threading/thread_checker.h"
12#include "base/timer/timer.h"
13#include "media/audio/audio_io.h"
14
15// The template based AgcAudioStream implements platform-independent parts
16// of the AudioInterface interface. Supported interfaces to pass as
17// AudioInterface are AudioIntputStream and AudioOutputStream. Each platform-
18// dependent implementation should derive from this class.
19//
20// Usage example (on Windows):
21//
22//  class WASAPIAudioInputStream : public AgcAudioStream<AudioInputStream> {
23//   public:
24//    WASAPIAudioInputStream();
25//    ...
26//  };
27//
28// Call flow example:
29//
30//   1) User creates AgcAudioStream<AudioInputStream>
31//   2) User calls AudioInputStream::SetAutomaticGainControl(true) =>
32//      AGC usage is now initialized but not yet started.
33//   3) User calls AudioInputStream::Start() => implementation calls
34//      AgcAudioStream<AudioInputStream>::StartAgc() which detects that AGC
35//      is enabled and then starts the periodic AGC timer.
36//   4) Microphone volume samples are now taken and included in all
37//      AudioInputCallback::OnData() callbacks.
38//   5) User calls AudioInputStream::Stop() => implementation calls
39//      AgcAudioStream<AudioInputStream>::StopAgc() which stops the timer.
40//
41// Note that, calling AudioInputStream::SetAutomaticGainControl(false) while
42// AGC measurements are active will not have an effect until StopAgc(),
43// StartAgc() are called again since SetAutomaticGainControl() only sets a
44// a state.
45//
46// Calling SetAutomaticGainControl(true) enables the AGC and StartAgc() starts
47// a periodic timer which calls QueryAndStoreNewMicrophoneVolume()
48// approximately once every second. QueryAndStoreNewMicrophoneVolume() asks
49// the actual microphone about its current volume level. This value is
50// normalized and stored so it can be read by GetAgcVolume() when the real-time
51// audio thread needs the value. The main idea behind this scheme is to avoid
52// accessing the audio hardware from the real-time audio thread and to ensure
53// that we don't take new microphone-level samples too often (~1 Hz is a
54// suitable compromise). The timer will be active until StopAgc() is called.
55//
56// This class should be created and destroyed on the audio manager thread and
57// a thread checker is added to ensure that this is the case (uses DCHECK).
58// All methods except GetAgcVolume() should be called on the creating thread
59// as well to ensure that thread safety is maintained. It will also guarantee
60// that the periodic timer runs on the audio manager thread.
61// |normalized_volume_|, which is updated by QueryAndStoreNewMicrophoneVolume()
62// and read in GetAgcVolume(), is protected by a lock to ensure that it can
63// be accessed from any real-time audio thread that needs it to update the its
64// AGC volume.
65
66namespace media {
67
68template <typename AudioInterface>
69class MEDIA_EXPORT AgcAudioStream : public AudioInterface {
70 public:
71  // Time between two successive timer events.
72  static const int kIntervalBetweenVolumeUpdatesMs = 1000;
73
74  AgcAudioStream()
75      : agc_is_enabled_(false), max_volume_(0.0), normalized_volume_(0.0) {
76  }
77
78  virtual ~AgcAudioStream() {
79    DCHECK(thread_checker_.CalledOnValidThread());
80  }
81
82 protected:
83  // Starts the periodic timer which periodically checks and updates the
84  // current microphone volume level.
85  // The timer is only started if AGC mode is first enabled using the
86  // SetAutomaticGainControl() method.
87  void StartAgc() {
88    DCHECK(thread_checker_.CalledOnValidThread());
89    if (!agc_is_enabled_ || timer_.IsRunning())
90      return;
91
92    // Query and cache the volume to avoid sending 0 as volume to AGC at the
93    // beginning of the audio stream, otherwise AGC will try to raise the
94    // volume from 0.
95    QueryAndStoreNewMicrophoneVolume();
96
97    timer_.Start(FROM_HERE,
98        base::TimeDelta::FromMilliseconds(kIntervalBetweenVolumeUpdatesMs),
99        this, &AgcAudioStream::QueryAndStoreNewMicrophoneVolume);
100  }
101
102  // Stops the periodic timer which periodically checks and updates the
103  // current microphone volume level.
104  void StopAgc() {
105    DCHECK(thread_checker_.CalledOnValidThread());
106    if (timer_.IsRunning())
107      timer_.Stop();
108  }
109
110  // Stores a new microphone volume level by checking the audio input device.
111  // Called on the audio manager thread.
112  void UpdateAgcVolume() {
113    DCHECK(thread_checker_.CalledOnValidThread());
114
115    if (!timer_.IsRunning())
116      return;
117
118    // We take new volume samples once every second when the AGC is enabled.
119    // To ensure that a new setting has an immediate effect, the new volume
120    // setting is cached here. It will ensure that the next OnData() callback
121    // will contain a new valid volume level. If this approach was not taken,
122    // we could report invalid volume levels to the client for a time period
123    // of up to one second.
124    QueryAndStoreNewMicrophoneVolume();
125  }
126
127  // Gets the latest stored volume level if AGC is enabled.
128  // Called at each capture callback on a real-time capture thread (platform
129  // dependent).
130  void GetAgcVolume(double* normalized_volume) {
131    base::AutoLock lock(lock_);
132    *normalized_volume = normalized_volume_;
133  }
134
135 private:
136  // Sets the automatic gain control (AGC) to on or off. When AGC is enabled,
137  // the microphone volume is queried periodically and the volume level can
138  // be read in each AudioInputCallback::OnData() callback and fed to the
139  // render-side AGC. User must call StartAgc() as well to start measuring
140  // the microphone level.
141  virtual void SetAutomaticGainControl(bool enabled) OVERRIDE {
142    DVLOG(1) << "SetAutomaticGainControl(enabled=" << enabled << ")";
143    DCHECK(thread_checker_.CalledOnValidThread());
144    agc_is_enabled_ = enabled;
145  }
146
147  // Gets the current automatic gain control state.
148  virtual bool GetAutomaticGainControl() OVERRIDE {
149    DCHECK(thread_checker_.CalledOnValidThread());
150    return agc_is_enabled_;
151  }
152
153  // Takes a new microphone volume sample and stores it in |normalized_volume_|.
154  // Range is normalized to [0.0,1.0] or [0.0, 1.5] on Linux.
155  // This method is called periodically when AGC is enabled and always on the
156  // audio manager thread. We use it to read the current microphone level and
157  // to store it so it can be read by the main capture thread. By using this
158  // approach, we can avoid accessing audio hardware from a real-time audio
159  // thread and it leads to a more stable capture performance.
160  void QueryAndStoreNewMicrophoneVolume() {
161    DCHECK(thread_checker_.CalledOnValidThread());
162
163    // Cach the maximum volume if this is the first time we ask for it.
164    if (max_volume_ == 0.0)
165      max_volume_ = static_cast<AudioInterface*>(this)->GetMaxVolume();
166
167    // Retrieve the current volume level by asking the audio hardware.
168    // Range is normalized to [0.0,1.0] or [0.0, 1.5] on Linux.
169    if (max_volume_ != 0.0) {
170      double normalized_volume =
171          static_cast<AudioInterface*>(this)->GetVolume() / max_volume_;
172      base::AutoLock auto_lock(lock_);
173      normalized_volume_ = normalized_volume;
174    }
175  }
176
177  // Ensures that this class is created and destroyed on the same thread.
178  base::ThreadChecker thread_checker_;
179
180  // Repeating timer which cancels itself when it goes out of scope.
181  // Used to check the microphone volume periodically.
182  base::RepeatingTimer<AgcAudioStream<AudioInterface> > timer_;
183
184  // True when automatic gain control is enabled, false otherwise.
185  bool agc_is_enabled_;
186
187  // Stores the maximum volume which is used for normalization to a volume
188  // range of [0.0, 1.0].
189  double max_volume_;
190
191  // Contains last result of internal call to GetVolume(). We save resources
192  // by not querying the capture volume for each callback. Guarded by |lock_|.
193  // The range is normalized to [0.0, 1.0].
194  double normalized_volume_;
195
196  // Protects |normalized_volume_| .
197  base::Lock lock_;
198
199  DISALLOW_COPY_AND_ASSIGN(AgcAudioStream<AudioInterface>);
200};
201
202}  // namespace media
203
204#endif  // MEDIA_AUDIO_AGC_AUDIO_STREAM_H_
205