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 // 73 namespace media { 74 75 class MEDIA_EXPORT AudioInputController 76 : public base::RefCountedThreadSafe<AudioInputController>, 77 public AudioInputStream::AudioInputCallback { 78 public: 79 // An event handler that receives events from the AudioInputController. The 80 // following methods are all called on the audio thread. 81 class MEDIA_EXPORT EventHandler { 82 public: 83 virtual void OnCreated(AudioInputController* controller) = 0; 84 virtual void OnRecording(AudioInputController* controller) = 0; 85 virtual void OnError(AudioInputController* controller) = 0; 86 virtual void OnData(AudioInputController* controller, const uint8* data, 87 uint32 size) = 0; 88 89 protected: 90 virtual ~EventHandler() {} 91 }; 92 93 // A synchronous writer interface used by AudioInputController for 94 // synchronous writing. 95 class SyncWriter { 96 public: 97 virtual ~SyncWriter() {} 98 99 // Notify the synchronous writer about the number of bytes in the 100 // soundcard which has been recorded. 101 virtual void UpdateRecordedBytes(uint32 bytes) = 0; 102 103 // Write certain amount of data from |data|. This method returns 104 // number of written bytes. 105 virtual uint32 Write(const void* data, uint32 size, double volume) = 0; 106 107 // Close this synchronous writer. 108 virtual void Close() = 0; 109 }; 110 111 // AudioInputController::Create() can use the currently registered Factory 112 // to create the AudioInputController. Factory is intended for testing only. 113 class Factory { 114 public: 115 virtual AudioInputController* Create(AudioManager* audio_manager, 116 EventHandler* event_handler, 117 AudioParameters params) = 0; 118 protected: 119 virtual ~Factory() {} 120 }; 121 122 // Factory method for creating an AudioInputController. 123 // The audio device will be created on the audio thread, and when that is 124 // done, the event handler will receive an OnCreated() call from that same 125 // thread. |device_id| is the unique ID of the audio device to be opened. 126 static scoped_refptr<AudioInputController> Create( 127 AudioManager* audio_manager, 128 EventHandler* event_handler, 129 const AudioParameters& params, 130 const std::string& device_id); 131 132 // Sets the factory used by the static method Create(). AudioInputController 133 // does not take ownership of |factory|. A value of NULL results in an 134 // AudioInputController being created directly. 135 static void set_factory_for_testing(Factory* factory) { factory_ = factory; } 136 AudioInputStream* stream_for_testing() { return stream_; } 137 138 // Factory method for creating an AudioInputController for low-latency mode. 139 // The audio device will be created on the audio thread, and when that is 140 // done, the event handler will receive an OnCreated() call from that same 141 // thread. 142 static scoped_refptr<AudioInputController> CreateLowLatency( 143 AudioManager* audio_manager, 144 EventHandler* event_handler, 145 const AudioParameters& params, 146 const std::string& device_id, 147 // External synchronous writer for audio controller. 148 SyncWriter* sync_writer); 149 150 // Factory method for creating an AudioInputController for low-latency mode, 151 // taking ownership of |stream|. The stream will be opened on the audio 152 // thread, and when that is done, the event handler will receive an 153 // OnCreated() call from that same thread. 154 static scoped_refptr<AudioInputController> CreateForStream( 155 const scoped_refptr<base::MessageLoopProxy>& message_loop, 156 EventHandler* event_handler, 157 AudioInputStream* stream, 158 // External synchronous writer for audio controller. 159 SyncWriter* sync_writer); 160 161 // Starts recording using the created audio input stream. 162 // This method is called on the creator thread. 163 virtual void Record(); 164 165 // Closes the audio input stream. The state is changed and the resources 166 // are freed on the audio thread. |closed_task| is then executed on the thread 167 // that called Close(). 168 // Callbacks (EventHandler and SyncWriter) must exist until |closed_task| 169 // is called. 170 // It is safe to call this method more than once. Calls after the first one 171 // will have no effect. 172 // This method trampolines to the audio thread. 173 virtual void Close(const base::Closure& closed_task); 174 175 // Sets the capture volume of the input stream. The value 0.0 corresponds 176 // to muted and 1.0 to maximum volume. 177 virtual void SetVolume(double volume); 178 179 // Sets the Automatic Gain Control (AGC) state of the input stream. 180 // Changing the AGC state is not supported while recording is active. 181 virtual void SetAutomaticGainControl(bool enabled); 182 183 // AudioInputCallback implementation. Threading details depends on the 184 // device-specific implementation. 185 virtual void OnData(AudioInputStream* stream, const uint8* src, uint32 size, 186 uint32 hardware_delay_bytes, double volume) OVERRIDE; 187 virtual void OnClose(AudioInputStream* stream) OVERRIDE; 188 virtual void OnError(AudioInputStream* stream) OVERRIDE; 189 190 bool LowLatencyMode() const { return sync_writer_ != NULL; } 191 192 protected: 193 friend class base::RefCountedThreadSafe<AudioInputController>; 194 195 // Internal state of the source. 196 enum State { 197 kEmpty, 198 kCreated, 199 kRecording, 200 kClosed, 201 kError 202 }; 203 204 AudioInputController(EventHandler* handler, SyncWriter* sync_writer); 205 virtual ~AudioInputController(); 206 207 // Methods called on the audio thread (owned by the AudioManager). 208 void DoCreate(AudioManager* audio_manager, const AudioParameters& params, 209 const std::string& device_id); 210 void DoCreateForStream(AudioInputStream* stream_to_control, 211 bool enable_nodata_timer); 212 void DoRecord(); 213 void DoClose(); 214 void DoReportError(); 215 void DoSetVolume(double volume); 216 void DoSetAutomaticGainControl(bool enabled); 217 218 // Method which ensures that OnError() is triggered when data recording 219 // times out. Called on the audio thread. 220 void DoCheckForNoData(); 221 222 // Helper method that stops, closes, and NULL:s |*stream_|. 223 // Signals event when done if the event is not NULL. 224 void DoStopCloseAndClearStream(base::WaitableEvent* done); 225 226 void SetDataIsActive(bool enabled); 227 bool GetDataIsActive(); 228 229 // Gives access to the message loop of the creating thread. 230 scoped_refptr<base::MessageLoopProxy> creator_loop_; 231 232 // The message loop of audio-manager thread that this object runs on. 233 scoped_refptr<base::MessageLoopProxy> message_loop_; 234 235 // Contains the AudioInputController::EventHandler which receives state 236 // notifications from this class. 237 EventHandler* handler_; 238 239 // Pointer to the audio input stream object. 240 AudioInputStream* stream_; 241 242 // |no_data_timer_| is used to call OnError() when we stop receiving 243 // OnData() calls without an OnClose() call. This can occur 244 // when an audio input device is unplugged whilst recording on Windows. 245 // See http://crbug.com/79936 for details. 246 // This member is only touched by the audio thread. 247 scoped_ptr<base::Timer> no_data_timer_; 248 249 // This flag is used to signal that we are receiving OnData() calls, i.e, 250 // that data is active. It can be touched by the audio thread and by the 251 // low-level audio thread which calls OnData(). E.g. on Windows, the 252 // low-level audio thread is called wasapi_capture_thread. 253 base::subtle::Atomic32 data_is_active_; 254 255 // |state_| is written on the audio thread and is read on the hardware audio 256 // thread. These operations need to be locked. But lock is not required for 257 // reading on the audio input controller thread. 258 State state_; 259 260 base::Lock lock_; 261 262 // SyncWriter is used only in low-latency mode for synchronous writing. 263 SyncWriter* sync_writer_; 264 265 static Factory* factory_; 266 267 double max_volume_; 268 269 DISALLOW_COPY_AND_ASSIGN(AudioInputController); 270 }; 271 272 } // namespace media 273 274 #endif // MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_ 275
