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 // Implementation of AudioInputStream for Windows using Windows Core Audio
6 // WASAPI for low latency capturing.
8 // Overview of operation:
10 // - An object of WASAPIAudioInputStream is created by the AudioManager
12 // - Next some thread will call Open(), at that point the underlying
13 // Core Audio APIs are utilized to create two WASAPI interfaces called
14 // IAudioClient and IAudioCaptureClient.
15 // - Then some thread will call Start(sink).
16 // A thread called "wasapi_capture_thread" is started and this thread listens
17 // on an event signal which is set periodically by the audio engine for
18 // each recorded data packet. As a result, data samples will be provided
19 // to the registered sink.
20 // - At some point, a thread will call Stop(), which stops and joins the
21 // capture thread and at the same time stops audio streaming.
22 // - The same thread that called stop will call Close() where we cleanup
23 // and notify the audio manager, which likely will destroy this object.
25 // Implementation notes:
27 // - The minimum supported client is Windows Vista.
28 // - This implementation is single-threaded, hence:
29 // o Construction and destruction must take place from the same thread.
30 // o It is recommended to call all APIs from the same thread as well.
31 // - It is recommended to first acquire the native sample rate of the default
32 // input device and then use the same rate when creating this object. Use
33 // WASAPIAudioInputStream::HardwareSampleRate() to retrieve the sample rate.
34 // - Calling Close() also leads to self destruction.
36 // Core Audio API details:
38 // - Utilized MMDevice interfaces:
39 // o IMMDeviceEnumerator
41 // - Utilized WASAPI interfaces:
43 // o IAudioCaptureClient
44 // - The stream is initialized in shared mode and the processing of the
45 // audio buffer is event driven.
46 // - The Multimedia Class Scheduler service (MMCSS) is utilized to boost
47 // the priority of the capture thread.
48 // - Audio applications that use the MMDevice API and WASAPI typically use
49 // the ISimpleAudioVolume interface to manage stream volume levels on a
50 // per-session basis. It is also possible to use of the IAudioEndpointVolume
51 // interface to control the master volume level of an audio endpoint device.
52 // This implementation is using the ISimpleAudioVolume interface.
53 // MSDN states that "In rare cases, a specialized audio application might
54 // require the use of the IAudioEndpointVolume".
56 #ifndef MEDIA_AUDIO_WIN_AUDIO_LOW_LATENCY_INPUT_WIN_H_
57 #define MEDIA_AUDIO_WIN_AUDIO_LOW_LATENCY_INPUT_WIN_H_
59 #include <Audioclient.h>
60 #include <MMDeviceAPI.h>
64 #include "base/compiler_specific.h"
65 #include "base/threading/non_thread_safe.h"
66 #include "base/threading/platform_thread.h"
67 #include "base/threading/simple_thread.h"
68 #include "base/win/scoped_co_mem.h"
69 #include "base/win/scoped_com_initializer.h"
70 #include "base/win/scoped_comptr.h"
71 #include "base/win/scoped_handle.h"
72 #include "media/audio/agc_audio_stream.h"
73 #include "media/audio/audio_parameters.h"
74 #include "media/base/media_export.h"
79 class AudioManagerWin;
81 // AudioInputStream implementation using Windows Core Audio APIs.
82 class MEDIA_EXPORT WASAPIAudioInputStream
83 : public AgcAudioStream<AudioInputStream>,
84 public base::DelegateSimpleThread::Delegate,
85 NON_EXPORTED_BASE(public base::NonThreadSafe) {
87 // The ctor takes all the usual parameters, plus |manager| which is the
88 // the audio manager who is creating this object.
89 WASAPIAudioInputStream(AudioManagerWin* manager,
90 const AudioParameters& params,
91 const std::string& device_id);
93 // The dtor is typically called by the AudioManager only and it is usually
94 // triggered by calling AudioInputStream::Close().
95 virtual ~WASAPIAudioInputStream();
97 // Implementation of AudioInputStream.
98 virtual bool Open() OVERRIDE;
99 virtual void Start(AudioInputCallback* callback) OVERRIDE;
100 virtual void Stop() OVERRIDE;
101 virtual void Close() OVERRIDE;
102 virtual double GetMaxVolume() OVERRIDE;
103 virtual void SetVolume(double volume) OVERRIDE;
104 virtual double GetVolume() OVERRIDE;
106 bool started() const { return started_; }
108 // Returns the default hardware audio parameters of the specific device.
109 static AudioParameters GetInputStreamParameters(const std::string& device_id);
112 // DelegateSimpleThread::Delegate implementation.
113 virtual void Run() OVERRIDE;
115 // Issues the OnError() callback to the |sink_|.
116 void HandleError(HRESULT err);
118 // The Open() method is divided into these sub methods.
119 HRESULT SetCaptureDevice();
120 HRESULT ActivateCaptureDevice();
121 HRESULT GetAudioEngineStreamFormat();
122 bool DesiredFormatIsSupported();
123 HRESULT InitializeAudioEngine();
125 // Retrieves the stream format that the audio engine uses for its internal
126 // processing/mixing of shared-mode streams.
127 // |effects| is a an AudioParameters::effects() flag that will have the
128 // DUCKING flag raised for only the default communication device.
129 static HRESULT GetMixFormat(const std::string& device_id,
130 WAVEFORMATEX** device_format,
133 // Our creator, the audio manager needs to be notified when we close.
134 AudioManagerWin* manager_;
136 // Capturing is driven by this thread (which has no message loop).
137 // All OnData() callbacks will be called from this thread.
138 base::DelegateSimpleThread* capture_thread_;
140 // Contains the desired audio format which is set up at construction.
141 WAVEFORMATEX format_;
146 // Size in bytes of each audio frame (4 bytes for 16-bit stereo PCM)
149 // Size in audio frames of each audio packet where an audio packet
150 // is defined as the block of data which the user received in each
151 // OnData() callback.
152 size_t packet_size_frames_;
154 // Size in bytes of each audio packet.
155 size_t packet_size_bytes_;
157 // Length of the audio endpoint buffer.
158 uint32 endpoint_buffer_size_frames_;
160 // A copy of the supplied AudioParameter's |effects|. If ducking was
161 // specified (desired device=communications) but we ended up not being
162 // able to open the communications device, this flag will be cleared.
165 // Contains the unique name of the selected endpoint device.
166 // Note that AudioManagerBase::kDefaultDeviceId represents the default
167 // device role and is not a valid ID as such.
168 std::string device_id_;
170 // Conversion factor used in delay-estimation calculations.
171 // Converts a raw performance counter value to 100-nanosecond unit.
172 double perf_count_to_100ns_units_;
174 // Conversion factor used in delay-estimation calculations.
175 // Converts from milliseconds to audio frames.
176 double ms_to_frame_count_;
178 // Pointer to the object that will receive the recorded audio samples.
179 AudioInputCallback* sink_;
181 // Windows Multimedia Device (MMDevice) API interfaces.
183 // An IMMDevice interface which represents an audio endpoint device.
184 base::win::ScopedComPtr<IMMDevice> endpoint_device_;
186 // Windows Audio Session API (WASAPI) interfaces.
188 // An IAudioClient interface which enables a client to create and initialize
189 // an audio stream between an audio application and the audio engine.
190 base::win::ScopedComPtr<IAudioClient> audio_client_;
192 // Loopback IAudioClient doesn't support event-driven mode, so a separate
193 // IAudioClient is needed to receive notifications when data is available in
194 // the buffer. For loopback input |audio_client_| is used to receive data,
195 // while |audio_render_client_for_loopback_| is used to get notifications
196 // when a new buffer is ready. See comment in InitializeAudioEngine() for
198 base::win::ScopedComPtr<IAudioClient> audio_render_client_for_loopback_;
200 // The IAudioCaptureClient interface enables a client to read input data
201 // from a capture endpoint buffer.
202 base::win::ScopedComPtr<IAudioCaptureClient> audio_capture_client_;
204 // The ISimpleAudioVolume interface enables a client to control the
205 // master volume level of an audio session.
206 // The volume-level is a value in the range 0.0 to 1.0.
207 // This interface does only work with shared-mode streams.
208 base::win::ScopedComPtr<ISimpleAudioVolume> simple_audio_volume_;
210 // The audio engine will signal this event each time a buffer has been
212 base::win::ScopedHandle audio_samples_ready_event_;
214 // This event will be signaled when capturing shall stop.
215 base::win::ScopedHandle stop_capture_event_;
217 // Extra audio bus used for storage of deinterleaved data for the OnData
219 scoped_ptr<media::AudioBus> audio_bus_;
221 DISALLOW_COPY_AND_ASSIGN(WASAPIAudioInputStream);
226 #endif // MEDIA_AUDIO_WIN_AUDIO_LOW_LATENCY_INPUT_WIN_H_