media/audio/audio_output_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 // Audio rendering unit utilizing audio output stream provided by browser
   6 // process through IPC.
   7 //
   8 // Relationship of classes.
   9 //
  10 //  AudioOutputController                AudioOutputDevice
  11 //           ^                                ^
  12 //           |                                |
  13 //           v               IPC              v
  14 //    AudioRendererHost  <---------> AudioOutputIPC (AudioMessageFilter)
  15 //
  16 // Transportation of audio samples from the render to the browser process
  17 // is done by using shared memory in combination with a sync socket pair
  18 // to generate a low latency transport. The AudioOutputDevice user registers an
  19 // AudioOutputDevice::RenderCallback at construction and will be polled by the
  20 // AudioOutputDevice for audio to be played out by the underlying audio layers.
  21 //
  22 // State sequences.
  23 //
  24 //            Task [IO thread]                  IPC [IO thread]
  25 // RequestDeviceAuthorization -> RequestDeviceAuthorizationOnIOThread ------>
  26 // RequestDeviceAuthorization ->
  27 //             <- OnDeviceAuthorized <- AudioMsg_NotifyDeviceAuthorized <-
  28 //
  29 // Start -> CreateStreamOnIOThread -----> CreateStream ------>
  30 //       <- OnStreamCreated <- AudioMsg_NotifyStreamCreated <-
  31 //       ---> PlayOnIOThread -----------> PlayStream -------->
  32 //
  33 // Optionally Play() / Pause() / SwitchOutputDevice() sequences may occur:
  34 // Play -> PlayOnIOThread --------------> PlayStream --------->
  35 // Pause -> PauseOnIOThread ------------> PauseStream -------->
  36 // SwitchOutputDevice -> SwitchOutputDeviceOnIOThread -> SwitchOutputDevice ->
  37 //         <- OnOutputDeviceSwitched <- AudioMsg_NotifyOutputDeviceSwitched <-
  38 // (note that Play() / Pause() / SwitchOutptuDevice() sequences before
  39 // OnStreamCreated are deferred until OnStreamCreated, with the last valid
  40 // state being used)
  41 //
  42 // AudioOutputDevice::Render => audio transport on audio thread =>
  43 //                               |
  44 // Stop --> ShutDownOnIOThread -------->  CloseStream -> Close
  45 //
  46 // This class utilizes several threads during its lifetime, namely:
  47 // 1. Creating thread.
  48 //    Must be the main render thread.
  49 // 2. Control thread (may be the main render thread or another thread).
  50 //    The methods: Start(), Stop(), Play(), Pause(), SetVolume()
  51 //    must be called on the same thread.
  52 // 3. IO thread (internal implementation detail - not exposed to public API)
  53 //    The thread within which this class receives all the IPC messages and
  54 //    IPC communications can only happen in this thread.
  55 // 4. Audio transport thread (See AudioDeviceThread).
  56 //    Responsible for calling the AudioThreadCallback implementation that in
  57 //    turn calls AudioRendererSink::RenderCallback which feeds audio samples to
  58 //    the audio layer in the browser process using sync sockets and shared
  59 //    memory.
  60 //
  61 // Implementation notes:
  62 // - The user must call Stop() before deleting the class instance.
  63
  64 #ifndef MEDIA_AUDIO_AUDIO_OUTPUT_DEVICE_H_
  65 #define MEDIA_AUDIO_AUDIO_OUTPUT_DEVICE_H_
  66
  67 #include <string>
  68
  69 #include "base/basictypes.h"
  70 #include "base/bind.h"
  71 #include "base/memory/scoped_ptr.h"
  72 #include "base/memory/shared_memory.h"
  73 #include "base/synchronization/waitable_event.h"
  74 #include "media/audio/audio_device_thread.h"
  75 #include "media/audio/audio_output_ipc.h"
  76 #include "media/audio/audio_parameters.h"
  77 #include "media/audio/scoped_task_runner_observer.h"
  78 #include "media/base/audio_renderer_sink.h"
  79 #include "media/base/media_export.h"
  80 #include "media/base/output_device.h"
  81
  82 namespace media {
  83
  84 class MEDIA_EXPORT AudioOutputDevice
  85     : NON_EXPORTED_BASE(public AudioRendererSink),
  86       NON_EXPORTED_BASE(public AudioOutputIPCDelegate),
  87       NON_EXPORTED_BASE(public OutputDevice),
  88       NON_EXPORTED_BASE(public ScopedTaskRunnerObserver) {
  89  public:
  90   // NOTE: Clients must call Initialize() before using.
  91   AudioOutputDevice(
  92       scoped_ptr<AudioOutputIPC> ipc,
  93       const scoped_refptr<base::SingleThreadTaskRunner>& io_task_runner,
  94       int session_id,
  95       const std::string& device_id,
  96       const url::Origin& security_origin);
  97
  98   // Request authorization to use the device specified in the constructor.
  99   void RequestDeviceAuthorization();
 100
 101   // AudioRendererSink implementation.
 102   void Initialize(const AudioParameters& params,
 103                   RenderCallback* callback) override;
 104   void Start() override;
 105   void Stop() override;
 106   void Play() override;
 107   void Pause() override;
 108   bool SetVolume(double volume) override;
 109   OutputDevice* GetOutputDevice() override;
 110
 111   // OutputDevice implementation
 112   void SwitchOutputDevice(const std::string& device_id,
 113                           const url::Origin& security_origin,
 114                           const SwitchOutputDeviceCB& callback) override;
 115   AudioParameters GetOutputParameters() override;
 116
 117   // Methods called on IO thread ----------------------------------------------
 118   // AudioOutputIPCDelegate methods.
 119   void OnStateChanged(AudioOutputIPCDelegateState state) override;
 120   void OnDeviceAuthorized(bool success,
 121                           const media::AudioParameters& output_params) override;
 122   void OnStreamCreated(base::SharedMemoryHandle handle,
 123                        base::SyncSocket::Handle socket_handle,
 124                        int length) override;
 125   void OnOutputDeviceSwitched(SwitchOutputDeviceResult result) override;
 126   void OnIPCClosed() override;
 127
 128  protected:
 129   // Magic required by ref_counted.h to avoid any code deleting the object
 130   // accidentally while there are references to it.
 131   friend class base::RefCountedThreadSafe<AudioOutputDevice>;
 132   ~AudioOutputDevice() override;
 133
 134  private:
 135   // Note: The ordering of members in this enum is critical to correct behavior!
 136   enum State {
 137     IPC_CLOSED,       // No more IPCs can take place.
 138     IDLE,             // Not started.
 139     AUTHORIZING,      // Sent device authorization request, waiting for reply.
 140     AUTHORIZED,       // Successful device authorization received.
 141     CREATING_STREAM,  // Waiting for OnStreamCreated() to be called back.
 142     PAUSED,   // Paused.  OnStreamCreated() has been called.  Can Play()/Stop().
 143     PLAYING,  // Playing back.  Can Pause()/Stop().
 144   };
 145
 146   // Methods called on IO thread ----------------------------------------------
 147   // The following methods are tasks posted on the IO thread that need to
 148   // be executed on that thread.  They use AudioOutputIPC to send IPC messages
 149   // upon state changes.
 150   void RequestDeviceAuthorizationOnIOThread();
 151   void CreateStreamOnIOThread(const AudioParameters& params);
 152   void PlayOnIOThread();
 153   void PauseOnIOThread();
 154   void ShutDownOnIOThread();
 155   void SetVolumeOnIOThread(double volume);
 156   void SwitchOutputDeviceOnIOThread(const std::string& device_id,
 157                                     const url::Origin& security_origin,
 158                                     const SwitchOutputDeviceCB& callback);
 159
 160   // base::MessageLoop::DestructionObserver implementation for the IO loop.
 161   // If the IO loop dies before we do, we shut down the audio thread from here.
 162   void WillDestroyCurrentMessageLoop() override;
 163
 164   void SetCurrentSwitchRequest(const SwitchOutputDeviceCB& callback,
 165                                const std::string& device_id,
 166                                const url::Origin& security_origin);
 167   void SetOutputParams(const media::AudioParameters& output_params);
 168
 169   AudioParameters audio_parameters_;
 170
 171   RenderCallback* callback_;
 172
 173   // A pointer to the IPC layer that takes care of sending requests over to
 174   // the AudioRendererHost.  Only valid when state_ != IPC_CLOSED and must only
 175   // be accessed on the IO thread.
 176   scoped_ptr<AudioOutputIPC> ipc_;
 177
 178   // Current state (must only be accessed from the IO thread).  See comments for
 179   // State enum above.
 180   State state_;
 181
 182   // State of Start() calls before OnDeviceAuthorized() is called.
 183   bool start_on_authorized_;
 184
 185   // State of Play() / Pause() calls before OnStreamCreated() is called.
 186   bool play_on_start_;
 187
 188   // The media session ID used to identify which input device to be started.
 189   // Only used by Unified IO.
 190   int session_id_;
 191
 192   // ID of hardware output device to be used (provided session_id_ is zero)
 193   std::string device_id_;
 194   url::Origin security_origin_;
 195
 196   // Our audio thread callback class.  See source file for details.
 197   class AudioThreadCallback;
 198
 199   // In order to avoid a race between OnStreamCreated and Stop(), we use this
 200   // guard to control stopping and starting the audio thread.
 201   base::Lock audio_thread_lock_;
 202   AudioDeviceThread audio_thread_;
 203   scoped_ptr<AudioOutputDevice::AudioThreadCallback> audio_callback_;
 204
 205   // Temporary hack to ignore OnStreamCreated() due to the user calling Stop()
 206   // so we don't start the audio thread pointing to a potentially freed
 207   // |callback_|.
 208   //
 209   // TODO(scherkus): Replace this by changing AudioRendererSink to either accept
 210   // the callback via Start(). See http://crbug.com/151051 for details.
 211   bool stopping_hack_;
 212
 213   SwitchOutputDeviceCB current_switch_callback_;
 214   std::string current_switch_device_id_;
 215   url::Origin current_switch_security_origin_;
 216   bool switch_output_device_on_start_;
 217
 218   base::WaitableEvent did_set_output_params_;
 219   media::AudioParameters output_params_;
 220
 221   DISALLOW_COPY_AND_ASSIGN(AudioOutputDevice);
 222 };
 223
 224 }  // namespace media
 225
 226 #endif  // MEDIA_AUDIO_AUDIO_OUTPUT_DEVICE_H_