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