Merge Chromium + Blink git repositories
[chromium-blink-merge.git] / media / audio / audio_input_controller.h
blob58e04640aaa87666fb73a33f97ab09e9de158af2
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_
8 #include <string>
9 #include "base/atomicops.h"
10 #include "base/callback.h"
11 #include "base/files/file.h"
12 #include "base/memory/ref_counted.h"
13 #include "base/memory/scoped_ptr.h"
14 #include "base/synchronization/lock.h"
15 #include "base/synchronization/waitable_event.h"
16 #include "base/threading/thread.h"
17 #include "base/timer/timer.h"
18 #include "media/audio/audio_io.h"
19 #include "media/audio/audio_manager_base.h"
20 #include "media/audio/audio_parameters.h"
21 #include "media/base/audio_bus.h"
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().
28 // All public methods of AudioInputController are non-blocking.
30 // Here is a state diagram for the AudioInputController:
32 // .--> [ Closed / Error ] <--.
33 // | |
34 // | |
35 // [ Created ] ----------> [ Recording ]
36 // ^
37 // |
38 // *[ Empty ]
40 // * Initial state
42 // State sequences (assuming low-latency):
44 // [Creating Thread] [Audio Thread]
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)
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).
76 namespace media {
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
83 class AudioInputWriter;
84 class UserInputMonitor;
86 class MEDIA_EXPORT AudioInputController
87 : public base::RefCountedThreadSafe<AudioInputController>,
88 public AudioInputStream::AudioInputCallback {
89 public:
91 // Error codes to make native loggin more clear. These error codes are added
92 // to generic error strings to provide a higher degree of details.
93 // Changing these values can lead to problems when matching native debug
94 // logs with the actual cause of error.
95 enum ErrorCode {
96 // An unspecified error occured.
97 UNKNOWN_ERROR = 0,
99 // Failed to create an audio input stream.
100 STREAM_CREATE_ERROR, // = 1
102 // Failed to open an audio input stream.
103 STREAM_OPEN_ERROR, // = 2
105 // Native input stream reports an error. Exact reason differs between
106 // platforms.
107 STREAM_ERROR, // = 3
109 // This can happen if a capture device has been removed or disabled.
110 NO_DATA_ERROR, // = 4
113 // An event handler that receives events from the AudioInputController. The
114 // following methods are all called on the audio thread.
115 class MEDIA_EXPORT EventHandler {
116 public:
117 virtual void OnCreated(AudioInputController* controller) = 0;
118 virtual void OnRecording(AudioInputController* controller) = 0;
119 virtual void OnError(AudioInputController* controller,
120 ErrorCode error_code) = 0;
121 virtual void OnData(AudioInputController* controller,
122 const AudioBus* data) = 0;
123 virtual void OnLog(AudioInputController* controller,
124 const std::string& message) = 0;
126 protected:
127 virtual ~EventHandler() {}
130 // A synchronous writer interface used by AudioInputController for
131 // synchronous writing.
132 class MEDIA_EXPORT SyncWriter {
133 public:
134 virtual ~SyncWriter() {}
136 // Write certain amount of data from |data|.
137 virtual void Write(const AudioBus* data,
138 double volume,
139 bool key_pressed,
140 uint32 hardware_delay_bytes) = 0;
142 // Close this synchronous writer.
143 virtual void Close() = 0;
146 // AudioInputController::Create() can use the currently registered Factory
147 // to create the AudioInputController. Factory is intended for testing only.
148 // |user_input_monitor| is used for typing detection and can be NULL.
149 class Factory {
150 public:
151 virtual AudioInputController* Create(
152 AudioManager* audio_manager,
153 EventHandler* event_handler,
154 AudioParameters params,
155 UserInputMonitor* user_input_monitor) = 0;
157 protected:
158 virtual ~Factory() {}
161 // Factory method for creating an AudioInputController.
162 // The audio device will be created on the audio thread, and when that is
163 // done, the event handler will receive an OnCreated() call from that same
164 // thread. |device_id| is the unique ID of the audio device to be opened.
165 // |user_input_monitor| is used for typing detection and can be NULL.
166 static scoped_refptr<AudioInputController> Create(
167 AudioManager* audio_manager,
168 EventHandler* event_handler,
169 const AudioParameters& params,
170 const std::string& device_id,
171 UserInputMonitor* user_input_monitor);
173 // Sets the factory used by the static method Create(). AudioInputController
174 // does not take ownership of |factory|. A value of NULL results in an
175 // AudioInputController being created directly.
176 static void set_factory_for_testing(Factory* factory) { factory_ = factory; }
177 AudioInputStream* stream_for_testing() { return stream_; }
179 // Factory method for creating an AudioInputController for low-latency mode.
180 // The audio device will be created on the audio thread, and when that is
181 // done, the event handler will receive an OnCreated() call from that same
182 // thread. |user_input_monitor| is used for typing detection and can be NULL.
183 static scoped_refptr<AudioInputController> CreateLowLatency(
184 AudioManager* audio_manager,
185 EventHandler* event_handler,
186 const AudioParameters& params,
187 const std::string& device_id,
188 // External synchronous writer for audio controller.
189 SyncWriter* sync_writer,
190 UserInputMonitor* user_input_monitor,
191 const bool agc_is_enabled);
193 // Factory method for creating an AudioInputController with an existing
194 // |stream| for low-latency mode, taking ownership of |stream|. The stream
195 // will be opened on the audio thread, and when that is done, the event
196 // handler will receive an OnCreated() call from that same thread.
197 // |user_input_monitor| is used for typing detection and can be NULL.
198 static scoped_refptr<AudioInputController> CreateForStream(
199 const scoped_refptr<base::SingleThreadTaskRunner>& task_runner,
200 EventHandler* event_handler,
201 AudioInputStream* stream,
202 // External synchronous writer for audio controller.
203 SyncWriter* sync_writer,
204 UserInputMonitor* user_input_monitor);
206 // Starts recording using the created audio input stream.
207 // This method is called on the creator thread.
208 virtual void Record();
210 // Closes the audio input stream. The state is changed and the resources
211 // are freed on the audio thread. |closed_task| is then executed on the thread
212 // that called Close().
213 // Callbacks (EventHandler and SyncWriter) must exist until |closed_task|
214 // is called.
215 // It is safe to call this method more than once. Calls after the first one
216 // will have no effect.
217 // This method trampolines to the audio thread.
218 virtual void Close(const base::Closure& closed_task);
220 // Sets the capture volume of the input stream. The value 0.0 corresponds
221 // to muted and 1.0 to maximum volume.
222 virtual void SetVolume(double volume);
224 // AudioInputCallback implementation. Threading details depends on the
225 // device-specific implementation.
226 void OnData(AudioInputStream* stream,
227 const AudioBus* source,
228 uint32 hardware_delay_bytes,
229 double volume) override;
230 void OnError(AudioInputStream* stream) override;
232 bool SharedMemoryAndSyncSocketMode() const { return sync_writer_ != NULL; }
234 // Enable debug recording of audio input.
235 void EnableDebugRecording(AudioInputWriter* input_writer);
237 // Disbale debug recording of audio input. Must be called before owner of
238 // |input_writer| deletes it.
239 void DisableDebugRecording(const base::Closure& callback);
241 protected:
242 friend class base::RefCountedThreadSafe<AudioInputController>;
244 // Internal state of the source.
245 enum State {
246 CREATED,
247 RECORDING,
248 CLOSED
251 #if defined(AUDIO_POWER_MONITORING)
252 // Used to log a silence report (see OnData).
253 // Elements in this enum should not be deleted or rearranged; the only
254 // permitted operation is to add new elements before SILENCE_STATE_MAX and
255 // update SILENCE_STATE_MAX.
256 // Possible silence state transitions:
257 // SILENCE_STATE_AUDIO_AND_SILENCE
258 // ^ ^
259 // SILENCE_STATE_ONLY_AUDIO SILENCE_STATE_ONLY_SILENCE
260 // ^ ^
261 // SILENCE_STATE_NO_MEASUREMENT
262 enum SilenceState {
263 SILENCE_STATE_NO_MEASUREMENT = 0,
264 SILENCE_STATE_ONLY_AUDIO = 1,
265 SILENCE_STATE_ONLY_SILENCE = 2,
266 SILENCE_STATE_AUDIO_AND_SILENCE = 3,
267 SILENCE_STATE_MAX = SILENCE_STATE_AUDIO_AND_SILENCE
269 #endif
271 AudioInputController(EventHandler* handler,
272 SyncWriter* sync_writer,
273 UserInputMonitor* user_input_monitor,
274 const bool agc_is_enabled);
275 ~AudioInputController() override;
277 // Methods called on the audio thread (owned by the AudioManager).
278 void DoCreate(AudioManager* audio_manager,
279 const AudioParameters& params,
280 const std::string& device_id);
281 void DoCreateForLowLatency(AudioManager* audio_manager,
282 const AudioParameters& params,
283 const std::string& device_id);
284 void DoCreateForStream(AudioInputStream* stream_to_control);
285 void DoRecord();
286 void DoClose();
287 void DoReportError();
288 void DoSetVolume(double volume);
289 void DoOnData(scoped_ptr<AudioBus> data);
290 void DoLogAudioLevels(float level_dbfs, int microphone_volume_percent);
292 // Method to check if we get recorded data after a stream was started,
293 // and log the result to UMA.
294 void FirstCheckForNoData();
296 // Method which ensures that OnError() is triggered when data recording
297 // times out. Called on the audio thread.
298 void DoCheckForNoData();
300 // Helper method that stops, closes, and NULL:s |*stream_|.
301 void DoStopCloseAndClearStream();
303 void SetDataIsActive(bool enabled);
304 bool GetDataIsActive();
306 #if defined(AUDIO_POWER_MONITORING)
307 // Updates the silence state, see enum SilenceState above for state
308 // transitions.
309 void UpdateSilenceState(bool silence);
311 // Logs the silence state as UMA stat.
312 void LogSilenceState(SilenceState value);
313 #endif
315 // Enable and disable debug recording of audio input. Called on the audio
316 // thread.
317 void DoEnableDebugRecording(AudioInputWriter* input_writer);
318 void DoDisableDebugRecording();
320 // Called on the audio thread.
321 void WriteInputDataForDebugging(scoped_ptr<AudioBus> data);
323 // Gives access to the task runner of the creating thread.
324 scoped_refptr<base::SingleThreadTaskRunner> creator_task_runner_;
326 // The task runner of audio-manager thread that this object runs on.
327 scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
329 // Contains the AudioInputController::EventHandler which receives state
330 // notifications from this class.
331 EventHandler* handler_;
333 // Pointer to the audio input stream object.
334 AudioInputStream* stream_;
336 // |no_data_timer_| is used to call OnError() when we stop receiving
337 // OnData() calls. This can occur when an audio input device is unplugged
338 // whilst recording on Windows.
339 // See http://crbug.com/79936 for details.
340 // This member is only touched by the audio thread.
341 scoped_ptr<base::Timer> no_data_timer_;
343 // This flag is used to signal that we are receiving OnData() calls, i.e,
344 // that data is active. It can be touched by the audio thread and by the
345 // low-level audio thread which calls OnData(). E.g. on Windows, the
346 // low-level audio thread is called wasapi_capture_thread.
347 base::subtle::Atomic32 data_is_active_;
349 // |state_| is written on the audio thread and is read on the hardware audio
350 // thread. These operations need to be locked. But lock is not required for
351 // reading on the audio input controller thread.
352 State state_;
354 base::Lock lock_;
356 // SyncWriter is used only in low-latency mode for synchronous writing.
357 SyncWriter* sync_writer_;
359 static Factory* factory_;
361 double max_volume_;
363 UserInputMonitor* user_input_monitor_;
365 const bool agc_is_enabled_;
367 #if defined(AUDIO_POWER_MONITORING)
368 // Enabled in DoCrete() but not in DoCreateForStream().
369 bool power_measurement_is_enabled_;
371 // Updated each time a power measurement is performed.
372 base::TimeTicks last_audio_level_log_time_;
374 // Whether the silence state should sent as UMA stat.
375 bool log_silence_state_;
377 // The silence report sent as UMA stat at the end of a session.
378 SilenceState silence_state_;
379 #endif
381 size_t prev_key_down_count_;
383 // Time when a low-latency stream is created.
384 base::TimeTicks low_latency_create_time_;
386 // Used for audio debug recordings. Accessed on audio thread.
387 AudioInputWriter* input_writer_;
389 DISALLOW_COPY_AND_ASSIGN(AudioInputController);
392 } // namespace media
394 #endif // MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_