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 #ifndef MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_
6 #define MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_
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"
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().
25 // All public methods of AudioInputController are non-blocking.
27 // Here is a state diagram for the AudioInputController:
29 // .--> [ Closed / Error ] <--.
32 // [ Created ] ----------> [ Recording ]
39 // State sequences (assuming low-latency):
41 // [Creating Thread] [Audio Thread]
43 // User AudioInputController EventHandler
44 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
45 // CrateLowLatency() ==> DoCreate()
46 // AudioManager::MakeAudioInputStream()
47 // AudioInputStream::Open()
48 // .- - - - - - - - - - - - -> OnError()
49 // create the data timer
50 // .-------------------------> OnCreated()
52 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
53 // Record() ==> DoRecord()
54 // AudioInputStream::Start()
55 // .-------------------------> OnRecording()
56 // start the data timer
58 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
59 // Close() ==> DoClose()
60 // delete the data timer
62 // AudioInputStream::Stop()
63 // AudioInputStream::Close()
64 // SyncWriter::Close()
65 // Closure::Run() <-----------------.
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).
75 class UserInputMonitor;
77 class MEDIA_EXPORT AudioInputController
78 : public base::RefCountedThreadSafe<AudioInputController>,
79 public AudioInputStream::AudioInputCallback {
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 {
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,
92 virtual ~EventHandler() {}
95 // A synchronous writer interface used by AudioInputController for
96 // synchronous writing.
99 virtual ~SyncWriter() {}
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;
105 // Write certain amount of data from |data|. This method returns
106 // number of written bytes.
107 virtual uint32 Write(const void* data,
110 bool key_pressed) = 0;
112 // Close this synchronous writer.
113 virtual void Close() = 0;
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.
121 virtual AudioInputController* Create(
122 AudioManager* audio_manager,
123 EventHandler* event_handler,
124 AudioParameters params,
125 UserInputMonitor* user_input_monitor) = 0;
128 virtual ~Factory() {}
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);
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_; }
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);
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);
175 // Starts recording using the created audio input stream.
176 // This method is called on the creator thread.
177 virtual void Record();
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|
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);
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);
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);
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;
203 bool LowLatencyMode() const { return sync_writer_ != NULL; }
206 friend class base::RefCountedThreadSafe<AudioInputController>;
208 // Internal state of the source.
217 AudioInputController(EventHandler* handler,
218 SyncWriter* sync_writer,
219 UserInputMonitor* user_input_monitor);
220 virtual ~AudioInputController();
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);
229 void DoReportError();
230 void DoSetVolume(double volume);
231 void DoSetAutomaticGainControl(bool enabled);
233 // Method which ensures that OnError() is triggered when data recording
234 // times out. Called on the audio thread.
235 void DoCheckForNoData();
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);
241 void SetDataIsActive(bool enabled);
242 bool GetDataIsActive();
244 // Gives access to the task runner of the creating thread.
245 scoped_refptr<base::SingleThreadTaskRunner> creator_task_runner_;
247 // The task runner of audio-manager thread that this object runs on.
248 scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
250 // Contains the AudioInputController::EventHandler which receives state
251 // notifications from this class.
252 EventHandler* handler_;
254 // Pointer to the audio input stream object.
255 AudioInputStream* stream_;
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_;
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_;
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.
277 // SyncWriter is used only in low-latency mode for synchronous writing.
278 SyncWriter* sync_writer_;
280 static Factory* factory_;
284 UserInputMonitor* user_input_monitor_;
286 size_t prev_key_down_count_;
288 DISALLOW_COPY_AND_ASSIGN(AudioInputController);
293 #endif // MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_