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 66 namespace media { 67 68 template <typename AudioInterface> 69 class 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 95 // Query and cache the volume to avoid sending 0 as volume to AGC at the 96 // beginning of the audio stream, otherwise AGC will try to raise the 97 // volume from 0. 98 QueryAndStoreNewMicrophoneVolume(); 99 100 timer_.Start(FROM_HERE, 101 base::TimeDelta::FromMilliseconds(kIntervalBetweenVolumeUpdatesMs), 102 this, &AgcAudioStream::QueryAndStoreNewMicrophoneVolume); 103 } 104 105 // Stops the periodic timer which periodically checks and updates the 106 // current microphone volume level. 107 void StopAgc() { 108 DVLOG(1) << "StopAgc()"; 109 DCHECK(thread_checker_.CalledOnValidThread()); 110 if (timer_.IsRunning()) 111 timer_.Stop(); 112 } 113 114 // Stores a new microphone volume level by checking the audio input device. 115 // Called on the audio manager thread. 116 void UpdateAgcVolume() { 117 DCHECK(thread_checker_.CalledOnValidThread()); 118 119 if (!timer_.IsRunning()) 120 return; 121 122 // We take new volume samples once every second when the AGC is enabled. 123 // To ensure that a new setting has an immediate effect, the new volume 124 // setting is cached here. It will ensure that the next OnData() callback 125 // will contain a new valid volume level. If this approach was not taken, 126 // we could report invalid volume levels to the client for a time period 127 // of up to one second. 128 QueryAndStoreNewMicrophoneVolume(); 129 } 130 131 // Gets the latest stored volume level if AGC is enabled. 132 // Called at each capture callback on a real-time capture thread (platform 133 // dependent). 134 void GetAgcVolume(double* normalized_volume) { 135 base::AutoLock lock(lock_); 136 *normalized_volume = normalized_volume_; 137 } 138 139 private: 140 // Sets the automatic gain control (AGC) to on or off. When AGC is enabled, 141 // the microphone volume is queried periodically and the volume level can 142 // be read in each AudioInputCallback::OnData() callback and fed to the 143 // render-side AGC. User must call StartAgc() as well to start measuring 144 // the microphone level. 145 virtual void SetAutomaticGainControl(bool enabled) OVERRIDE { 146 DVLOG(1) << "SetAutomaticGainControl(enabled=" << enabled << ")"; 147 DCHECK(thread_checker_.CalledOnValidThread()); 148 agc_is_enabled_ = enabled; 149 } 150 151 // Gets the current automatic gain control state. 152 virtual bool GetAutomaticGainControl() OVERRIDE { 153 DCHECK(thread_checker_.CalledOnValidThread()); 154 return agc_is_enabled_; 155 } 156 157 // Takes a new microphone volume sample and stores it in |normalized_volume_|. 158 // Range is normalized to [0.0,1.0] or [0.0, 1.5] on Linux. 159 // This method is called periodically when AGC is enabled and always on the 160 // audio manager thread. We use it to read the current microphone level and 161 // to store it so it can be read by the main capture thread. By using this 162 // approach, we can avoid accessing audio hardware from a real-time audio 163 // thread and it leads to a more stable capture performance. 164 void QueryAndStoreNewMicrophoneVolume() { 165 DCHECK(thread_checker_.CalledOnValidThread()); 166 167 // Cach the maximum volume if this is the first time we ask for it. 168 if (max_volume_ == 0.0) 169 max_volume_ = static_cast<AudioInterface*>(this)->GetMaxVolume(); 170 171 // Retrieve the current volume level by asking the audio hardware. 172 // Range is normalized to [0.0,1.0] or [0.0, 1.5] on Linux. 173 if (max_volume_ != 0.0) { 174 double normalized_volume = 175 static_cast<AudioInterface*>(this)->GetVolume() / max_volume_; 176 base::AutoLock auto_lock(lock_); 177 normalized_volume_ = normalized_volume; 178 } 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
