audio_input_controller.h revision 5821806d5e7f356e8fa4b058a389a808ea183019 
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.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//
73namespace media {
74
75class 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, int error_code) = 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.
126  static scoped_refptr<AudioInputController> Create(
127      AudioManager* audio_manager,
128      EventHandler* event_handler,
129      const AudioParameters& params);
130
131  // Sets the factory used by the static method Create(). AudioInputController
132  // does not take ownership of |factory|. A value of NULL results in an
133  // AudioInputController being created directly.
134  static void set_factory_for_testing(Factory* factory) { factory_ = factory; }
135  AudioInputStream* stream_for_testing() { return stream_; }
136
137  // Factory method for creating an AudioInputController for low-latency mode.
138  // The audio device will be created on the audio thread, and when that is
139  // done, the event handler will receive an OnCreated() call from that same
140  // thread.
141  static scoped_refptr<AudioInputController> CreateLowLatency(
142      AudioManager* audio_manager,
143      EventHandler* event_handler,
144      const AudioParameters& params,
145      const std::string& device_id,
146      // External synchronous writer for audio controller.
147      SyncWriter* sync_writer);
148
149  // Starts recording using the created audio input stream.
150  // This method is called on the creator thread.
151  virtual void Record();
152
153  // Closes the audio input stream. The state is changed and the resources
154  // are freed on the audio thread. |closed_task| is then executed on the thread
155  // that called Close().
156  // Callbacks (EventHandler and SyncWriter) must exist until |closed_task|
157  // is called.
158  // It is safe to call this method more than once. Calls after the first one
159  // will have no effect.
160  // This method trampolines to the audio thread.
161  virtual void Close(const base::Closure& closed_task);
162
163  // Sets the capture volume of the input stream. The value 0.0 corresponds
164  // to muted and 1.0 to maximum volume.
165  virtual void SetVolume(double volume);
166
167  // Sets the Automatic Gain Control (AGC) state of the input stream.
168  // Changing the AGC state is not supported while recording is active.
169  virtual void SetAutomaticGainControl(bool enabled);
170
171  // AudioInputCallback implementation. Threading details depends on the
172  // device-specific implementation.
173  virtual void OnData(AudioInputStream* stream, const uint8* src, uint32 size,
174                      uint32 hardware_delay_bytes, double volume) OVERRIDE;
175  virtual void OnClose(AudioInputStream* stream) OVERRIDE;
176  virtual void OnError(AudioInputStream* stream, int code) OVERRIDE;
177
178  bool LowLatencyMode() const { return sync_writer_ != NULL; }
179
180 protected:
181  friend class base::RefCountedThreadSafe<AudioInputController>;
182
183  // Internal state of the source.
184  enum State {
185    kEmpty,
186    kCreated,
187    kRecording,
188    kClosed,
189    kError
190  };
191
192  AudioInputController(EventHandler* handler, SyncWriter* sync_writer);
193  virtual ~AudioInputController();
194
195  // Methods called on the audio thread (owned by the AudioManager).
196  void DoCreate(AudioManager* audio_manager, const AudioParameters& params,
197                const std::string& device_id);
198  void DoRecord();
199  void DoClose();
200  void DoReportError(int code);
201  void DoSetVolume(double volume);
202  void DoSetAutomaticGainControl(bool enabled);
203
204  // Method which ensures that OnError() is triggered when data recording
205  // times out. Called on the audio thread.
206  void DoCheckForNoData();
207
208  // Helper method that stops, closes, and NULL:s |*stream_|.
209  // Signals event when done if the event is not NULL.
210  void DoStopCloseAndClearStream(base::WaitableEvent* done);
211
212  void SetDataIsActive(bool enabled);
213  bool GetDataIsActive();
214
215  // Gives access to the message loop of the creating thread.
216  scoped_refptr<base::MessageLoopProxy> creator_loop_;
217
218  // The message loop of audio-manager thread that this object runs on.
219  scoped_refptr<base::MessageLoopProxy> message_loop_;
220
221  // Contains the AudioInputController::EventHandler which receives state
222  // notifications from this class.
223  EventHandler* handler_;
224
225  // Pointer to the audio input stream object.
226  AudioInputStream* stream_;
227
228  // |no_data_timer_| is used to call OnError() when we stop receiving
229  // OnData() calls without an OnClose() call. This can occur
230  // when an audio input device is unplugged whilst recording on Windows.
231  // See http://crbug.com/79936 for details.
232  // This member is only touched by the audio thread.
233  scoped_ptr<base::Timer> no_data_timer_;
234
235  // This flag is used to signal that we are receiving OnData() calls, i.e,
236  // that data is active. It can be touched by the audio thread and by the
237  // low-level audio thread which calls OnData(). E.g. on Windows, the
238  // low-level audio thread is called wasapi_capture_thread.
239  base::subtle::Atomic32 data_is_active_;
240
241  // |state_| is written on the audio thread and is read on the hardware audio
242  // thread. These operations need to be locked. But lock is not required for
243  // reading on the audio input controller thread.
244  State state_;
245
246  base::Lock lock_;
247
248  // SyncWriter is used only in low-latency mode for synchronous writing.
249  SyncWriter* sync_writer_;
250
251  static Factory* factory_;
252
253  double max_volume_;
254
255  DISALLOW_COPY_AND_ASSIGN(AudioInputController);
256};
257
258}  // namespace media
259
260#endif  // MEDIA_AUDIO_AUDIO_INPUT_CONTROLLER_H_
261