audio_input_controller.h revision 5d1f7b1de12d16ceb2c938c56701a3e8bfa558f7
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#ifndef MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_ 6#define MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_ 7 8#include <string> 9#include "base/atomicops.h" 10#include "base/callback.h" 11#include "base/memory/ref_counted.h" 12#include "base/memory/scoped_ptr.h" 13#include "base/synchronization/lock.h" 14#include "base/synchronization/waitable_event.h" 15#include "base/threading/thread.h" 16#include "base/timer/timer.h" 17#include "media/audio/audio_io.h" 18#include "media/audio/audio_manager_base.h" 19 20// An AudioInputController controls an AudioInputStream and records data 21// from this input stream. The two main methods are Record() and Close() and 22// they are both executed on the audio thread which is injected by the two 23// alternative factory methods, Create() or CreateLowLatency(). 24// 25// All public methods of AudioInputController are non-blocking. 26// 27// Here is a state diagram for the AudioInputController: 28// 29// .--> [ Closed / Error ] <--. 30// | | 31// | | 32// [ Created ] ----------> [ Recording ] 33// ^ 34// | 35// *[ Empty ] 36// 37// * Initial state 38// 39// State sequences (assuming low-latency): 40// 41// [Creating Thread] [Audio Thread] 42// 43// User AudioInputController EventHandler 44// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 45// CrateLowLatency() ==> DoCreate() 46// AudioManager::MakeAudioInputStream() 47// AudioInputStream::Open() 48// .- - - - - - - - - - - - -> OnError() 49// create the data timer 50// .-------------------------> OnCreated() 51// kCreated 52// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 53// Record() ==> DoRecord() 54// AudioInputStream::Start() 55// .-------------------------> OnRecording() 56// start the data timer 57// kRecording 58// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 59// Close() ==> DoClose() 60// delete the data timer 61// state_ = kClosed 62// AudioInputStream::Stop() 63// AudioInputStream::Close() 64// SyncWriter::Close() 65// Closure::Run() <-----------------. 66// (closure-task) 67// 68// The audio thread itself is owned by the AudioManager that the 69// AudioInputController holds a reference to. When performing tasks on the 70// audio thread, the controller must not add or release references to the 71// AudioManager or itself (since it in turn holds a reference to the manager). 72// 73namespace media { 74 75class UserInputMonitor; 76 77class MEDIA_EXPORT AudioInputController 78 : public base::RefCountedThreadSafe<AudioInputController>, 79 public AudioInputStream::AudioInputCallback { 80 public: 81 // An event handler that receives events from the AudioInputController. The 82 // following methods are all called on the audio thread. 83 class MEDIA_EXPORT EventHandler { 84 public: 85 virtual void OnCreated(AudioInputController* controller) = 0; 86 virtual void OnRecording(AudioInputController* controller) = 0; 87 virtual void OnError(AudioInputController* controller) = 0; 88 virtual void OnData(AudioInputController* controller, const uint8* data, 89 uint32 size) = 0; 90 91 protected: 92 virtual ~EventHandler() {} 93 }; 94 95 // A synchronous writer interface used by AudioInputController for 96 // synchronous writing. 97 class SyncWriter { 98 public: 99 virtual ~SyncWriter() {} 100 101 // Notify the synchronous writer about the number of bytes in the 102 // soundcard which has been recorded. 103 virtual void UpdateRecordedBytes(uint32 bytes) = 0; 104 105 // Write certain amount of data from |data|. This method returns 106 // number of written bytes. 107 virtual uint32 Write(const void* data, 108 uint32 size, 109 double volume, 110 bool key_pressed) = 0; 111 112 // Close this synchronous writer. 113 virtual void Close() = 0; 114 }; 115 116 // AudioInputController::Create() can use the currently registered Factory 117 // to create the AudioInputController. Factory is intended for testing only. 118 // |user_input_monitor| is used for typing detection and can be NULL. 119 class Factory { 120 public: 121 virtual AudioInputController* Create( 122 AudioManager* audio_manager, 123 EventHandler* event_handler, 124 AudioParameters params, 125 UserInputMonitor* user_input_monitor) = 0; 126 127 protected: 128 virtual ~Factory() {} 129 }; 130 131 // Factory method for creating an AudioInputController. 132 // The audio device will be created on the audio thread, and when that is 133 // done, the event handler will receive an OnCreated() call from that same 134 // thread. |device_id| is the unique ID of the audio device to be opened. 135 // |user_input_monitor| is used for typing detection and can be NULL. 136 static scoped_refptr<AudioInputController> Create( 137 AudioManager* audio_manager, 138 EventHandler* event_handler, 139 const AudioParameters& params, 140 const std::string& device_id, 141 UserInputMonitor* user_input_monitor); 142 143 // Sets the factory used by the static method Create(). AudioInputController 144 // does not take ownership of |factory|. A value of NULL results in an 145 // AudioInputController being created directly. 146 static void set_factory_for_testing(Factory* factory) { factory_ = factory; } 147 AudioInputStream* stream_for_testing() { return stream_; } 148 149 // Factory method for creating an AudioInputController for low-latency mode. 150 // The audio device will be created on the audio thread, and when that is 151 // done, the event handler will receive an OnCreated() call from that same 152 // thread. |user_input_monitor| is used for typing detection and can be NULL. 153 static scoped_refptr<AudioInputController> CreateLowLatency( 154 AudioManager* audio_manager, 155 EventHandler* event_handler, 156 const AudioParameters& params, 157 const std::string& device_id, 158 // External synchronous writer for audio controller. 159 SyncWriter* sync_writer, 160 UserInputMonitor* user_input_monitor); 161 162 // Factory method for creating an AudioInputController for low-latency mode, 163 // taking ownership of |stream|. The stream will be opened on the audio 164 // thread, and when that is done, the event handler will receive an 165 // OnCreated() call from that same thread. |user_input_monitor| is used for 166 // typing detection and can be NULL. 167 static scoped_refptr<AudioInputController> CreateForStream( 168 const scoped_refptr<base::SingleThreadTaskRunner>& task_runner, 169 EventHandler* event_handler, 170 AudioInputStream* stream, 171 // External synchronous writer for audio controller. 172 SyncWriter* sync_writer, 173 UserInputMonitor* user_input_monitor); 174 175 // Starts recording using the created audio input stream. 176 // This method is called on the creator thread. 177 virtual void Record(); 178 179 // Closes the audio input stream. The state is changed and the resources 180 // are freed on the audio thread. |closed_task| is then executed on the thread 181 // that called Close(). 182 // Callbacks (EventHandler and SyncWriter) must exist until |closed_task| 183 // is called. 184 // It is safe to call this method more than once. Calls after the first one 185 // will have no effect. 186 // This method trampolines to the audio thread. 187 virtual void Close(const base::Closure& closed_task); 188 189 // Sets the capture volume of the input stream. The value 0.0 corresponds 190 // to muted and 1.0 to maximum volume. 191 virtual void SetVolume(double volume); 192 193 // Sets the Automatic Gain Control (AGC) state of the input stream. 194 // Changing the AGC state is not supported while recording is active. 195 virtual void SetAutomaticGainControl(bool enabled); 196 197 // AudioInputCallback implementation. Threading details depends on the 198 // device-specific implementation. 199 virtual void OnData(AudioInputStream* stream, const uint8* src, uint32 size, 200 uint32 hardware_delay_bytes, double volume) OVERRIDE; 201 virtual void OnError(AudioInputStream* stream) OVERRIDE; 202 203 bool LowLatencyMode() const { return sync_writer_ != NULL; } 204 205 protected: 206 friend class base::RefCountedThreadSafe<AudioInputController>; 207 208 // Internal state of the source. 209 enum State { 210 kEmpty, 211 kCreated, 212 kRecording, 213 kClosed, 214 kError 215 }; 216 217 AudioInputController(EventHandler* handler, 218 SyncWriter* sync_writer, 219 UserInputMonitor* user_input_monitor); 220 virtual ~AudioInputController(); 221 222 // Methods called on the audio thread (owned by the AudioManager). 223 void DoCreate(AudioManager* audio_manager, const AudioParameters& params, 224 const std::string& device_id); 225 void DoCreateForStream(AudioInputStream* stream_to_control, 226 bool enable_nodata_timer); 227 void DoRecord(); 228 void DoClose(); 229 void DoReportError(); 230 void DoSetVolume(double volume); 231 void DoSetAutomaticGainControl(bool enabled); 232 233 // Method which ensures that OnError() is triggered when data recording 234 // times out. Called on the audio thread. 235 void DoCheckForNoData(); 236 237 // Helper method that stops, closes, and NULL:s |*stream_|. 238 // Signals event when done if the event is not NULL. 239 void DoStopCloseAndClearStream(base::WaitableEvent* done); 240 241 void SetDataIsActive(bool enabled); 242 bool GetDataIsActive(); 243 244 // Gives access to the task runner of the creating thread. 245 scoped_refptr<base::SingleThreadTaskRunner> creator_task_runner_; 246 247 // The task runner of audio-manager thread that this object runs on. 248 scoped_refptr<base::SingleThreadTaskRunner> task_runner_; 249 250 // Contains the AudioInputController::EventHandler which receives state 251 // notifications from this class. 252 EventHandler* handler_; 253 254 // Pointer to the audio input stream object. 255 AudioInputStream* stream_; 256 257 // |no_data_timer_| is used to call OnError() when we stop receiving 258 // OnData() calls. This can occur when an audio input device is unplugged 259 // whilst recording on Windows. 260 // See http://crbug.com/79936 for details. 261 // This member is only touched by the audio thread. 262 scoped_ptr<base::Timer> no_data_timer_; 263 264 // This flag is used to signal that we are receiving OnData() calls, i.e, 265 // that data is active. It can be touched by the audio thread and by the 266 // low-level audio thread which calls OnData(). E.g. on Windows, the 267 // low-level audio thread is called wasapi_capture_thread. 268 base::subtle::Atomic32 data_is_active_; 269 270 // |state_| is written on the audio thread and is read on the hardware audio 271 // thread. These operations need to be locked. But lock is not required for 272 // reading on the audio input controller thread. 273 State state_; 274 275 base::Lock lock_; 276 277 // SyncWriter is used only in low-latency mode for synchronous writing. 278 SyncWriter* sync_writer_; 279 280 static Factory* factory_; 281 282 double max_volume_; 283 284 UserInputMonitor* user_input_monitor_; 285 286 size_t prev_key_down_count_; 287 288 DISALLOW_COPY_AND_ASSIGN(AudioInputController); 289}; 290 291} // namespace media 292 293#endif // MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_ 294