audio_input_controller.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#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#include "media/audio/audio_parameters.h" 20#include "media/audio/audio_power_monitor.h" 21#include "media/base/audio_bus.h" 22 23// An AudioInputController controls an AudioInputStream and records data 24// from this input stream. The two main methods are Record() and Close() and 25// they are both executed on the audio thread which is injected by the two 26// alternative factory methods, Create() or CreateLowLatency(). 27// 28// All public methods of AudioInputController are non-blocking. 29// 30// Here is a state diagram for the AudioInputController: 31// 32// .--> [ Closed / Error ] <--. 33// | | 34// | | 35// [ Created ] ----------> [ Recording ] 36// ^ 37// | 38// *[ Empty ] 39// 40// * Initial state 41// 42// State sequences (assuming low-latency): 43// 44// [Creating Thread] [Audio Thread] 45// 46// User AudioInputController EventHandler 47// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 48// CrateLowLatency() ==> DoCreate() 49// AudioManager::MakeAudioInputStream() 50// AudioInputStream::Open() 51// .- - - - - - - - - - - - -> OnError() 52// create the data timer 53// .-------------------------> OnCreated() 54// kCreated 55// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 56// Record() ==> DoRecord() 57// AudioInputStream::Start() 58// .-------------------------> OnRecording() 59// start the data timer 60// kRecording 61// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 62// Close() ==> DoClose() 63// delete the data timer 64// state_ = kClosed 65// AudioInputStream::Stop() 66// AudioInputStream::Close() 67// SyncWriter::Close() 68// Closure::Run() <-----------------. 69// (closure-task) 70// 71// The audio thread itself is owned by the AudioManager that the 72// AudioInputController holds a reference to. When performing tasks on the 73// audio thread, the controller must not add or release references to the 74// AudioManager or itself (since it in turn holds a reference to the manager). 75// 76namespace media { 77 78// Only do power monitoring for non-mobile platforms to save resources. 79#if !defined(OS_ANDROID) && !defined(OS_IOS) 80#define AUDIO_POWER_MONITORING 81#endif 82 83class UserInputMonitor; 84 85class MEDIA_EXPORT AudioInputController 86 : public base::RefCountedThreadSafe<AudioInputController>, 87 public AudioInputStream::AudioInputCallback { 88 public: 89 90 // Error codes to make native loggin more clear. These error codes are added 91 // to generic error strings to provide a higher degree of details. 92 // Changing these values can lead to problems when matching native debug 93 // logs with the actual cause of error. 94 enum ErrorCode { 95 // An unspecified error occured. 96 UNKNOWN_ERROR = 0, 97 98 // Failed to create an audio input stream. 99 STREAM_CREATE_ERROR, // = 1 100 101 // Failed to open an audio input stream. 102 STREAM_OPEN_ERROR, // = 2 103 104 // Native input stream reports an error. Exact reason differs between 105 // platforms. 106 STREAM_ERROR, // = 3 107 108 // This can happen if a capture device has been removed or disabled. 109 NO_DATA_ERROR, // = 4 110 }; 111 112 // An event handler that receives events from the AudioInputController. The 113 // following methods are all called on the audio thread. 114 class MEDIA_EXPORT EventHandler { 115 public: 116 virtual void OnCreated(AudioInputController* controller) = 0; 117 virtual void OnRecording(AudioInputController* controller) = 0; 118 virtual void OnError(AudioInputController* controller, 119 ErrorCode error_code) = 0; 120 virtual void OnData(AudioInputController* controller, const uint8* data, 121 uint32 size) = 0; 122 virtual void OnLog(AudioInputController* controller, 123 const std::string& message) = 0; 124 125 protected: 126 virtual ~EventHandler() {} 127 }; 128 129 // A synchronous writer interface used by AudioInputController for 130 // synchronous writing. 131 class SyncWriter { 132 public: 133 virtual ~SyncWriter() {} 134 135 // Notify the synchronous writer about the number of bytes in the 136 // soundcard which has been recorded. 137 virtual void UpdateRecordedBytes(uint32 bytes) = 0; 138 139 // Write certain amount of data from |data|. This method returns 140 // number of written bytes. 141 virtual uint32 Write(const void* data, 142 uint32 size, 143 double volume, 144 bool key_pressed) = 0; 145 146 // Close this synchronous writer. 147 virtual void Close() = 0; 148 }; 149 150 // AudioInputController::Create() can use the currently registered Factory 151 // to create the AudioInputController. Factory is intended for testing only. 152 // |user_input_monitor| is used for typing detection and can be NULL. 153 class Factory { 154 public: 155 virtual AudioInputController* Create( 156 AudioManager* audio_manager, 157 EventHandler* event_handler, 158 AudioParameters params, 159 UserInputMonitor* user_input_monitor) = 0; 160 161 protected: 162 virtual ~Factory() {} 163 }; 164 165 // Factory method for creating an AudioInputController. 166 // The audio device will be created on the audio thread, and when that is 167 // done, the event handler will receive an OnCreated() call from that same 168 // thread. |device_id| is the unique ID of the audio device to be opened. 169 // |user_input_monitor| is used for typing detection and can be NULL. 170 static scoped_refptr<AudioInputController> Create( 171 AudioManager* audio_manager, 172 EventHandler* event_handler, 173 const AudioParameters& params, 174 const std::string& device_id, 175 UserInputMonitor* user_input_monitor); 176 177 // Sets the factory used by the static method Create(). AudioInputController 178 // does not take ownership of |factory|. A value of NULL results in an 179 // AudioInputController being created directly. 180 static void set_factory_for_testing(Factory* factory) { factory_ = factory; } 181 AudioInputStream* stream_for_testing() { return stream_; } 182 183 // Factory method for creating an AudioInputController for low-latency mode. 184 // The audio device will be created on the audio thread, and when that is 185 // done, the event handler will receive an OnCreated() call from that same 186 // thread. |user_input_monitor| is used for typing detection and can be NULL. 187 static scoped_refptr<AudioInputController> CreateLowLatency( 188 AudioManager* audio_manager, 189 EventHandler* event_handler, 190 const AudioParameters& params, 191 const std::string& device_id, 192 // External synchronous writer for audio controller. 193 SyncWriter* sync_writer, 194 UserInputMonitor* user_input_monitor); 195 196 // Factory method for creating an AudioInputController for low-latency mode, 197 // taking ownership of |stream|. The stream will be opened on the audio 198 // thread, and when that is done, the event handler will receive an 199 // OnCreated() call from that same thread. |user_input_monitor| is used for 200 // typing detection and can be NULL. 201 static scoped_refptr<AudioInputController> CreateForStream( 202 const scoped_refptr<base::SingleThreadTaskRunner>& task_runner, 203 EventHandler* event_handler, 204 AudioInputStream* stream, 205 // External synchronous writer for audio controller. 206 SyncWriter* sync_writer, 207 UserInputMonitor* user_input_monitor); 208 209 // Starts recording using the created audio input stream. 210 // This method is called on the creator thread. 211 virtual void Record(); 212 213 // Closes the audio input stream. The state is changed and the resources 214 // are freed on the audio thread. |closed_task| is then executed on the thread 215 // that called Close(). 216 // Callbacks (EventHandler and SyncWriter) must exist until |closed_task| 217 // is called. 218 // It is safe to call this method more than once. Calls after the first one 219 // will have no effect. 220 // This method trampolines to the audio thread. 221 virtual void Close(const base::Closure& closed_task); 222 223 // Sets the capture volume of the input stream. The value 0.0 corresponds 224 // to muted and 1.0 to maximum volume. 225 virtual void SetVolume(double volume); 226 227 // Sets the Automatic Gain Control (AGC) state of the input stream. 228 // Changing the AGC state is not supported while recording is active. 229 virtual void SetAutomaticGainControl(bool enabled); 230 231 // AudioInputCallback implementation. Threading details depends on the 232 // device-specific implementation. 233 virtual void OnData(AudioInputStream* stream, const uint8* src, uint32 size, 234 uint32 hardware_delay_bytes, double volume) OVERRIDE; 235 virtual void OnError(AudioInputStream* stream) OVERRIDE; 236 237 bool SharedMemoryAndSyncSocketMode() const { return sync_writer_ != NULL; } 238 239 protected: 240 friend class base::RefCountedThreadSafe<AudioInputController>; 241 242 // Internal state of the source. 243 enum State { 244 CREATED, 245 RECORDING, 246 CLOSED 247 }; 248 249 AudioInputController(EventHandler* handler, 250 SyncWriter* sync_writer, 251 UserInputMonitor* user_input_monitor); 252 virtual ~AudioInputController(); 253 254 // Methods called on the audio thread (owned by the AudioManager). 255 void DoCreate(AudioManager* audio_manager, const AudioParameters& params, 256 const std::string& device_id); 257 void DoCreateForStream(AudioInputStream* stream_to_control, 258 bool enable_nodata_timer); 259 void DoRecord(); 260 void DoClose(); 261 void DoReportError(); 262 void DoSetVolume(double volume); 263 void DoSetAutomaticGainControl(bool enabled); 264 void DoOnData(scoped_ptr<uint8[]> data, uint32 size); 265 void DoLogAudioLevel(float level_dbfs); 266 267 // Method to check if we get recorded data after a stream was started, 268 // and log the result to UMA. 269 void FirstCheckForNoData(); 270 271 // Method which ensures that OnError() is triggered when data recording 272 // times out. Called on the audio thread. 273 void DoCheckForNoData(); 274 275 // Helper method that stops, closes, and NULL:s |*stream_|. 276 void DoStopCloseAndClearStream(); 277 278 void SetDataIsActive(bool enabled); 279 bool GetDataIsActive(); 280 281 // Gives access to the task runner of the creating thread. 282 scoped_refptr<base::SingleThreadTaskRunner> creator_task_runner_; 283 284 // The task runner of audio-manager thread that this object runs on. 285 scoped_refptr<base::SingleThreadTaskRunner> task_runner_; 286 287 // Contains the AudioInputController::EventHandler which receives state 288 // notifications from this class. 289 EventHandler* handler_; 290 291 // Pointer to the audio input stream object. 292 AudioInputStream* stream_; 293 294 // |no_data_timer_| is used to call OnError() when we stop receiving 295 // OnData() calls. This can occur when an audio input device is unplugged 296 // whilst recording on Windows. 297 // See http://crbug.com/79936 for details. 298 // This member is only touched by the audio thread. 299 scoped_ptr<base::Timer> no_data_timer_; 300 301 // This flag is used to signal that we are receiving OnData() calls, i.e, 302 // that data is active. It can be touched by the audio thread and by the 303 // low-level audio thread which calls OnData(). E.g. on Windows, the 304 // low-level audio thread is called wasapi_capture_thread. 305 base::subtle::Atomic32 data_is_active_; 306 307 // |state_| is written on the audio thread and is read on the hardware audio 308 // thread. These operations need to be locked. But lock is not required for 309 // reading on the audio input controller thread. 310 State state_; 311 312 base::Lock lock_; 313 314 // SyncWriter is used only in low-latency mode for synchronous writing. 315 SyncWriter* sync_writer_; 316 317 static Factory* factory_; 318 319 double max_volume_; 320 321 UserInputMonitor* user_input_monitor_; 322 323#if defined(AUDIO_POWER_MONITORING) 324 // Scans audio samples from OnData() as input to compute audio levels. 325 scoped_ptr<AudioPowerMonitor> audio_level_; 326 327 // We need these to be able to feed data to the AudioPowerMonitor. 328 scoped_ptr<AudioBus> audio_bus_; 329 media::AudioParameters audio_params_; 330 base::TimeTicks last_audio_level_log_time_; 331#endif 332 333 size_t prev_key_down_count_; 334 335 DISALLOW_COPY_AND_ASSIGN(AudioInputController); 336}; 337 338} // namespace media 339 340#endif // MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_ 341