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 AgcAudioStream()74 AgcAudioStream() 75 : agc_is_enabled_(false), max_volume_(0.0), normalized_volume_(0.0) { 76 } 77 ~AgcAudioStream()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. StartAgc()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. StopAgc()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. UpdateAgcVolume()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). GetAgcVolume(double * normalized_volume)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. SetAutomaticGainControl(bool enabled)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. GetAutomaticGainControl()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. QueryAndStoreNewMicrophoneVolume()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