media/audio/audio_input_controller.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_AUDIO_INPUT_CONTROLLER_H_
   6 #define MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_
   7
   8 #include <string>
   9 #include "base/atomicops.h"
  10 #include "base/callback.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "base/memory/scoped_ptr.h"
  13 #include "base/synchronization/lock.h"
  14 #include "base/synchronization/waitable_event.h"
  15 #include "base/threading/thread.h"
  16 #include "base/timer/timer.h"
  17 #include "media/audio/audio_io.h"
  18 #include "media/audio/audio_manager_base.h"
  19 #include "media/audio/audio_parameters.h"
  20 #include "media/base/audio_bus.h"
  21
  22 // An AudioInputController controls an AudioInputStream and records data
  23 // from this input stream. The two main methods are Record() and Close() and
  24 // they are both executed on the audio thread which is injected by the two
  25 // alternative factory methods, Create() or CreateLowLatency().
  26 //
  27 // All public methods of AudioInputController are non-blocking.
  28 //
  29 // Here is a state diagram for the AudioInputController:
  30 //
  31 //                    .-->  [ Closed / Error ]  <--.
  32 //                    |                            |
  33 //                    |                            |
  34 //               [ Created ]  ---------->  [ Recording ]
  35 //                    ^
  36 //                    |
  37 //              *[  Empty  ]
  38 //
  39 // * Initial state
  40 //
  41 // State sequences (assuming low-latency):
  42 //
  43 //  [Creating Thread]                     [Audio Thread]
  44 //
  45 //      User               AudioInputController               EventHandler
  46 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  47 // CrateLowLatency() ==>        DoCreate()
  48 //                   AudioManager::MakeAudioInputStream()
  49 //                        AudioInputStream::Open()
  50 //                                  .- - - - - - - - - - - - ->   OnError()
  51 //                          create the data timer
  52 //                                  .------------------------->  OnCreated()
  53 //                               kCreated
  54 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  55 // Record() ==>                 DoRecord()
  56 //                      AudioInputStream::Start()
  57 //                                  .------------------------->  OnRecording()
  58 //                          start the data timer
  59 //                              kRecording
  60 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  61 // Close() ==>                  DoClose()
  62 //                        delete the data timer
  63 //                           state_ = kClosed
  64 //                        AudioInputStream::Stop()
  65 //                        AudioInputStream::Close()
  66 //                          SyncWriter::Close()
  67 // Closure::Run() <-----------------.
  68 // (closure-task)
  69 //
  70 // The audio thread itself is owned by the AudioManager that the
  71 // AudioInputController holds a reference to.  When performing tasks on the
  72 // audio thread, the controller must not add or release references to the
  73 // AudioManager or itself (since it in turn holds a reference to the manager).
  74 //
  75 namespace media {
  76
  77 // Only do power monitoring for non-mobile platforms to save resources.
  78 #if !defined(OS_ANDROID) && !defined(OS_IOS)
  79 #define AUDIO_POWER_MONITORING
  80 #endif
  81
  82 class UserInputMonitor;
  83
  84 class MEDIA_EXPORT AudioInputController
  85     : public base::RefCountedThreadSafe<AudioInputController>,
  86       public AudioInputStream::AudioInputCallback {
  87  public:
  88
  89   // Error codes to make native loggin more clear. These error codes are added
  90   // to generic error strings to provide a higher degree of details.
  91   // Changing these values can lead to problems when matching native debug
  92   // logs with the actual cause of error.
  93   enum ErrorCode {
  94     // An unspecified error occured.
  95     UNKNOWN_ERROR = 0,
  96
  97     // Failed to create an audio input stream.
  98     STREAM_CREATE_ERROR,  // = 1
  99
 100     // Failed to open an audio input stream.
 101     STREAM_OPEN_ERROR,  // = 2
 102
 103     // Native input stream reports an error. Exact reason differs between
 104     // platforms.
 105     STREAM_ERROR,  // = 3
 106
 107     // This can happen if a capture device has been removed or disabled.
 108     NO_DATA_ERROR,  // = 4
 109   };
 110
 111   // An event handler that receives events from the AudioInputController. The
 112   // following methods are all called on the audio thread.
 113   class MEDIA_EXPORT EventHandler {
 114    public:
 115     virtual void OnCreated(AudioInputController* controller) = 0;
 116     virtual void OnRecording(AudioInputController* controller) = 0;
 117     virtual void OnError(AudioInputController* controller,
 118                          ErrorCode error_code) = 0;
 119     virtual void OnData(AudioInputController* controller,
 120                         const AudioBus* data) = 0;
 121     virtual void OnLog(AudioInputController* controller,
 122                        const std::string& message) = 0;
 123
 124    protected:
 125     virtual ~EventHandler() {}
 126   };
 127
 128   // A synchronous writer interface used by AudioInputController for
 129   // synchronous writing.
 130   class SyncWriter {
 131    public:
 132     virtual ~SyncWriter() {}
 133
 134     // Notify the synchronous writer about the number of bytes in the
 135     // soundcard which has been recorded.
 136     virtual void UpdateRecordedBytes(uint32 bytes) = 0;
 137
 138     // Write certain amount of data from |data|.
 139     virtual void Write(const AudioBus* data,
 140                        double volume,
 141                        bool key_pressed) = 0;
 142
 143     // Close this synchronous writer.
 144     virtual void Close() = 0;
 145   };
 146
 147   // AudioInputController::Create() can use the currently registered Factory
 148   // to create the AudioInputController. Factory is intended for testing only.
 149   // |user_input_monitor| is used for typing detection and can be NULL.
 150   class Factory {
 151    public:
 152     virtual AudioInputController* Create(
 153         AudioManager* audio_manager,
 154         EventHandler* event_handler,
 155         AudioParameters params,
 156         UserInputMonitor* user_input_monitor) = 0;
 157
 158    protected:
 159     virtual ~Factory() {}
 160   };
 161
 162   // Factory method for creating an AudioInputController.
 163   // The audio device will be created on the audio thread, and when that is
 164   // done, the event handler will receive an OnCreated() call from that same
 165   // thread. |device_id| is the unique ID of the audio device to be opened.
 166   // |user_input_monitor| is used for typing detection and can be NULL.
 167   static scoped_refptr<AudioInputController> Create(
 168       AudioManager* audio_manager,
 169       EventHandler* event_handler,
 170       const AudioParameters& params,
 171       const std::string& device_id,
 172       UserInputMonitor* user_input_monitor);
 173
 174   // Sets the factory used by the static method Create(). AudioInputController
 175   // does not take ownership of |factory|. A value of NULL results in an
 176   // AudioInputController being created directly.
 177   static void set_factory_for_testing(Factory* factory) { factory_ = factory; }
 178   AudioInputStream* stream_for_testing() { return stream_; }
 179
 180   // Factory method for creating an AudioInputController for low-latency mode.
 181   // The audio device will be created on the audio thread, and when that is
 182   // done, the event handler will receive an OnCreated() call from that same
 183   // thread. |user_input_monitor| is used for typing detection and can be NULL.
 184   static scoped_refptr<AudioInputController> CreateLowLatency(
 185       AudioManager* audio_manager,
 186       EventHandler* event_handler,
 187       const AudioParameters& params,
 188       const std::string& device_id,
 189       // External synchronous writer for audio controller.
 190       SyncWriter* sync_writer,
 191       UserInputMonitor* user_input_monitor,
 192       const bool agc_is_enabled);
 193
 194   // Factory method for creating an AudioInputController with an existing
 195   // |stream| for low-latency mode, taking ownership of |stream|. The stream
 196   // will be opened on the audio thread, and when that is done, the event
 197   // handler will receive an OnCreated() call from that same thread.
 198   // |user_input_monitor| is used for typing detection and can be NULL.
 199   static scoped_refptr<AudioInputController> CreateForStream(
 200       const scoped_refptr<base::SingleThreadTaskRunner>& task_runner,
 201       EventHandler* event_handler,
 202       AudioInputStream* stream,
 203       // External synchronous writer for audio controller.
 204       SyncWriter* sync_writer,
 205       UserInputMonitor* user_input_monitor);
 206
 207   // Starts recording using the created audio input stream.
 208   // This method is called on the creator thread.
 209   virtual void Record();
 210
 211   // Closes the audio input stream. The state is changed and the resources
 212   // are freed on the audio thread. |closed_task| is then executed on the thread
 213   // that called Close().
 214   // Callbacks (EventHandler and SyncWriter) must exist until |closed_task|
 215   // is called.
 216   // It is safe to call this method more than once. Calls after the first one
 217   // will have no effect.
 218   // This method trampolines to the audio thread.
 219   virtual void Close(const base::Closure& closed_task);
 220
 221   // Sets the capture volume of the input stream. The value 0.0 corresponds
 222   // to muted and 1.0 to maximum volume.
 223   virtual void SetVolume(double volume);
 224
 225   // AudioInputCallback implementation. Threading details depends on the
 226   // device-specific implementation.
 227   void OnData(AudioInputStream* stream,
 228               const AudioBus* source,
 229               uint32 hardware_delay_bytes,
 230               double volume) override;
 231   void OnError(AudioInputStream* stream) override;
 232
 233   bool SharedMemoryAndSyncSocketMode() const { return sync_writer_ != NULL; }
 234
 235  protected:
 236   friend class base::RefCountedThreadSafe<AudioInputController>;
 237
 238   // Internal state of the source.
 239   enum State {
 240     CREATED,
 241     RECORDING,
 242     CLOSED
 243   };
 244
 245 #if defined(AUDIO_POWER_MONITORING)
 246   // Used to log a silence report (see OnData).
 247   // Elements in this enum should not be deleted or rearranged; the only
 248   // permitted operation is to add new elements before SILENCE_STATE_MAX and
 249   // update SILENCE_STATE_MAX.
 250   // Possible silence state transitions:
 251   //           SILENCE_STATE_AUDIO_AND_SILENCE
 252   //               ^                  ^
 253   // SILENCE_STATE_ONLY_AUDIO   SILENCE_STATE_ONLY_SILENCE
 254   //               ^                  ^
 255   //            SILENCE_STATE_NO_MEASUREMENT
 256   enum SilenceState {
 257     SILENCE_STATE_NO_MEASUREMENT = 0,
 258     SILENCE_STATE_ONLY_AUDIO = 1,
 259     SILENCE_STATE_ONLY_SILENCE = 2,
 260     SILENCE_STATE_AUDIO_AND_SILENCE = 3,
 261     SILENCE_STATE_MAX = SILENCE_STATE_AUDIO_AND_SILENCE
 262   };
 263 #endif
 264
 265   AudioInputController(EventHandler* handler,
 266                        SyncWriter* sync_writer,
 267                        UserInputMonitor* user_input_monitor,
 268                        const bool agc_is_enabled);
 269   ~AudioInputController() override;
 270
 271   // Methods called on the audio thread (owned by the AudioManager).
 272   void DoCreate(AudioManager* audio_manager,
 273                 const AudioParameters& params,
 274                 const std::string& device_id);
 275   void DoCreateForLowLatency(AudioManager* audio_manager,
 276                              const AudioParameters& params,
 277                              const std::string& device_id);
 278   void DoCreateForStream(AudioInputStream* stream_to_control);
 279   void DoRecord();
 280   void DoClose();
 281   void DoReportError();
 282   void DoSetVolume(double volume);
 283   void DoOnData(scoped_ptr<AudioBus> data);
 284   void DoLogAudioLevels(float level_dbfs, int microphone_volume_percent);
 285
 286   // Method to check if we get recorded data after a stream was started,
 287   // and log the result to UMA.
 288   void FirstCheckForNoData();
 289
 290   // Method which ensures that OnError() is triggered when data recording
 291   // times out. Called on the audio thread.
 292   void DoCheckForNoData();
 293
 294   // Helper method that stops, closes, and NULL:s |*stream_|.
 295   void DoStopCloseAndClearStream();
 296
 297   void SetDataIsActive(bool enabled);
 298   bool GetDataIsActive();
 299
 300 #if defined(AUDIO_POWER_MONITORING)
 301   // Updates the silence state, see enum SilenceState above for state
 302   // transitions.
 303   void UpdateSilenceState(bool silence);
 304
 305   // Logs the silence state as UMA stat.
 306   void LogSilenceState(SilenceState value);
 307 #endif
 308
 309   // Gives access to the task runner of the creating thread.
 310   scoped_refptr<base::SingleThreadTaskRunner> creator_task_runner_;
 311
 312   // The task runner of audio-manager thread that this object runs on.
 313   scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
 314
 315   // Contains the AudioInputController::EventHandler which receives state
 316   // notifications from this class.
 317   EventHandler* handler_;
 318
 319   // Pointer to the audio input stream object.
 320   AudioInputStream* stream_;
 321
 322   // |no_data_timer_| is used to call OnError() when we stop receiving
 323   // OnData() calls. This can occur when an audio input device is unplugged
 324   // whilst recording on Windows.
 325   // See http://crbug.com/79936 for details.
 326   // This member is only touched by the audio thread.
 327   scoped_ptr<base::Timer> no_data_timer_;
 328
 329   // This flag is used to signal that we are receiving OnData() calls, i.e,
 330   // that data is active. It can be touched by the audio thread and by the
 331   // low-level audio thread which calls OnData(). E.g. on Windows, the
 332   // low-level audio thread is called wasapi_capture_thread.
 333   base::subtle::Atomic32 data_is_active_;
 334
 335   // |state_| is written on the audio thread and is read on the hardware audio
 336   // thread. These operations need to be locked. But lock is not required for
 337   // reading on the audio input controller thread.
 338   State state_;
 339
 340   base::Lock lock_;
 341
 342   // SyncWriter is used only in low-latency mode for synchronous writing.
 343   SyncWriter* sync_writer_;
 344
 345   static Factory* factory_;
 346
 347   double max_volume_;
 348
 349   UserInputMonitor* user_input_monitor_;
 350
 351   const bool agc_is_enabled_;
 352
 353 #if defined(AUDIO_POWER_MONITORING)
 354   // Enabled in DoCrete() but not in DoCreateForStream().
 355   bool power_measurement_is_enabled_;
 356
 357   // Updated each time a power measurement is performed.
 358   base::TimeTicks last_audio_level_log_time_;
 359
 360   // Whether the silence state should sent as UMA stat.
 361   bool log_silence_state_;
 362
 363   // The silence report sent as UMA stat at the end of a session.
 364   SilenceState silence_state_;
 365 #endif
 366
 367   size_t prev_key_down_count_;
 368
 369   // Time when a low-latency stream is created.
 370   base::TimeTicks low_latency_create_time_;
 371
 372   DISALLOW_COPY_AND_ASSIGN(AudioInputController);
 373 };
 374
 375 }  // namespace media
 376
 377 #endif  // MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_