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.
5 // Audio rendering unit utilizing audio output stream provided by browser
6 // process through IPC.
8 // Relationship of classes.
10 // AudioOutputController AudioOutputDevice
14 // AudioRendererHost <---------> AudioOutputIPC (AudioMessageFilter)
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.
24 // Task [IO thread] IPC [IO thread]
26 // Start -> CreateStreamOnIOThread -----> CreateStream ------>
27 // <- OnStreamCreated <- AudioMsg_NotifyStreamCreated <-
28 // ---> PlayOnIOThread -----------> PlayStream -------->
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)
36 // AudioOutputDevice::Render => audio transport on audio thread =>
38 // Stop --> ShutDownOnIOThread --------> CloseStream -> Close
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
55 // Implementation notes:
56 // - The user must call Stop() before deleting the class instance.
58 #ifndef MEDIA_AUDIO_AUDIO_OUTPUT_DEVICE_H_
59 #define MEDIA_AUDIO_AUDIO_OUTPUT_DEVICE_H_
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 "media/audio/audio_device_thread.h"
66 #include "media/audio/audio_output_ipc.h"
67 #include "media/audio/audio_parameters.h"
68 #include "media/audio/scoped_task_runner_observer.h"
69 #include "media/base/audio_renderer_sink.h"
70 #include "media/base/media_export.h"
74 class MEDIA_EXPORT AudioOutputDevice
75 : NON_EXPORTED_BASE(public AudioRendererSink),
76 NON_EXPORTED_BASE(public AudioOutputIPCDelegate),
77 NON_EXPORTED_BASE(public ScopedTaskRunnerObserver) {
79 // NOTE: Clients must call Initialize() before using.
81 scoped_ptr<AudioOutputIPC> ipc,
82 const scoped_refptr<base::SingleThreadTaskRunner>& io_task_runner);
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,
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;
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;
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();
120 // Note: The ordering of members in this enum is critical to correct behavior!
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().
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);
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;
143 AudioParameters audio_parameters_;
145 RenderCallback* callback_;
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_;
152 // Current state (must only be accessed from the IO thread). See comments for
156 // State of Play() / Pause() calls before OnStreamCreated() is called.
159 // The media session ID used to identify which input device to be started.
160 // Only used by Unified IO.
163 // Our audio thread callback class. See source file for details.
164 class AudioThreadCallback;
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_;
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
176 // TODO(scherkus): Replace this by changing AudioRendererSink to either accept
177 // the callback via Start(). See http://crbug.com/151051 for details.
180 DISALLOW_COPY_AND_ASSIGN(AudioOutputDevice);
185 #endif // MEDIA_AUDIO_AUDIO_OUTPUT_DEVICE_H_