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