OLD | NEW |
(Empty) | |
| 1 // Copyright (c) 2011 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 // Implementation of AudioOutputStream for Windows using Windows Core Audio |
| 6 // WASAPI for low latency rendering. |
| 7 // |
| 8 // Overview of operation and performance: |
| 9 // |
| 10 // - An object of WASAPIAudioOutputStream is created by the AudioManager |
| 11 // factory. |
| 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 IAudioRenderClient. |
| 15 // - Then some thread will call Start(source). |
| 16 // A thread called "wasapi_render_thread" is started and this thread listens |
| 17 // on an event signal which is set periodically by the audio engine to signal |
| 18 // render events. As a result, OnMoreData() will be called and the registered |
| 19 // client is then expected to provide data samples to be played out. |
| 20 // - At some point, a thread will call Stop(), which stops and joins the |
| 21 // render 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. |
| 24 // - Initial tests on Windows 7 shows that this implementation results in a |
| 25 // latency of approximately 35 ms if the selected packet size is less than |
| 26 // or equal to 20 ms. Using a packet size of 10 ms does not result in a |
| 27 // lower latency but only affects the size of the data buffer in each |
| 28 // OnMoreData() callback. |
| 29 // - A total typical delay of 35 ms contains three parts: |
| 30 // o Audio endpoint device period (~10 ms). |
| 31 // o Stream latency between the buffer and endpoint device (~5 ms). |
| 32 // o Endpoint buffer (~20 ms to ensure glitch-free rendering). |
| 33 // - Note that, if the user selects a packet size of e.g. 100 ms, the total |
| 34 // delay will be approximately 115 ms (10 + 5 + 100). |
| 35 // |
| 36 // Implementation notes: |
| 37 // |
| 38 // - The minimum supported client is Windows Vista. |
| 39 // - This implementation is single-threaded, hence: |
| 40 // o Construction and destruction must take place from the same thread. |
| 41 // o It is recommended to call all APIs from the same thread as well. |
| 42 // - It is recommended to first acquire the native sample rate of the default |
| 43 // input device and then use the same rate when creating this object. Use |
| 44 // WASAPIAudioOutputStream::HardwareSampleRate() to retrieve the sample rate. |
| 45 // - Calling Close() also leads to self destruction. |
| 46 // |
| 47 // Core Audio API details: |
| 48 // |
| 49 // - CoInitializeEx() is called on the creating thread and on the internal |
| 50 // capture thread. Each thread's concurrency model and apartment is set |
| 51 // to multi-threaded (MTA). CHECK() is called to ensure that we crash if |
| 52 // CoInitializeEx(MTA) fails. |
| 53 // - Utilized MMDevice interfaces: |
| 54 // o IMMDeviceEnumerator |
| 55 // o IMMDevice |
| 56 // - Utilized WASAPI interfaces: |
| 57 // o IAudioClient |
| 58 // o IAudioRenderClient |
| 59 // - The stream is initialized in shared mode and the processing of the |
| 60 // audio buffer is event driven. |
| 61 // - The Multimedia Class Scheduler service (MMCSS) is utilized to boost |
| 62 // the priority of the render thread. |
| 63 // - Audio-rendering endpoint devices can have three roles: |
| 64 // Console (eConsole), Communications (eCommunications), and Multimedia |
| 65 // (eMultimedia). Search for "Device Roles" on MSDN for more details. |
| 66 // |
| 67 #ifndef MEDIA_AUDIO_WIN_AUDIO_LOW_LATENCY_OUTPUT_WIN_H_ |
| 68 #define MEDIA_AUDIO_WIN_AUDIO_LOW_LATENCY_OUTPUT_WIN_H_ |
| 69 |
| 70 #include <Audioclient.h> |
| 71 #include <MMDeviceAPI.h> |
| 72 |
| 73 #include "base/compiler_specific.h" |
| 74 #include "base/threading/platform_thread.h" |
| 75 #include "base/threading/simple_thread.h" |
| 76 #include "base/win/scoped_co_mem.h" |
| 77 #include "base/win/scoped_com_initializer.h" |
| 78 #include "base/win/scoped_comptr.h" |
| 79 #include "base/win/scoped_handle.h" |
| 80 #include "media/audio/audio_io.h" |
| 81 #include "media/audio/audio_parameters.h" |
| 82 #include "media/base/media_export.h" |
| 83 |
| 84 class AudioManagerWin; |
| 85 |
| 86 // AudioOutputStream implementation using Windows Core Audio APIs. |
| 87 class MEDIA_EXPORT WASAPIAudioOutputStream |
| 88 : public AudioOutputStream, |
| 89 public base::DelegateSimpleThread::Delegate { |
| 90 public: |
| 91 // The ctor takes all the usual parameters, plus |manager| which is the |
| 92 // the audio manager who is creating this object. |
| 93 WASAPIAudioOutputStream(AudioManagerWin* manager, |
| 94 const AudioParameters& params, |
| 95 ERole device_role); |
| 96 // The dtor is typically called by the AudioManager only and it is usually |
| 97 // triggered by calling AudioOutputStream::Close(). |
| 98 virtual ~WASAPIAudioOutputStream(); |
| 99 |
| 100 // Implementation of AudioOutputStream. |
| 101 virtual bool Open() OVERRIDE; |
| 102 virtual void Start(AudioSourceCallback* callback) OVERRIDE; |
| 103 virtual void Stop() OVERRIDE; |
| 104 virtual void Close() OVERRIDE; |
| 105 virtual void SetVolume(double volume) OVERRIDE; |
| 106 virtual void GetVolume(double* volume) OVERRIDE; |
| 107 |
| 108 // Retrieves the stream format that the audio engine uses for its internal |
| 109 // processing/mixing of shared-mode streams. |
| 110 static double HardwareSampleRate(ERole device_role); |
| 111 |
| 112 bool started() const { return started_; } |
| 113 |
| 114 private: |
| 115 // DelegateSimpleThread::Delegate implementation. |
| 116 virtual void Run() OVERRIDE; |
| 117 |
| 118 // Issues the OnError() callback to the |sink_|. |
| 119 void HandleError(HRESULT err); |
| 120 |
| 121 // The Open() method is divided into these sub methods. |
| 122 HRESULT SetRenderDevice(ERole device_role); |
| 123 HRESULT ActivateRenderDevice(); |
| 124 HRESULT GetAudioEngineStreamFormat(); |
| 125 bool DesiredFormatIsSupported(); |
| 126 HRESULT InitializeAudioEngine(); |
| 127 |
| 128 // Initializes the COM library for use by the calling thread and sets the |
| 129 // thread's concurrency model to multi-threaded. |
| 130 base::win::ScopedCOMInitializer com_init_; |
| 131 |
| 132 // Our creator, the audio manager needs to be notified when we close. |
| 133 AudioManagerWin* manager_; |
| 134 |
| 135 // Rendering is driven by this thread (which has no message loop). |
| 136 // All OnMoreData() callbacks will be called from this thread. |
| 137 base::DelegateSimpleThread* render_thread_; |
| 138 |
| 139 // Contains the desired audio format which is set up at construction. |
| 140 WAVEFORMATEX format_; |
| 141 |
| 142 // Copy of the audio format which we know the audio engine supports. |
| 143 // It is recommended to ensure that the sample rate in |format_| is identical |
| 144 // to the sample rate in |audio_engine_mix_format_|. |
| 145 base::win::ScopedCoMem<WAVEFORMATEX> audio_engine_mix_format_; |
| 146 |
| 147 bool opened_; |
| 148 bool started_; |
| 149 |
| 150 // Volume level from 0 to 1. |
| 151 float volume_; |
| 152 |
| 153 // Size in bytes of each audio frame (4 bytes for 16-bit stereo PCM). |
| 154 size_t frame_size_; |
| 155 |
| 156 // Size in audio frames of each audio packet where an audio packet |
| 157 // is defined as the block of data which the source is expected to deliver |
| 158 // in each OnMoreData() callback. |
| 159 size_t packet_size_frames_; |
| 160 |
| 161 // Size in bytes of each audio packet. |
| 162 size_t packet_size_bytes_; |
| 163 |
| 164 // Size in milliseconds of each audio packet. |
| 165 float packet_size_ms_; |
| 166 |
| 167 // Length of the audio endpoint buffer. |
| 168 size_t endpoint_buffer_size_frames_; |
| 169 |
| 170 // Defines the role that the system has assigned to an audio endpoint device. |
| 171 ERole device_role_; |
| 172 |
| 173 // Counts the number of audio frames written to the endpoint buffer. |
| 174 UINT64 num_written_frames_; |
| 175 |
| 176 // Pointer to the client that will deliver audio samples to be played out. |
| 177 AudioSourceCallback* source_; |
| 178 |
| 179 // An IMMDevice interface which represents an audio endpoint device. |
| 180 base::win::ScopedComPtr<IMMDevice> endpoint_device_; |
| 181 |
| 182 // An IAudioClient interface which enables a client to create and initialize |
| 183 // an audio stream between an audio application and the audio engine. |
| 184 base::win::ScopedComPtr<IAudioClient> audio_client_; |
| 185 |
| 186 // The IAudioRenderClient interface enables a client to write output |
| 187 // data to a rendering endpoint buffer. |
| 188 base::win::ScopedComPtr<IAudioRenderClient> audio_render_client_; |
| 189 |
| 190 // The audio engine will signal this event each time a buffer becomes |
| 191 // ready to be filled by the client. |
| 192 base::win::ScopedHandle audio_samples_render_event_; |
| 193 |
| 194 // This event will be signaled when rendering shall stop. |
| 195 base::win::ScopedHandle stop_render_event_; |
| 196 |
| 197 DISALLOW_COPY_AND_ASSIGN(WASAPIAudioOutputStream); |
| 198 }; |
| 199 |
| 200 #endif // MEDIA_AUDIO_WIN_AUDIO_LOW_LATENCY_OUTPUT_WIN_H_ |
OLD | NEW |