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
