src/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
  20 // An AudioInputController controls an AudioInputStream and records data
  21 // from this input stream. The two main methods are Record() and Close() and
  22 // they are both executed on the audio thread which is injected by the two
  23 // alternative factory methods, Create() or CreateLowLatency().
  24 //
  25 // All public methods of AudioInputController are non-blocking.
  26 //
  27 // Here is a state diagram for the AudioInputController:
  28 //
  29 //                    .-->  [ Closed / Error ]  <--.
  30 //                    |                            |
  31 //                    |                            |
  32 //               [ Created ]  ---------->  [ Recording ]
  33 //                    ^
  34 //                    |
  35 //              *[  Empty  ]
  36 //
  37 // * Initial state
  38 //
  39 // State sequences (assuming low-latency):
  40 //
  41 //  [Creating Thread]                     [Audio Thread]
  42 //
  43 //      User               AudioInputController               EventHandler
  44 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  45 // CrateLowLatency() ==>        DoCreate()
  46 //                   AudioManager::MakeAudioInputStream()
  47 //                        AudioInputStream::Open()
  48 //                                  .- - - - - - - - - - - - ->   OnError()
  49 //                          create the data timer
  50 //                                  .------------------------->  OnCreated()
  51 //                               kCreated
  52 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  53 // Record() ==>                 DoRecord()
  54 //                      AudioInputStream::Start()
  55 //                                  .------------------------->  OnRecording()
  56 //                          start the data timer
  57 //                              kRecording
  58 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  59 // Close() ==>                  DoClose()
  60 //                        delete the data timer
  61 //                           state_ = kClosed
  62 //                        AudioInputStream::Stop()
  63 //                        AudioInputStream::Close()
  64 //                          SyncWriter::Close()
  65 // Closure::Run() <-----------------.
  66 // (closure-task)
  67 //
  68 // The audio thread itself is owned by the AudioManager that the
  69 // AudioInputController holds a reference to.  When performing tasks on the
  70 // audio thread, the controller must not add or release references to the
  71 // AudioManager or itself (since it in turn holds a reference to the manager).
  72 //
  73 namespace media {
  74
  75 class UserInputMonitor;
  76
  77 class MEDIA_EXPORT AudioInputController
  78     : public base::RefCountedThreadSafe<AudioInputController>,
  79       public AudioInputStream::AudioInputCallback {
  80  public:
  81   // An event handler that receives events from the AudioInputController. The
  82   // following methods are all called on the audio thread.
  83   class MEDIA_EXPORT EventHandler {
  84    public:
  85     virtual void OnCreated(AudioInputController* controller) = 0;
  86     virtual void OnRecording(AudioInputController* controller) = 0;
  87     virtual void OnError(AudioInputController* controller) = 0;
  88     virtual void OnData(AudioInputController* controller, const uint8* data,
  89                         uint32 size) = 0;
  90
  91    protected:
  92     virtual ~EventHandler() {}
  93   };
  94
  95   // A synchronous writer interface used by AudioInputController for
  96   // synchronous writing.
  97   class SyncWriter {
  98    public:
  99     virtual ~SyncWriter() {}
 100
 101     // Notify the synchronous writer about the number of bytes in the
 102     // soundcard which has been recorded.
 103     virtual void UpdateRecordedBytes(uint32 bytes) = 0;
 104
 105     // Write certain amount of data from |data|. This method returns
 106     // number of written bytes.
 107     virtual uint32 Write(const void* data,
 108                          uint32 size,
 109                          double volume,
 110                          bool key_pressed) = 0;
 111
 112     // Close this synchronous writer.
 113     virtual void Close() = 0;
 114   };
 115
 116   // AudioInputController::Create() can use the currently registered Factory
 117   // to create the AudioInputController. Factory is intended for testing only.
 118   // |user_input_monitor| is used for typing detection and can be NULL.
 119   class Factory {
 120    public:
 121     virtual AudioInputController* Create(
 122         AudioManager* audio_manager,
 123         EventHandler* event_handler,
 124         AudioParameters params,
 125         UserInputMonitor* user_input_monitor) = 0;
 126
 127    protected:
 128     virtual ~Factory() {}
 129   };
 130
 131   // Factory method for creating an AudioInputController.
 132   // The audio device will be created on the audio thread, and when that is
 133   // done, the event handler will receive an OnCreated() call from that same
 134   // thread. |device_id| is the unique ID of the audio device to be opened.
 135   // |user_input_monitor| is used for typing detection and can be NULL.
 136   static scoped_refptr<AudioInputController> Create(
 137       AudioManager* audio_manager,
 138       EventHandler* event_handler,
 139       const AudioParameters& params,
 140       const std::string& device_id,
 141       UserInputMonitor* user_input_monitor);
 142
 143   // Sets the factory used by the static method Create(). AudioInputController
 144   // does not take ownership of |factory|. A value of NULL results in an
 145   // AudioInputController being created directly.
 146   static void set_factory_for_testing(Factory* factory) { factory_ = factory; }
 147   AudioInputStream* stream_for_testing() { return stream_; }
 148
 149   // Factory method for creating an AudioInputController for low-latency mode.
 150   // The audio device will be created on the audio thread, and when that is
 151   // done, the event handler will receive an OnCreated() call from that same
 152   // thread. |user_input_monitor| is used for typing detection and can be NULL.
 153   static scoped_refptr<AudioInputController> CreateLowLatency(
 154       AudioManager* audio_manager,
 155       EventHandler* event_handler,
 156       const AudioParameters& params,
 157       const std::string& device_id,
 158       // External synchronous writer for audio controller.
 159       SyncWriter* sync_writer,
 160       UserInputMonitor* user_input_monitor);
 161
 162   // Factory method for creating an AudioInputController for low-latency mode,
 163   // taking ownership of |stream|.  The stream will be opened on the audio
 164   // thread, and when that is done, the event handler will receive an
 165   // OnCreated() call from that same thread. |user_input_monitor| is used for
 166   // typing detection and can be NULL.
 167   static scoped_refptr<AudioInputController> CreateForStream(
 168       const scoped_refptr<base::MessageLoopProxy>& message_loop,
 169       EventHandler* event_handler,
 170       AudioInputStream* stream,
 171       // External synchronous writer for audio controller.
 172       SyncWriter* sync_writer,
 173       UserInputMonitor* user_input_monitor);
 174
 175   // Starts recording using the created audio input stream.
 176   // This method is called on the creator thread.
 177   virtual void Record();
 178
 179   // Closes the audio input stream. The state is changed and the resources
 180   // are freed on the audio thread. |closed_task| is then executed on the thread
 181   // that called Close().
 182   // Callbacks (EventHandler and SyncWriter) must exist until |closed_task|
 183   // is called.
 184   // It is safe to call this method more than once. Calls after the first one
 185   // will have no effect.
 186   // This method trampolines to the audio thread.
 187   virtual void Close(const base::Closure& closed_task);
 188
 189   // Sets the capture volume of the input stream. The value 0.0 corresponds
 190   // to muted and 1.0 to maximum volume.
 191   virtual void SetVolume(double volume);
 192
 193   // Sets the Automatic Gain Control (AGC) state of the input stream.
 194   // Changing the AGC state is not supported while recording is active.
 195   virtual void SetAutomaticGainControl(bool enabled);
 196
 197   // AudioInputCallback implementation. Threading details depends on the
 198   // device-specific implementation.
 199   virtual void OnData(AudioInputStream* stream, const uint8* src, uint32 size,
 200                       uint32 hardware_delay_bytes, double volume) OVERRIDE;
 201   virtual void OnClose(AudioInputStream* stream) OVERRIDE;
 202   virtual void OnError(AudioInputStream* stream) OVERRIDE;
 203
 204   bool LowLatencyMode() const { return sync_writer_ != NULL; }
 205
 206  protected:
 207   friend class base::RefCountedThreadSafe<AudioInputController>;
 208
 209   // Internal state of the source.
 210   enum State {
 211     kEmpty,
 212     kCreated,
 213     kRecording,
 214     kClosed,
 215     kError
 216   };
 217
 218   AudioInputController(EventHandler* handler,
 219                        SyncWriter* sync_writer,
 220                        UserInputMonitor* user_input_monitor);
 221   virtual ~AudioInputController();
 222
 223   // Methods called on the audio thread (owned by the AudioManager).
 224   void DoCreate(AudioManager* audio_manager, const AudioParameters& params,
 225                 const std::string& device_id);
 226   void DoCreateForStream(AudioInputStream* stream_to_control,
 227                          bool enable_nodata_timer);
 228   void DoRecord();
 229   void DoClose();
 230   void DoReportError();
 231   void DoSetVolume(double volume);
 232   void DoSetAutomaticGainControl(bool enabled);
 233
 234   // Method which ensures that OnError() is triggered when data recording
 235   // times out. Called on the audio thread.
 236   void DoCheckForNoData();
 237
 238   // Helper method that stops, closes, and NULL:s |*stream_|.
 239   // Signals event when done if the event is not NULL.
 240   void DoStopCloseAndClearStream(base::WaitableEvent* done);
 241
 242   void SetDataIsActive(bool enabled);
 243   bool GetDataIsActive();
 244
 245   // Gives access to the message loop of the creating thread.
 246   scoped_refptr<base::MessageLoopProxy> creator_loop_;
 247
 248   // The message loop of audio-manager thread that this object runs on.
 249   scoped_refptr<base::MessageLoopProxy> message_loop_;
 250
 251   // Contains the AudioInputController::EventHandler which receives state
 252   // notifications from this class.
 253   EventHandler* handler_;
 254
 255   // Pointer to the audio input stream object.
 256   AudioInputStream* stream_;
 257
 258   // |no_data_timer_| is used to call OnError() when we stop receiving
 259   // OnData() calls without an OnClose() call. This can occur
 260   // when an audio input device is unplugged whilst recording on Windows.
 261   // See http://crbug.com/79936 for details.
 262   // This member is only touched by the audio thread.
 263   scoped_ptr<base::Timer> no_data_timer_;
 264
 265   // This flag is used to signal that we are receiving OnData() calls, i.e,
 266   // that data is active. It can be touched by the audio thread and by the
 267   // low-level audio thread which calls OnData(). E.g. on Windows, the
 268   // low-level audio thread is called wasapi_capture_thread.
 269   base::subtle::Atomic32 data_is_active_;
 270
 271   // |state_| is written on the audio thread and is read on the hardware audio
 272   // thread. These operations need to be locked. But lock is not required for
 273   // reading on the audio input controller thread.
 274   State state_;
 275
 276   base::Lock lock_;
 277
 278   // SyncWriter is used only in low-latency mode for synchronous writing.
 279   SyncWriter* sync_writer_;
 280
 281   static Factory* factory_;
 282
 283   double max_volume_;
 284
 285   UserInputMonitor* user_input_monitor_;
 286
 287   size_t prev_key_down_count_;
 288
 289   DISALLOW_COPY_AND_ASSIGN(AudioInputController);
 290 };
 291
 292 }  // namespace media
 293
 294 #endif  // MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_