Home | History | Annotate | Download | only in audio 
      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   }
     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