agc_audio_stream.h 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202
  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. #ifndef MEDIA_AUDIO_AGC_AUDIO_STREAM_H_
  5. #define MEDIA_AUDIO_AGC_AUDIO_STREAM_H_
  6. #include <atomic>
  7. #include "base/logging.h"
  8. #include "base/threading/thread_checker.h"
  9. #include "base/timer/timer.h"
  10. #include "media/audio/audio_io.h"
  11. // The template based AgcAudioStream implements platform-independent parts
  12. // of the AudioInterface interface. Supported interfaces to pass as
  13. // AudioInterface are AudioIntputStream and AudioOutputStream. Each platform-
  14. // dependent implementation should derive from this class.
  15. //
  16. // Usage example (on Windows):
  17. //
  18. // class WASAPIAudioInputStream : public AgcAudioStream<AudioInputStream> {
  19. // public:
  20. // WASAPIAudioInputStream();
  21. // ...
  22. // };
  23. //
  24. // Call flow example:
  25. //
  26. // 1) User creates AgcAudioStream<AudioInputStream>
  27. // 2) User calls AudioInputStream::SetAutomaticGainControl(true) =>
  28. // AGC usage is now initialized but not yet started.
  29. // 3) User calls AudioInputStream::Start() => implementation calls
  30. // AgcAudioStream<AudioInputStream>::StartAgc() which detects that AGC
  31. // is enabled and then starts the periodic AGC timer.
  32. // 4) Microphone volume samples are now taken and included in all
  33. // AudioInputCallback::OnData() callbacks.
  34. // 5) User calls AudioInputStream::Stop() => implementation calls
  35. // AgcAudioStream<AudioInputStream>::StopAgc() which stops the timer.
  36. //
  37. // Note that, calling AudioInputStream::SetAutomaticGainControl(false) while
  38. // AGC measurements are active will not have an effect until StopAgc(),
  39. // StartAgc() are called again since SetAutomaticGainControl() only sets a
  40. // a state.
  41. //
  42. // Calling SetAutomaticGainControl(true) enables the AGC and StartAgc() starts
  43. // a periodic timer which calls QueryAndStoreNewMicrophoneVolume()
  44. // approximately once every second. QueryAndStoreNewMicrophoneVolume() asks
  45. // the actual microphone about its current volume level. This value is
  46. // normalized and stored so it can be read by GetAgcVolume() when the real-time
  47. // audio thread needs the value. The main idea behind this scheme is to avoid
  48. // accessing the audio hardware from the real-time audio thread and to ensure
  49. // that we don't take new microphone-level samples too often (~1 Hz is a
  50. // suitable compromise). The timer will be active until StopAgc() is called.
  51. //
  52. // This class should be created and destroyed on the audio manager thread and
  53. // a thread checker is added to ensure that this is the case (uses DCHECK).
  54. // All methods except GetAgcVolume() should be called on the creating thread
  55. // as well to ensure that thread safety is maintained. It will also guarantee
  56. // that the periodic timer runs on the audio manager thread.
  57. // |normalized_volume_|, which is updated by QueryAndStoreNewMicrophoneVolume()
  58. // and read in GetAgcVolume(), is atomic to ensure that it can be accessed from
  59. // any real-time audio thread that needs it to update the its AGC volume.
  60. namespace media {
  61. template <typename AudioInterface>
  62. class MEDIA_EXPORT AgcAudioStream : public AudioInterface {
  63. public:
  64. // Time between two successive timer events.
  65. static constexpr base::TimeDelta kIntervalBetweenVolumeUpdates =
  66. base::Milliseconds(1000);
  67. AgcAudioStream()
  68. : agc_is_enabled_(false), max_volume_(0.0), normalized_volume_(0.0) {
  69. }
  70. AgcAudioStream(const AgcAudioStream&) = delete;
  71. AgcAudioStream& operator=(const AgcAudioStream&) = delete;
  72. virtual ~AgcAudioStream() {
  73. DCHECK(thread_checker_.CalledOnValidThread());
  74. }
  75. protected:
  76. // Starts the periodic timer which periodically checks and updates the
  77. // current microphone volume level.
  78. // The timer is only started if AGC mode is first enabled using the
  79. // SetAutomaticGainControl() method.
  80. void StartAgc() {
  81. DCHECK(thread_checker_.CalledOnValidThread());
  82. if (!agc_is_enabled_ || timer_.IsRunning())
  83. return;
  84. max_volume_ = static_cast<AudioInterface*>(this)->GetMaxVolume();
  85. if (max_volume_ <= 0) {
  86. DLOG(WARNING) << "Failed to get max volume from hardware. Won't provide "
  87. << "normalized volume.";
  88. return;
  89. }
  90. // Query and cache the volume to avoid sending 0 as volume to AGC at the
  91. // beginning of the audio stream, otherwise AGC will try to raise the
  92. // volume from 0.
  93. QueryAndStoreNewMicrophoneVolume();
  94. timer_.Start(FROM_HERE, kIntervalBetweenVolumeUpdates, this,
  95. &AgcAudioStream::QueryAndStoreNewMicrophoneVolume);
  96. }
  97. // Stops the periodic timer which periodically checks and updates the
  98. // current microphone volume level.
  99. void StopAgc() {
  100. DCHECK(thread_checker_.CalledOnValidThread());
  101. if (timer_.IsRunning())
  102. timer_.Stop();
  103. }
  104. // Stores a new microphone volume level by checking the audio input device.
  105. // Called on the audio manager thread.
  106. void UpdateAgcVolume() {
  107. DCHECK(thread_checker_.CalledOnValidThread());
  108. if (!timer_.IsRunning())
  109. return;
  110. // We take new volume samples once every second when the AGC is enabled.
  111. // To ensure that a new setting has an immediate effect, the new volume
  112. // setting is cached here. It will ensure that the next OnData() callback
  113. // will contain a new valid volume level. If this approach was not taken,
  114. // we could report invalid volume levels to the client for a time period
  115. // of up to one second.
  116. QueryAndStoreNewMicrophoneVolume();
  117. }
  118. // Gets the latest stored volume level if AGC is enabled.
  119. // Called at each capture callback on a real-time capture thread (platform
  120. // dependent).
  121. void GetAgcVolume(double* normalized_volume) {
  122. *normalized_volume = normalized_volume_.load(std::memory_order_relaxed);
  123. }
  124. // Gets the current automatic gain control state.
  125. bool GetAutomaticGainControl() override {
  126. DCHECK(thread_checker_.CalledOnValidThread());
  127. return agc_is_enabled_;
  128. }
  129. private:
  130. // Sets the automatic gain control (AGC) to on or off. When AGC is enabled,
  131. // the microphone volume is queried periodically and the volume level can
  132. // be read in each AudioInputCallback::OnData() callback and fed to the
  133. // render-side AGC. User must call StartAgc() as well to start measuring
  134. // the microphone level.
  135. bool SetAutomaticGainControl(bool enabled) override {
  136. DVLOG(1) << "SetAutomaticGainControl(enabled=" << enabled << ")";
  137. DCHECK(thread_checker_.CalledOnValidThread());
  138. agc_is_enabled_ = enabled;
  139. return true;
  140. }
  141. // Takes a new microphone volume sample and stores it in |normalized_volume_|.
  142. // Range is normalized to [0.0,1.0] or [0.0, 1.5] on Linux.
  143. // This method is called periodically when AGC is enabled and always on the
  144. // audio manager thread. We use it to read the current microphone level and
  145. // to store it so it can be read by the main capture thread. By using this
  146. // approach, we can avoid accessing audio hardware from a real-time audio
  147. // thread and it leads to a more stable capture performance.
  148. void QueryAndStoreNewMicrophoneVolume() {
  149. DCHECK(thread_checker_.CalledOnValidThread());
  150. DCHECK_GT(max_volume_, 0.0);
  151. // Retrieve the current volume level by asking the audio hardware.
  152. // Range is normalized to [0.0,1.0] or [0.0, 1.5] on Linux.
  153. double normalized_volume =
  154. static_cast<AudioInterface*>(this)->GetVolume() / max_volume_;
  155. normalized_volume_.store(normalized_volume, std::memory_order_relaxed);
  156. }
  157. // Ensures that this class is created and destroyed on the same thread.
  158. base::ThreadChecker thread_checker_;
  159. // Repeating timer which cancels itself when it goes out of scope.
  160. // Used to check the microphone volume periodically.
  161. base::RepeatingTimer timer_;
  162. // True when automatic gain control is enabled, false otherwise.
  163. bool agc_is_enabled_;
  164. // Stores the maximum volume which is used for normalization to a volume
  165. // range of [0.0, 1.0].
  166. double max_volume_;
  167. // Contains last result of internal call to GetVolume(). We save resources
  168. // by not querying the capture volume for each callback. The range is
  169. // normalized to [0.0, 1.0].
  170. std::atomic<double> normalized_volume_;
  171. };
  172. } // namespace media
  173. #endif // MEDIA_AUDIO_AGC_AUDIO_STREAM_H_