media/audio/agc_audio_stream.h

   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_