media/audio/audio_input_device.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 // Low-latency audio capturing class utilizing audio input stream provided
   6 // by a server (browser) process by use of an IPC interface.
   7 //
   8 // Relationship of classes:
   9 //
  10 //  AudioInputController                 AudioInputDevice
  11 //           ^                                  ^
  12 //           |                                  |
  13 //           v                  IPC             v
  14 // AudioInputRendererHost  <----------->  AudioInputIPC
  15 //           ^                            (AudioInputMessageFilter)
  16 //           |
  17 //           v
  18 // AudioInputDeviceManager
  19 //
  20 // Transportation of audio samples from the browser to the render process
  21 // is done by using shared memory in combination with a SyncSocket.
  22 // The AudioInputDevice user registers an AudioInputDevice::CaptureCallback by
  23 // calling Initialize().  The callback will be called with recorded audio from
  24 // the underlying audio layers.
  25 // The session ID is used by the AudioInputRendererHost to start the device
  26 // referenced by this ID.
  27 //
  28 // State sequences:
  29 //
  30 // Start -> InitializeOnIOThread -> CreateStream ->
  31 //       <- OnStreamCreated <-
  32 //       -> StartOnIOThread -> PlayStream ->
  33 //
  34 //
  35 // AudioInputDevice::Capture => low latency audio transport on audio thread =>
  36 //                               |
  37 // Stop --> ShutDownOnIOThread ------>  CloseStream -> Close
  38 //
  39 // This class depends on two threads to function:
  40 //
  41 // 1. An IO thread.
  42 //    This thread is used to asynchronously process Start/Stop etc operations
  43 //    that are available via the public interface.  The public methods are
  44 //    asynchronous and simply post a task to the IO thread to actually perform
  45 //    the work.
  46 // 2. Audio transport thread.
  47 //    Responsible for calling the CaptureCallback and feed audio samples from
  48 //    the server side audio layer using a socket and shared memory.
  49 //
  50 // Implementation notes:
  51 // - The user must call Stop() before deleting the class instance.
  52
  53 #ifndef MEDIA_AUDIO_AUDIO_INPUT_DEVICE_H_
  54 #define MEDIA_AUDIO_AUDIO_INPUT_DEVICE_H_
  55
  56 #include <string>
  57
  58 #include "base/basictypes.h"
  59 #include "base/compiler_specific.h"
  60 #include "base/memory/scoped_ptr.h"
  61 #include "base/memory/shared_memory.h"
  62 #include "media/audio/audio_device_thread.h"
  63 #include "media/audio/audio_input_ipc.h"
  64 #include "media/audio/audio_parameters.h"
  65 #include "media/audio/scoped_task_runner_observer.h"
  66 #include "media/base/audio_capturer_source.h"
  67 #include "media/base/media_export.h"
  68
  69 namespace media {
  70
  71 // TODO(henrika): This class is based on the AudioOutputDevice class and it has
  72 // many components in common. Investigate potential for re-factoring.
  73 // See http://crbug.com/179597.
  74 // TODO(henrika): Add support for event handling (e.g. OnStateChanged,
  75 // OnCaptureStopped etc.) and ensure that we can deliver these notifications
  76 // to any clients using this class.
  77 class MEDIA_EXPORT AudioInputDevice
  78     : NON_EXPORTED_BASE(public AudioCapturerSource),
  79       NON_EXPORTED_BASE(public AudioInputIPCDelegate),
  80       NON_EXPORTED_BASE(public ScopedTaskRunnerObserver) {
  81  public:
  82   // NOTE: Clients must call Initialize() before using.
  83   AudioInputDevice(
  84       scoped_ptr<AudioInputIPC> ipc,
  85       const scoped_refptr<base::SingleThreadTaskRunner>& io_task_runner);
  86
  87   // AudioCapturerSource implementation.
  88   virtual void Initialize(const AudioParameters& params,
  89                           CaptureCallback* callback,
  90                           int session_id) OVERRIDE;
  91   virtual void Start() OVERRIDE;
  92   virtual void Stop() OVERRIDE;
  93   virtual void SetVolume(double volume) OVERRIDE;
  94   virtual void SetAutomaticGainControl(bool enabled) OVERRIDE;
  95
  96  protected:
  97   friend class base::RefCountedThreadSafe<AudioInputDevice>;
  98   virtual ~AudioInputDevice();
  99
 100   // Methods called on IO thread ----------------------------------------------
 101   // AudioInputIPCDelegate implementation.
 102   virtual void OnStreamCreated(base::SharedMemoryHandle handle,
 103                                base::SyncSocket::Handle socket_handle,
 104                                int length,
 105                                int total_segments) OVERRIDE;
 106   virtual void OnVolume(double volume) OVERRIDE;
 107   virtual void OnStateChanged(
 108       AudioInputIPCDelegate::State state) OVERRIDE;
 109   virtual void OnIPCClosed() OVERRIDE;
 110
 111  private:
 112   // Note: The ordering of members in this enum is critical to correct behavior!
 113   enum State {
 114     IPC_CLOSED,  // No more IPCs can take place.
 115     IDLE,  // Not started.
 116     CREATING_STREAM,  // Waiting for OnStreamCreated() to be called back.
 117     RECORDING,  // Receiving audio data.
 118   };
 119
 120   // Methods called on IO thread ----------------------------------------------
 121   // The following methods are tasks posted on the IO thread that needs to
 122   // be executed on that thread. They interact with AudioInputMessageFilter and
 123   // sends IPC messages on that thread.
 124   void StartUpOnIOThread();
 125   void ShutDownOnIOThread();
 126   void SetVolumeOnIOThread(double volume);
 127   void SetAutomaticGainControlOnIOThread(bool enabled);
 128
 129   // base::MessageLoop::DestructionObserver implementation for the IO loop.
 130   // If the IO loop dies before we do, we shut down the audio thread from here.
 131   virtual void WillDestroyCurrentMessageLoop() OVERRIDE;
 132
 133   AudioParameters audio_parameters_;
 134
 135   CaptureCallback* callback_;
 136
 137   // A pointer to the IPC layer that takes care of sending requests over to
 138   // the AudioInputRendererHost.  Only valid when state_ != IPC_CLOSED and must
 139   // only be accessed on the IO thread.
 140   scoped_ptr<AudioInputIPC> ipc_;
 141
 142   // Current state (must only be accessed from the IO thread).  See comments for
 143   // State enum above.
 144   State state_;
 145
 146   // The media session ID used to identify which input device to be started.
 147   // Only modified in Initialize() and ShutDownOnIOThread().
 148   int session_id_;
 149
 150   // Stores the Automatic Gain Control state. Default is false.
 151   // Only modified on the IO thread.
 152   bool agc_is_enabled_;
 153
 154   // Our audio thread callback class.  See source file for details.
 155   class AudioThreadCallback;
 156
 157   // In order to avoid a race between OnStreamCreated and Stop(), we use this
 158   // guard to control stopping and starting the audio thread.
 159   base::Lock audio_thread_lock_;
 160   AudioDeviceThread audio_thread_;
 161   scoped_ptr<AudioInputDevice::AudioThreadCallback> audio_callback_;
 162
 163   // Temporary hack to ignore OnStreamCreated() due to the user calling Stop()
 164   // so we don't start the audio thread pointing to a potentially freed
 165   // |callback_|.
 166   //
 167   // TODO(miu): Replace this by changing AudioCapturerSource to accept the
 168   // callback via Start(). See http://crbug.com/151051 for details.
 169   bool stopping_hack_;
 170
 171   DISALLOW_IMPLICIT_CONSTRUCTORS(AudioInputDevice);
 172 };
 173
 174 }  // namespace media
 175
 176 #endif  // MEDIA_AUDIO_AUDIO_INPUT_DEVICE_H_