agc_audio_stream.h revision 90dce4d38c5ff5333bea97d859d4e484e27edf0c
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.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 OnTimer() approximately once every second. 48// OnTimer() calls the QueryAndStoreNewMicrophoneVolume() method which 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 DVLOG(1) << __FUNCTION__; 77 } 78 79 virtual ~AgcAudioStream() { 80 DCHECK(thread_checker_.CalledOnValidThread()); 81 DVLOG(1) << __FUNCTION__; 82 } 83 84 protected: 85 // Starts the periodic timer which periodically checks and updates the 86 // current microphone volume level. 87 // The timer is only started if AGC mode is first enabled using the 88 // SetAutomaticGainControl() method. 89 void StartAgc() { 90 DVLOG(1) << "StartAgc()"; 91 DCHECK(thread_checker_.CalledOnValidThread()); 92 if (!agc_is_enabled_ || timer_.IsRunning()) 93 return; 94 timer_.Start(FROM_HERE, 95 base::TimeDelta::FromMilliseconds(kIntervalBetweenVolumeUpdatesMs), 96 this, &AgcAudioStream::OnTimer); 97 } 98 99 // Stops the periodic timer which periodically checks and updates the 100 // current microphone volume level. 101 void StopAgc() { 102 DVLOG(1) << "StopAgc()"; 103 DCHECK(thread_checker_.CalledOnValidThread()); 104 if (timer_.IsRunning()) 105 timer_.Stop(); 106 } 107 108 // Stores a new microphone volume level by checking the audio input device. 109 // Called on the audio manager thread. 110 void UpdateAgcVolume() { 111 DCHECK(thread_checker_.CalledOnValidThread()); 112 113 // We take new volume samples once every second when the AGC is enabled. 114 // To ensure that a new setting has an immediate effect, the new volume 115 // setting is cached here. It will ensure that the next OnData() callback 116 // will contain a new valid volume level. If this approach was not taken, 117 // we could report invalid volume levels to the client for a time period 118 // of up to one second. 119 QueryAndStoreNewMicrophoneVolume(); 120 } 121 122 // Gets the latest stored volume level if AGC is enabled. 123 // Called at each capture callback on a real-time capture thread (platform 124 // dependent). 125 void GetAgcVolume(double* normalized_volume) { 126 base::AutoLock lock(lock_); 127 *normalized_volume = normalized_volume_; 128 } 129 130 private: 131 // Sets the automatic gain control (AGC) to on or off. When AGC is enabled, 132 // the microphone volume is queried periodically and the volume level can 133 // be read in each AudioInputCallback::OnData() callback and fed to the 134 // render-side AGC. User must call StartAgc() as well to start measuring 135 // the microphone level. 136 virtual void SetAutomaticGainControl(bool enabled) OVERRIDE { 137 DVLOG(1) << "SetAutomaticGainControl(enabled=" << enabled << ")"; 138 DCHECK(thread_checker_.CalledOnValidThread()); 139 agc_is_enabled_ = enabled; 140 } 141 142 // Gets the current automatic gain control state. 143 virtual bool GetAutomaticGainControl() OVERRIDE { 144 DCHECK(thread_checker_.CalledOnValidThread()); 145 return agc_is_enabled_; 146 } 147 148 // Takes a new microphone volume sample and stores it in |normalized_volume_|. 149 // Range is normalized to [0.0,1.0] or [0.0, 1.5] on Linux. 150 void QueryAndStoreNewMicrophoneVolume() { 151 DCHECK(thread_checker_.CalledOnValidThread()); 152 153 // Avoid updating the volume member if AGC is not running. 154 if (!timer_.IsRunning()) 155 return; 156 157 // Cach the maximum volume if this is the first time we ask for it. 158 if (max_volume_ == 0.0) 159 max_volume_ = static_cast<AudioInterface*>(this)->GetMaxVolume(); 160 161 // Retrieve the current volume level by asking the audio hardware. 162 // Range is normalized to [0.0,1.0] or [0.0, 1.5] on Linux. 163 if (max_volume_ != 0.0) { 164 double normalized_volume = 165 static_cast<AudioInterface*>(this)->GetVolume() / max_volume_; 166 base::AutoLock auto_lock(lock_); 167 normalized_volume_ = normalized_volume; 168 } 169 } 170 171 // This method is called periodically when AGC is enabled and always on the 172 // audio manager thread. We use it to read the current microphone level and 173 // to store it so it can be read by the main capture thread. By using this 174 // approach, we can avoid accessing audio hardware from a real-time audio 175 // thread and it leads to a more stable capture performance. 176 void OnTimer() { 177 DCHECK(thread_checker_.CalledOnValidThread()); 178 QueryAndStoreNewMicrophoneVolume(); 179 } 180 181 // Ensures that this class is created and destroyed on the same thread. 182 base::ThreadChecker thread_checker_; 183 184 // Repeating timer which cancels itself when it goes out of scope. 185 // Used to check the microphone volume periodically. 186 base::RepeatingTimer<AgcAudioStream<AudioInterface> > timer_; 187 188 // True when automatic gain control is enabled, false otherwise. 189 bool agc_is_enabled_; 190 191 // Stores the maximum volume which is used for normalization to a volume 192 // range of [0.0, 1.0]. 193 double max_volume_; 194 195 // Contains last result of internal call to GetVolume(). We save resources 196 // by not querying the capture volume for each callback. Guarded by |lock_|. 197 // The range is normalized to [0.0, 1.0]. 198 double normalized_volume_; 199 200 // Protects |normalized_volume_| . 201 base::Lock lock_; 202 203 DISALLOW_COPY_AND_ASSIGN(AgcAudioStream<AudioInterface>); 204}; 205 206} // namespace media 207 208#endif // MEDIA_AUDIO_AGC_AUDIO_STREAM_H_ 209