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,
121                        const AudioBus* data) = 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|.
140    virtual void Write(const AudioBus* data,
141                       double volume,
142                       bool key_pressed) = 0;
143
144    // Close this synchronous writer.
145    virtual void Close() = 0;
146  };
147
148  // AudioInputController::Create() can use the currently registered Factory
149  // to create the AudioInputController. Factory is intended for testing only.
150  // |user_input_monitor| is used for typing detection and can be NULL.
151  class Factory {
152   public:
153    virtual AudioInputController* Create(
154        AudioManager* audio_manager,
155        EventHandler* event_handler,
156        AudioParameters params,
157        UserInputMonitor* user_input_monitor) = 0;
158
159   protected:
160    virtual ~Factory() {}
161  };
162
163  // Factory method for creating an AudioInputController.
164  // The audio device will be created on the audio thread, and when that is
165  // done, the event handler will receive an OnCreated() call from that same
166  // thread. |device_id| is the unique ID of the audio device to be opened.
167  // |user_input_monitor| is used for typing detection and can be NULL.
168  static scoped_refptr<AudioInputController> Create(
169      AudioManager* audio_manager,
170      EventHandler* event_handler,
171      const AudioParameters& params,
172      const std::string& device_id,
173      UserInputMonitor* user_input_monitor);
174
175  // Sets the factory used by the static method Create(). AudioInputController
176  // does not take ownership of |factory|. A value of NULL results in an
177  // AudioInputController being created directly.
178  static void set_factory_for_testing(Factory* factory) { factory_ = factory; }
179  AudioInputStream* stream_for_testing() { return stream_; }
180
181  // Factory method for creating an AudioInputController for low-latency mode.
182  // The audio device will be created on the audio thread, and when that is
183  // done, the event handler will receive an OnCreated() call from that same
184  // thread. |user_input_monitor| is used for typing detection and can be NULL.
185  static scoped_refptr<AudioInputController> CreateLowLatency(
186      AudioManager* audio_manager,
187      EventHandler* event_handler,
188      const AudioParameters& params,
189      const std::string& device_id,
190      // External synchronous writer for audio controller.
191      SyncWriter* sync_writer,
192      UserInputMonitor* user_input_monitor);
193
194  // Factory method for creating an AudioInputController with an existing
195  // |stream| for low-latency mode, taking ownership of |stream|. The stream
196  // will be opened on the audio thread, and when that is done, the event
197  // handler will receive an OnCreated() call from that same thread.
198  // |user_input_monitor| is used for typing detection and can be NULL.
199  static scoped_refptr<AudioInputController> CreateForStream(
200      const scoped_refptr<base::SingleThreadTaskRunner>& task_runner,
201      EventHandler* event_handler,
202      AudioInputStream* stream,
203      // External synchronous writer for audio controller.
204      SyncWriter* sync_writer,
205      UserInputMonitor* user_input_monitor);
206
207  // Starts recording using the created audio input stream.
208  // This method is called on the creator thread.
209  virtual void Record();
210
211  // Closes the audio input stream. The state is changed and the resources
212  // are freed on the audio thread. |closed_task| is then executed on the thread
213  // that called Close().
214  // Callbacks (EventHandler and SyncWriter) must exist until |closed_task|
215  // is called.
216  // It is safe to call this method more than once. Calls after the first one
217  // will have no effect.
218  // This method trampolines to the audio thread.
219  virtual void Close(const base::Closure& closed_task);
220
221  // Sets the capture volume of the input stream. The value 0.0 corresponds
222  // to muted and 1.0 to maximum volume.
223  virtual void SetVolume(double volume);
224
225  // Sets the Automatic Gain Control (AGC) state of the input stream.
226  // Changing the AGC state is not supported while recording is active.
227  virtual void SetAutomaticGainControl(bool enabled);
228
229  // AudioInputCallback implementation. Threading details depends on the
230  // device-specific implementation.
231  virtual void OnData(AudioInputStream* stream,
232                      const AudioBus* source,
233                      uint32 hardware_delay_bytes,
234                      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#if defined(AUDIO_POWER_MONITORING)
250  // Used to log a silence report (see OnData).
251  // Elements in this enum should not be deleted or rearranged; the only
252  // permitted operation is to add new elements before SILENCE_STATE_MAX and
253  // update SILENCE_STATE_MAX.
254  // Possible silence state transitions:
255  //           SILENCE_STATE_AUDIO_AND_SILENCE
256  //               ^                  ^
257  // SILENCE_STATE_ONLY_AUDIO   SILENCE_STATE_ONLY_SILENCE
258  //               ^                  ^
259  //            SILENCE_STATE_NO_MEASUREMENT
260  enum SilenceState {
261    SILENCE_STATE_NO_MEASUREMENT = 0,
262    SILENCE_STATE_ONLY_AUDIO = 1,
263    SILENCE_STATE_ONLY_SILENCE = 2,
264    SILENCE_STATE_AUDIO_AND_SILENCE = 3,
265    SILENCE_STATE_MAX = SILENCE_STATE_AUDIO_AND_SILENCE
266  };
267#endif
268
269  AudioInputController(EventHandler* handler,
270                       SyncWriter* sync_writer,
271                       UserInputMonitor* user_input_monitor);
272  virtual ~AudioInputController();
273
274  // Methods called on the audio thread (owned by the AudioManager).
275  void DoCreate(AudioManager* audio_manager,
276                const AudioParameters& params,
277                const std::string& device_id);
278  void DoCreateForLowLatency(AudioManager* audio_manager,
279                             const AudioParameters& params,
280                             const std::string& device_id);
281  void DoCreateForStream(AudioInputStream* stream_to_control);
282  void DoRecord();
283  void DoClose();
284  void DoReportError();
285  void DoSetVolume(double volume);
286  void DoSetAutomaticGainControl(bool enabled);
287  void DoOnData(scoped_ptr<AudioBus> data);
288  void DoLogAudioLevels(float level_dbfs, int microphone_volume_percent);
289
290  // Method to check if we get recorded data after a stream was started,
291  // and log the result to UMA.
292  void FirstCheckForNoData();
293
294  // Method which ensures that OnError() is triggered when data recording
295  // times out. Called on the audio thread.
296  void DoCheckForNoData();
297
298  // Helper method that stops, closes, and NULL:s |*stream_|.
299  void DoStopCloseAndClearStream();
300
301  void SetDataIsActive(bool enabled);
302  bool GetDataIsActive();
303
304#if defined(AUDIO_POWER_MONITORING)
305  // Updates the silence state, see enum SilenceState above for state
306  // transitions.
307  void UpdateSilenceState(bool silence);
308
309  // Logs the silence state as UMA stat.
310  void LogSilenceState(SilenceState value);
311#endif
312
313  // Gives access to the task runner of the creating thread.
314  scoped_refptr<base::SingleThreadTaskRunner> creator_task_runner_;
315
316  // The task runner of audio-manager thread that this object runs on.
317  scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
318
319  // Contains the AudioInputController::EventHandler which receives state
320  // notifications from this class.
321  EventHandler* handler_;
322
323  // Pointer to the audio input stream object.
324  AudioInputStream* stream_;
325
326  // |no_data_timer_| is used to call OnError() when we stop receiving
327  // OnData() calls. This can occur when an audio input device is unplugged
328  // whilst recording on Windows.
329  // See http://crbug.com/79936 for details.
330  // This member is only touched by the audio thread.
331  scoped_ptr<base::Timer> no_data_timer_;
332
333  // This flag is used to signal that we are receiving OnData() calls, i.e,
334  // that data is active. It can be touched by the audio thread and by the
335  // low-level audio thread which calls OnData(). E.g. on Windows, the
336  // low-level audio thread is called wasapi_capture_thread.
337  base::subtle::Atomic32 data_is_active_;
338
339  // |state_| is written on the audio thread and is read on the hardware audio
340  // thread. These operations need to be locked. But lock is not required for
341  // reading on the audio input controller thread.
342  State state_;
343
344  base::Lock lock_;
345
346  // SyncWriter is used only in low-latency mode for synchronous writing.
347  SyncWriter* sync_writer_;
348
349  static Factory* factory_;
350
351  double max_volume_;
352
353  UserInputMonitor* user_input_monitor_;
354
355#if defined(AUDIO_POWER_MONITORING)
356  // Scans audio samples from OnData() as input to compute audio levels.
357  scoped_ptr<AudioPowerMonitor> audio_level_;
358
359  // We need these to be able to feed data to the AudioPowerMonitor.
360  media::AudioParameters audio_params_;
361  base::TimeTicks last_audio_level_log_time_;
362
363  // Whether the silence state should sent as UMA stat.
364  bool log_silence_state_;
365
366  // The silence report sent as UMA stat at the end of a session.
367  SilenceState silence_state_;
368#endif
369
370  size_t prev_key_down_count_;
371
372  // Time when a low-latency stream is created.
373  base::TimeTicks low_latency_create_time_;
374
375  DISALLOW_COPY_AND_ASSIGN(AudioInputController);
376};
377
378}  // namespace media
379
380#endif  // MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_
381