Home | History | Annotate | Download | only in audio
      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 "base/basictypes.h"
     62 #include "base/bind.h"
     63 #include "base/memory/scoped_ptr.h"
     64 #include "base/memory/shared_memory.h"
     65 #include "base/message_loop/message_loop.h"
     66 #include "media/audio/audio_device_thread.h"
     67 #include "media/audio/audio_output_ipc.h"
     68 #include "media/audio/audio_parameters.h"
     69 #include "media/audio/scoped_loop_observer.h"
     70 #include "media/base/audio_renderer_sink.h"
     71 #include "media/base/media_export.h"
     72 
     73 namespace media {
     74 
     75 class MEDIA_EXPORT AudioOutputDevice
     76     : NON_EXPORTED_BASE(public AudioRendererSink),
     77       NON_EXPORTED_BASE(public AudioOutputIPCDelegate),
     78       NON_EXPORTED_BASE(public ScopedLoopObserver) {
     79  public:
     80   // NOTE: Clients must call Initialize() before using.
     81   AudioOutputDevice(scoped_ptr<AudioOutputIPC> ipc,
     82                     const scoped_refptr<base::MessageLoopProxy>& io_loop);
     83 
     84   // Initialize function for clients wishing to have unified input and
     85   // output, |params| may specify |input_channels| > 0, representing a
     86   // number of input channels which will be at the same sample-rate
     87   // and buffer-size as the output as specified in |params|. |session_id| is
     88   // used for the browser to select the correct input device.
     89   // In this case, the callback's RenderIO() method will be called instead
     90   // of Render(), providing the synchronized input data at the same time as
     91   // when new output data is to be rendered.
     92   void InitializeUnifiedStream(const AudioParameters& params,
     93                                RenderCallback* callback,
     94                                int session_id);
     95 
     96   // AudioRendererSink implementation.
     97   virtual void Initialize(const AudioParameters& params,
     98                           RenderCallback* callback) OVERRIDE;
     99   virtual void Start() OVERRIDE;
    100   virtual void Stop() OVERRIDE;
    101   virtual void Play() OVERRIDE;
    102   virtual void Pause() OVERRIDE;
    103   virtual bool SetVolume(double volume) OVERRIDE;
    104 
    105   // Methods called on IO thread ----------------------------------------------
    106   // AudioOutputIPCDelegate methods.
    107   virtual void OnStateChanged(AudioOutputIPCDelegate::State state) OVERRIDE;
    108   virtual void OnStreamCreated(base::SharedMemoryHandle handle,
    109                                base::SyncSocket::Handle socket_handle,
    110                                int length) OVERRIDE;
    111   virtual void OnIPCClosed() OVERRIDE;
    112 
    113  protected:
    114   // Magic required by ref_counted.h to avoid any code deleting the object
    115   // accidentally while there are references to it.
    116   friend class base::RefCountedThreadSafe<AudioOutputDevice>;
    117   virtual ~AudioOutputDevice();
    118 
    119  private:
    120   // Note: The ordering of members in this enum is critical to correct behavior!
    121   enum State {
    122     IPC_CLOSED,  // No more IPCs can take place.
    123     IDLE,  // Not started.
    124     CREATING_STREAM,  // Waiting for OnStreamCreated() to be called back.
    125     PAUSED,  // Paused.  OnStreamCreated() has been called.  Can Play()/Stop().
    126     PLAYING,  // Playing back.  Can Pause()/Stop().
    127   };
    128 
    129   // Methods called on IO thread ----------------------------------------------
    130   // The following methods are tasks posted on the IO thread that need to
    131   // be executed on that thread.  They use AudioOutputIPC to send IPC messages
    132   // upon state changes.
    133   void CreateStreamOnIOThread(const AudioParameters& params);
    134   void PlayOnIOThread();
    135   void PauseOnIOThread();
    136   void ShutDownOnIOThread();
    137   void SetVolumeOnIOThread(double volume);
    138 
    139   // base::MessageLoop::DestructionObserver implementation for the IO loop.
    140   // If the IO loop dies before we do, we shut down the audio thread from here.
    141   virtual void WillDestroyCurrentMessageLoop() OVERRIDE;
    142 
    143   AudioParameters audio_parameters_;
    144 
    145   RenderCallback* callback_;
    146 
    147   // A pointer to the IPC layer that takes care of sending requests over to
    148   // the AudioRendererHost.  Only valid when state_ != IPC_CLOSED and must only
    149   // be accessed on the IO thread.
    150   scoped_ptr<AudioOutputIPC> ipc_;
    151 
    152   // Current state (must only be accessed from the IO thread).  See comments for
    153   // State enum above.
    154   State state_;
    155 
    156   // State of Play() / Pause() calls before OnStreamCreated() is called.
    157   bool play_on_start_;
    158 
    159   // The media session ID used to identify which input device to be started.
    160   // Only used by Unified IO.
    161   int session_id_;
    162 
    163   // Our audio thread callback class.  See source file for details.
    164   class AudioThreadCallback;
    165 
    166   // In order to avoid a race between OnStreamCreated and Stop(), we use this
    167   // guard to control stopping and starting the audio thread.
    168   base::Lock audio_thread_lock_;
    169   AudioDeviceThread audio_thread_;
    170   scoped_ptr<AudioOutputDevice::AudioThreadCallback> audio_callback_;
    171 
    172   // Temporary hack to ignore OnStreamCreated() due to the user calling Stop()
    173   // so we don't start the audio thread pointing to a potentially freed
    174   // |callback_|.
    175   //
    176   // TODO(scherkus): Replace this by changing AudioRendererSink to either accept
    177   // the callback via Start(). See http://crbug.com/151051 for details.
    178   bool stopping_hack_;
    179 
    180   DISALLOW_COPY_AND_ASSIGN(AudioOutputDevice);
    181 };
    182 
    183 }  // namespace media
    184 
    185 #endif  // MEDIA_AUDIO_AUDIO_OUTPUT_DEVICE_H_
    186