OLD | NEW |
1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 // | 4 // |
5 // Low-latency audio rendering unit utilizing audio output stream provided | 5 // Low-latency audio rendering unit utilizing audio output stream provided |
6 // by browser process through IPC. | 6 // by browser process through IPC. |
7 // | 7 // |
8 // Relationship of classes. | 8 // Relationship of classes. |
9 // | 9 // |
10 // AudioOutputController AudioDevice | 10 // AudioOutputController AudioDevice |
11 // ^ ^ | 11 // ^ ^ |
12 // | | | 12 // | | |
13 // v IPC v | 13 // v IPC v |
14 // AudioRendererHost <---------> AudioMessageFilter | 14 // AudioRendererHost <---------> AudioMessageFilter |
15 // | 15 // |
16 // Transportation of audio samples from the render to the browser process | 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 | 17 // is done by using shared memory in combination with a sync socket pair |
18 // to generate a low latency transport. The AudioDevice user registers an | 18 // to generate a low latency transport. The AudioDevice user registers an |
19 // AudioDevice::RenderCallback at construction and will be polled by the | 19 // AudioDevice::RenderCallback at construction and will be polled by the |
20 // AudioDevice for audio to be played out by the underlying audio layers. | 20 // AudioDevice for audio to be played out by the underlying audio layers. |
21 // | 21 // |
22 // State sequences. | 22 // State sequences. |
23 // | 23 // |
24 // Task [IO thread] IPC [IO thread] | 24 // Task [IO thread] IPC [IO thread] |
25 // | 25 // |
26 // Start -> InitializeOnIOThread ------> AudioHostMsg_CreateStream --------> | 26 // Start -> InitializeOnIOThread ------> AudioHostMsg_CreateStream --------> |
27 // <- OnLowLatencyCreated <- AudioMsg_NotifyLowLatencyStreamCreated <- | 27 // <- OnLowLatencyCreated <- AudioMsg_NotifyLowLatencyStreamCreated <- |
28 // ---> StartOnIOThread -----------> AudioHostMsg_PlayStream --------> | 28 // ---> PlayOnIOThread -----------> AudioHostMsg_PlayStream --------> |
| 29 // |
| 30 // Optionally Play() / Pause() sequences may occur: |
| 31 // Play -> PlayOnIOThread --------------> AudioHostMsg_PlayStream ---------> |
| 32 // Pause -> PauseOnIOThread ------------> AudioHostMsg_PauseStream --------> |
| 33 // (note that Play() / Pause() sequences before OnLowLatencyCreated are |
| 34 // deferred until OnLowLatencyCreated, with the last valid state being used) |
29 // | 35 // |
30 // AudioDevice::Render => audio transport on audio thread with low latency => | 36 // AudioDevice::Render => audio transport on audio thread with low latency => |
31 // | | 37 // | |
32 // Stop --> ShutDownOnIOThread --------> AudioHostMsg_CloseStream -> Close | 38 // Stop --> ShutDownOnIOThread --------> AudioHostMsg_CloseStream -> Close |
33 // | 39 // |
34 // This class utilizes three threads during its lifetime, namely: | 40 // This class utilizes several threads during its lifetime, namely: |
35 // 1. Creating thread. | 41 // 1. Creating thread. |
36 // Must be the main render thread. Start and Stop should be called on | 42 // Must be the main render thread. |
37 // this thread. | 43 // 2. Control thread (may be the main render thread or another thread). |
38 // 2. IO 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) |
39 // The thread within which this class receives all the IPC messages and | 47 // The thread within which this class receives all the IPC messages and |
40 // IPC communications can only happen in this thread. | 48 // IPC communications can only happen in this thread. |
41 // 3. Audio transport thread. | 49 // 4. Audio transport thread. |
42 // Responsible for calling the RenderCallback and feed audio samples to | 50 // Responsible for calling the RenderCallback and feeding audio samples to |
43 // the audio layer in the browser process using sync sockets and shared | 51 // the audio layer in the browser process using sync sockets and shared |
44 // memory. | 52 // memory. |
45 // | 53 // |
46 // Implementation notes: | 54 // Implementation notes: |
47 // | 55 // |
48 // - Start() is asynchronous/non-blocking. | 56 // - Start() is asynchronous/non-blocking. |
49 // - Stop() is synchronous/blocking. | 57 // - Stop() is synchronous/blocking. |
| 58 // - Play() is asynchronous/non-blocking. |
| 59 // - Pause() is asynchronous/non-blocking. |
50 // - The user must call Stop() before deleting the class instance. | 60 // - The user must call Stop() before deleting the class instance. |
51 | 61 |
52 #ifndef CONTENT_RENDERER_MEDIA_AUDIO_DEVICE_H_ | 62 #ifndef CONTENT_RENDERER_MEDIA_AUDIO_DEVICE_H_ |
53 #define CONTENT_RENDERER_MEDIA_AUDIO_DEVICE_H_ | 63 #define CONTENT_RENDERER_MEDIA_AUDIO_DEVICE_H_ |
54 #pragma once | 64 #pragma once |
55 | 65 |
56 #include <vector> | 66 #include <vector> |
57 | 67 |
58 #include "base/basictypes.h" | 68 #include "base/basictypes.h" |
59 #include "base/memory/scoped_ptr.h" | 69 #include "base/memory/scoped_ptr.h" |
60 #include "base/shared_memory.h" | 70 #include "base/shared_memory.h" |
| 71 #include "base/synchronization/lock.h" |
61 #include "base/threading/simple_thread.h" | 72 #include "base/threading/simple_thread.h" |
62 #include "content/common/content_export.h" | 73 #include "content/common/content_export.h" |
63 #include "content/renderer/media/audio_message_filter.h" | 74 #include "content/renderer/media/audio_message_filter.h" |
64 | 75 #include "media/audio/audio_parameters.h" |
65 struct AudioParameters; | |
66 | 76 |
67 class CONTENT_EXPORT AudioDevice | 77 class CONTENT_EXPORT AudioDevice |
68 : public AudioMessageFilter::Delegate, | 78 : public AudioMessageFilter::Delegate, |
69 public base::DelegateSimpleThread::Delegate, | 79 public base::DelegateSimpleThread::Delegate, |
70 public base::RefCountedThreadSafe<AudioDevice> { | 80 public base::RefCountedThreadSafe<AudioDevice> { |
71 public: | 81 public: |
72 class RenderCallback { | 82 class RenderCallback { |
73 public: | 83 public: |
74 virtual void Render(const std::vector<float*>& audio_data, | 84 virtual void Render(const std::vector<float*>& audio_data, |
75 size_t number_of_frames, | 85 size_t number_of_frames, |
76 size_t audio_delay_milliseconds) = 0; | 86 size_t audio_delay_milliseconds) = 0; |
77 protected: | 87 protected: |
78 virtual ~RenderCallback() {} | 88 virtual ~RenderCallback() {} |
79 }; | 89 }; |
80 | 90 |
81 // Methods called on main render thread ------------------------------------- | 91 // Methods called on main render thread ------------------------------------- |
| 92 |
| 93 // Minimal constructor where Initialize() must be called later. |
| 94 AudioDevice(); |
| 95 |
82 AudioDevice(size_t buffer_size, | 96 AudioDevice(size_t buffer_size, |
83 int channels, | 97 int channels, |
84 double sample_rate, | 98 double sample_rate, |
85 RenderCallback* callback); | 99 RenderCallback* callback); |
86 virtual ~AudioDevice(); | 100 virtual ~AudioDevice(); |
87 | 101 |
| 102 void Initialize(size_t buffer_size, |
| 103 int channels, |
| 104 double sample_rate, |
| 105 AudioParameters::Format latency_format, |
| 106 RenderCallback* callback); |
| 107 bool IsInitialized(); |
| 108 |
88 // Starts audio playback. | 109 // Starts audio playback. |
89 void Start(); | 110 void Start(); |
90 | 111 |
91 // Stops audio playback. Returns |true| on success. | 112 // Stops audio playback. Returns |true| on success. |
92 bool Stop(); | 113 bool Stop(); |
93 | 114 |
| 115 // Resumes playback if currently paused. |
| 116 // TODO(crogers): it should be possible to remove the extra complexity |
| 117 // of Play() and Pause() with additional re-factoring |
| 118 // work in AudioRendererImpl. |
| 119 void Play(); |
| 120 |
| 121 // Pauses playback. |
| 122 // If |flush| is true then any pending audio which is in the pipeline |
| 123 // (has not yet reached the hardware) will be discarded. In this case, |
| 124 // When Play() is later called, no previous pending audio will be |
| 125 // rendered. |
| 126 void Pause(bool flush); |
| 127 |
94 // Sets the playback volume, with range [0.0, 1.0] inclusive. | 128 // Sets the playback volume, with range [0.0, 1.0] inclusive. |
95 // Returns |true| on success. | 129 // Returns |true| on success. |
96 bool SetVolume(double volume); | 130 bool SetVolume(double volume); |
97 | 131 |
98 // Gets the playback volume, with range [0.0, 1.0] inclusive. | 132 // Gets the playback volume, with range [0.0, 1.0] inclusive. |
99 void GetVolume(double* volume); | 133 void GetVolume(double* volume); |
100 | 134 |
101 double sample_rate() const { return sample_rate_; } | 135 double sample_rate() const { return sample_rate_; } |
102 size_t buffer_size() const { return buffer_size_; } | 136 size_t buffer_size() const { return buffer_size_; } |
103 | 137 |
104 static double GetAudioHardwareSampleRate(); | 138 static double GetAudioHardwareSampleRate(); |
105 static size_t GetAudioHardwareBufferSize(); | 139 static size_t GetAudioHardwareBufferSize(); |
106 | 140 |
107 // Methods called on IO thread ---------------------------------------------- | 141 // Methods called on IO thread ---------------------------------------------- |
108 // AudioMessageFilter::Delegate methods, called by AudioMessageFilter. | 142 // AudioMessageFilter::Delegate methods, called by AudioMessageFilter. |
109 virtual void OnRequestPacket(AudioBuffersState buffers_state); | 143 virtual void OnRequestPacket(AudioBuffersState buffers_state); |
110 virtual void OnStateChanged(AudioStreamState state); | 144 virtual void OnStateChanged(AudioStreamState state); |
111 virtual void OnCreated(base::SharedMemoryHandle handle, uint32 length); | 145 virtual void OnCreated(base::SharedMemoryHandle handle, uint32 length); |
112 virtual void OnLowLatencyCreated(base::SharedMemoryHandle handle, | 146 virtual void OnLowLatencyCreated(base::SharedMemoryHandle handle, |
113 base::SyncSocket::Handle socket_handle, | 147 base::SyncSocket::Handle socket_handle, |
114 uint32 length); | 148 uint32 length); |
115 virtual void OnVolume(double volume); | 149 virtual void OnVolume(double volume); |
116 | 150 |
117 private: | 151 private: |
118 // Methods called on IO thread ---------------------------------------------- | 152 // Methods called on IO thread ---------------------------------------------- |
119 // The following methods are tasks posted on the IO thread that needs to | 153 // The following methods are tasks posted on the IO thread that needs to |
120 // be executed on that thread. They interact with AudioMessageFilter and | 154 // be executed on that thread. They interact with AudioMessageFilter and |
121 // sends IPC messages on that thread. | 155 // sends IPC messages on that thread. |
122 void InitializeOnIOThread(const AudioParameters& params); | 156 void InitializeOnIOThread(const AudioParameters& params); |
123 void StartOnIOThread(); | 157 void PlayOnIOThread(); |
| 158 void PauseOnIOThread(bool flush); |
124 void ShutDownOnIOThread(base::WaitableEvent* completion); | 159 void ShutDownOnIOThread(base::WaitableEvent* completion); |
125 void SetVolumeOnIOThread(double volume); | 160 void SetVolumeOnIOThread(double volume); |
126 | 161 |
127 void Send(IPC::Message* message); | 162 void Send(IPC::Message* message); |
128 | 163 |
129 // Method called on the audio thread (+ one call on the IO thread) ---------- | 164 // Method called on the audio thread (+ one call on the IO thread) ---------- |
130 // Calls the client's callback for rendering audio. There will also be one | 165 // Calls the client's callback for rendering audio. There will also be one |
131 // initial call on the IO thread before the audio thread has been created. | 166 // initial call on the IO thread before the audio thread has been created. |
132 void FireRenderCallback(); | 167 void FireRenderCallback(); |
133 | 168 |
134 // DelegateSimpleThread::Delegate implementation. | 169 // DelegateSimpleThread::Delegate implementation. |
135 virtual void Run(); | 170 virtual void Run(); |
136 | 171 |
| 172 // Closes socket and joins with the audio thread. |
| 173 void ShutDownAudioThread(); |
| 174 |
137 // Format | 175 // Format |
138 size_t buffer_size_; // in sample-frames | 176 size_t buffer_size_; // in sample-frames |
139 int channels_; | 177 int channels_; |
140 int bits_per_sample_; | 178 int bits_per_sample_; |
141 double sample_rate_; | 179 double sample_rate_; |
| 180 AudioParameters::Format latency_format_; |
142 | 181 |
143 RenderCallback* callback_; | 182 RenderCallback* callback_; |
144 | 183 |
145 // The client callback renders audio into here. | 184 // The client callback renders audio into here. |
146 std::vector<float*> audio_data_; | 185 std::vector<float*> audio_data_; |
147 | 186 |
| 187 // Set to |true| once Initialize() has been called. |
| 188 bool is_initialized_; |
| 189 |
148 // The client stores the last reported audio delay in this member. | 190 // The client stores the last reported audio delay in this member. |
149 // The delay shall reflect the amount of audio which still resides in | 191 // The delay shall reflect the amount of audio which still resides in |
150 // the output buffer, i.e., the expected audio output delay. | 192 // the output buffer, i.e., the expected audio output delay. |
151 int audio_delay_milliseconds_; | 193 int audio_delay_milliseconds_; |
152 | 194 |
153 // The current volume scaling [0.0, 1.0] of the audio stream. | 195 // The current volume scaling [0.0, 1.0] of the audio stream. |
154 double volume_; | 196 double volume_; |
155 | 197 |
156 // Callbacks for rendering audio occur on this thread. | 198 // Callbacks for rendering audio occur on this thread. |
157 scoped_ptr<base::DelegateSimpleThread> audio_thread_; | 199 scoped_ptr<base::DelegateSimpleThread> audio_thread_; |
158 | 200 |
159 // IPC message stuff. | 201 // IPC message stuff. |
160 base::SharedMemory* shared_memory() { return shared_memory_.get(); } | 202 base::SharedMemory* shared_memory() { return shared_memory_.get(); } |
161 base::SyncSocket* socket() { return socket_.get(); } | 203 base::SyncSocket* socket() { return socket_.get(); } |
162 void* shared_memory_data() { return shared_memory()->memory(); } | 204 void* shared_memory_data() { return shared_memory()->memory(); } |
163 | 205 |
164 // Cached audio message filter (lives on the main render thread). | 206 // Cached audio message filter (lives on the main render thread). |
165 scoped_refptr<AudioMessageFilter> filter_; | 207 scoped_refptr<AudioMessageFilter> filter_; |
166 | 208 |
167 // Our stream ID on the message filter. Only accessed on the IO thread. | 209 // Our stream ID on the message filter. Only accessed on the IO thread. |
168 int32 stream_id_; | 210 int32 stream_id_; |
169 | 211 |
| 212 // State of Play() / Pause() calls before OnLowLatencyCreated() is called. |
| 213 bool play_on_start_; |
| 214 |
| 215 // Set to |true| when OnLowLatencyCreated() is called. |
| 216 // Set to |false| when ShutDownOnIOThread() is called. |
| 217 // This is for use with play_on_start_ to track Play() / Pause() state. |
| 218 bool is_started_; |
| 219 |
170 // Data transfer between browser and render process uses a combination | 220 // Data transfer between browser and render process uses a combination |
171 // of sync sockets and shared memory to provide lowest possible latency. | 221 // of sync sockets and shared memory to provide lowest possible latency. |
172 scoped_ptr<base::SharedMemory> shared_memory_; | 222 scoped_ptr<base::SharedMemory> shared_memory_; |
| 223 uint32 shared_memory_size_; |
173 scoped_ptr<base::SyncSocket> socket_; | 224 scoped_ptr<base::SyncSocket> socket_; |
174 | 225 |
175 DISALLOW_IMPLICIT_CONSTRUCTORS(AudioDevice); | 226 // Protects lifetime of: |
| 227 // socket_ |
| 228 // audio_thread_ |
| 229 base::Lock lock_; |
| 230 |
| 231 DISALLOW_COPY_AND_ASSIGN(AudioDevice); |
176 }; | 232 }; |
177 | 233 |
178 #endif // CONTENT_RENDERER_MEDIA_AUDIO_DEVICE_H_ | 234 #endif // CONTENT_RENDERER_MEDIA_AUDIO_DEVICE_H_ |
OLD | NEW |