audio_output_device.h revision 2a99a7e74a7f215066514fe81d2bfa6639d9eddd
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/message_loop.h" 65#include "base/shared_memory.h" 66#include "media/base/media_export.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_loop_observer.h" 71#include "media/base/audio_renderer_sink.h" 72 73namespace media { 74 75class MEDIA_EXPORT AudioOutputDevice 76 : NON_EXPORTED_BASE(public AudioRendererSink), 77 public AudioOutputIPCDelegate, 78 NON_EXPORTED_BASE(public ScopedLoopObserver) { 79 public: 80 // AudioRendererSink implementation. 81 virtual void Initialize(const AudioParameters& params, 82 RenderCallback* callback) OVERRIDE; 83 virtual void Start() OVERRIDE; 84 virtual void Stop() OVERRIDE; 85 virtual void Play() OVERRIDE; 86 virtual void Pause(bool flush) OVERRIDE; 87 virtual bool SetVolume(double volume) OVERRIDE; 88 89 // Methods called on IO thread ---------------------------------------------- 90 // AudioOutputIPCDelegate methods. 91 virtual void OnStateChanged(AudioOutputIPCDelegate::State state) OVERRIDE; 92 virtual void OnStreamCreated(base::SharedMemoryHandle handle, 93 base::SyncSocket::Handle socket_handle, 94 int length) OVERRIDE; 95 virtual void OnIPCClosed() OVERRIDE; 96 97 // Creates an uninitialized AudioOutputDevice. Clients must call Initialize() 98 // before using. 99 AudioOutputDevice(AudioOutputIPC* ipc, 100 const scoped_refptr<base::MessageLoopProxy>& io_loop); 101 102 protected: 103 // Magic required by ref_counted.h to avoid any code deleting the object 104 // accidentally while there are references to it. 105 friend class base::RefCountedThreadSafe<AudioOutputDevice>; 106 virtual ~AudioOutputDevice(); 107 108 // Accessors for subclasses (via IO thread only). 109 int stream_id() const { return stream_id_; } 110 AudioOutputIPC* audio_output_ipc() const { return ipc_; } 111 112 private: 113 // Note: The ordering of members in this enum is critical to correct behavior! 114 enum State { 115 IPC_CLOSED, // No more IPCs can take place. 116 IDLE, // Not started. 117 CREATING_STREAM, // Waiting for OnStreamCreated() to be called back. 118 PAUSED, // Paused. OnStreamCreated() has been called. Can Play()/Stop(). 119 PLAYING, // Playing back. Can Pause()/Stop(). 120 }; 121 122 // Methods called on IO thread ---------------------------------------------- 123 // The following methods are tasks posted on the IO thread that needs to 124 // be executed on that thread. They interact with AudioMessageFilter and 125 // sends IPC messages on that thread. 126 void CreateStreamOnIOThread(const AudioParameters& params); 127 void PlayOnIOThread(); 128 void PauseOnIOThread(bool flush); 129 void ShutDownOnIOThread(); 130 void SetVolumeOnIOThread(double volume); 131 132 // MessageLoop::DestructionObserver implementation for the IO loop. 133 // If the IO loop dies before we do, we shut down the audio thread from here. 134 virtual void WillDestroyCurrentMessageLoop() OVERRIDE; 135 136 AudioParameters audio_parameters_; 137 138 RenderCallback* callback_; 139 140 // A pointer to the IPC layer that takes care of sending requests over to 141 // the AudioRendererHost. 142 AudioOutputIPC* ipc_; 143 144 // Our stream ID on the message filter. Only accessed on the IO thread. 145 // Must only be modified on the IO thread. 146 int stream_id_; 147 148 // Current state (must only be accessed from the IO thread). See comments for 149 // State enum above. 150 State state_; 151 152 // State of Play() / Pause() calls before OnStreamCreated() is called. 153 bool play_on_start_; 154 155 // Our audio thread callback class. See source file for details. 156 class AudioThreadCallback; 157 158 // In order to avoid a race between OnStreamCreated and Stop(), we use this 159 // guard to control stopping and starting the audio thread. 160 base::Lock audio_thread_lock_; 161 AudioDeviceThread audio_thread_; 162 scoped_ptr<AudioOutputDevice::AudioThreadCallback> audio_callback_; 163 164 // Temporary hack to ignore OnStreamCreated() due to the user calling Stop() 165 // so we don't start the audio thread pointing to a potentially freed 166 // |callback_|. 167 // 168 // TODO(scherkus): Replace this by changing AudioRendererSink to either accept 169 // the callback via Start(). See http://crbug.com/151051 for details. 170 bool stopping_hack_; 171 172 DISALLOW_COPY_AND_ASSIGN(AudioOutputDevice); 173}; 174 175} // namespace media 176 177#endif // MEDIA_AUDIO_AUDIO_OUTPUT_DEVICE_H_ 178