src/media/audio/win/core_audio_util_win.h

   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 // Utility methods for the Core Audio API on Windows.
   6 // Always ensure that Core Audio is supported before using these methods.
   7 // Use media::CoreAudioIsSupported() for this purpose.
   8 // Also, all methods must be called on a valid COM thread. This can be done
   9 // by using the base::win::ScopedCOMInitializer helper class.
  10
  11 #ifndef MEDIA_AUDIO_WIN_CORE_AUDIO_UTIL_WIN_H_
  12 #define MEDIA_AUDIO_WIN_CORE_AUDIO_UTIL_WIN_H_
  13
  14 #include <audioclient.h>
  15 #include <mmdeviceapi.h>
  16 #include <string>
  17
  18 #include "base/basictypes.h"
  19 #include "base/time/time.h"
  20 #include "base/win/scoped_comptr.h"
  21 #include "media/audio/audio_device_name.h"
  22 #include "media/audio/audio_parameters.h"
  23 #include "media/base/media_export.h"
  24
  25 using base::win::ScopedComPtr;
  26
  27 namespace media {
  28
  29
  30 // Represents audio channel configuration constants as understood by Windows.
  31 // E.g. KSAUDIO_SPEAKER_MONO.  For a list of possible values see:
  32 // http://msdn.microsoft.com/en-us/library/windows/hardware/ff537083(v=vs.85).aspx
  33 typedef uint32 ChannelConfig;
  34
  35 class MEDIA_EXPORT CoreAudioUtil {
  36  public:
  37   // Returns true if Windows Core Audio is supported.
  38   // Always verify that this method returns true before using any of the
  39   // methods in this class.
  40   // WARNING: This function must be called once from the main thread before
  41   // it is safe to call from other threads.
  42   static bool IsSupported();
  43
  44   // Converts between reference time to base::TimeDelta.
  45   // One reference-time unit is 100 nanoseconds.
  46   // Example: double s = RefererenceTimeToTimeDelta(t).InMillisecondsF();
  47   static base::TimeDelta RefererenceTimeToTimeDelta(REFERENCE_TIME time);
  48
  49   // Returns AUDCLNT_SHAREMODE_EXCLUSIVE if --enable-exclusive-mode is used
  50   // as command-line flag and AUDCLNT_SHAREMODE_SHARED otherwise (default).
  51   static AUDCLNT_SHAREMODE GetShareMode();
  52
  53   // The Windows Multimedia Device (MMDevice) API enables audio clients to
  54   // discover audio endpoint devices and determine their capabilities.
  55
  56   // Number of active audio devices in the specified flow data flow direction.
  57   // Set |data_flow| to eAll to retrieve the total number of active audio
  58   // devices.
  59   static int NumberOfActiveDevices(EDataFlow data_flow);
  60
  61   // Creates an IMMDeviceEnumerator interface which provides methods for
  62   // enumerating audio endpoint devices.
  63   static ScopedComPtr<IMMDeviceEnumerator> CreateDeviceEnumerator();
  64
  65   // Creates a default endpoint device that is specified by a data-flow
  66   // direction and role, e.g. default render device.
  67   static ScopedComPtr<IMMDevice> CreateDefaultDevice(
  68       EDataFlow data_flow, ERole role);
  69
  70   // Returns the device id of the default output device or an empty string
  71   // if no such device exists or if the default device has been disabled.
  72   static std::string GetDefaultOutputDeviceID();
  73
  74   // Creates an endpoint device that is specified by a unique endpoint device-
  75   // identification string.
  76   static ScopedComPtr<IMMDevice> CreateDevice(const std::string& device_id);
  77
  78   // Returns the unique ID and user-friendly name of a given endpoint device.
  79   // Example: "{0.0.1.00000000}.{8db6020f-18e3-4f25-b6f5-7726c9122574}", and
  80   //          "Microphone (Realtek High Definition Audio)".
  81   static HRESULT GetDeviceName(IMMDevice* device, AudioDeviceName* name);
  82
  83   // Returns the device ID/path of the controller (a.k.a. physical device that
  84   // |device| is connected to.  This ID will be the same for all devices from
  85   // the same controller so it is useful for doing things like determining
  86   // whether a set of output and input devices belong to the same controller.
  87   // The device enumerator is required as well as the device itself since
  88   // looking at the device topology is required and we need to open up
  89   // associated devices to determine the controller id.
  90   // If the ID could not be determined for some reason, an empty string is
  91   // returned.
  92   static std::string GetAudioControllerID(IMMDevice* device,
  93       IMMDeviceEnumerator* enumerator);
  94
  95   // Accepts an id of an input device and finds a matching output device id.
  96   // If the associated hardware does not have an audio output device (e.g.
  97   // a webcam with a mic), an empty string is returned.
  98   static std::string GetMatchingOutputDeviceID(
  99       const std::string& input_device_id);
 100
 101   // Gets the user-friendly name of the endpoint device which is represented
 102   // by a unique id in |device_id|.
 103   static std::string GetFriendlyName(const std::string& device_id);
 104
 105   // Returns true if the provided unique |device_id| corresponds to the current
 106   // default device for the specified by a data-flow direction and role.
 107   static bool DeviceIsDefault(
 108       EDataFlow flow, ERole role, const std::string& device_id);
 109
 110   // Query if the audio device is a rendering device or a capture device.
 111   static EDataFlow GetDataFlow(IMMDevice* device);
 112
 113   // The Windows Audio Session API (WASAPI) enables client applications to
 114   // manage the flow of audio data between the application and an audio endpoint
 115   // device.
 116
 117   // Create an IAudioClient instance for the default IMMDevice where
 118   // flow direction and role is define by |data_flow| and |role|.
 119   // The IAudioClient interface enables a client to create and initialize an
 120   // audio stream between an audio application and the audio engine (for a
 121   // shared-mode stream) or the hardware buffer of an audio endpoint device
 122   // (for an exclusive-mode stream).
 123   static ScopedComPtr<IAudioClient> CreateDefaultClient(EDataFlow data_flow,
 124                                                         ERole role);
 125
 126   // Create an IAudioClient instance for a specific device _or_ the default
 127   // device if |device_id| is empty.
 128   static ScopedComPtr<IAudioClient> CreateClient(const std::string& device_id,
 129                                                  EDataFlow data_flow,
 130                                                  ERole role);
 131
 132   // Create an IAudioClient interface for an existing IMMDevice given by
 133   // |audio_device|. Flow direction and role is define by the |audio_device|.
 134   static ScopedComPtr<IAudioClient> CreateClient(IMMDevice* audio_device);
 135
 136   // Get the mix format that the audio engine uses internally for processing
 137   // of shared-mode streams. This format is not necessarily a format that the
 138   // audio endpoint device supports. Thus, the caller might not succeed in
 139   // creating an exclusive-mode stream with a format obtained by this method.
 140   static HRESULT GetSharedModeMixFormat(IAudioClient* client,
 141                                         WAVEFORMATPCMEX* format);
 142
 143   // Returns true if the specified |client| supports the format in |format|
 144   // for the given |share_mode| (shared or exclusive).
 145   static bool IsFormatSupported(IAudioClient* client,
 146                                 AUDCLNT_SHAREMODE share_mode,
 147                                 const WAVEFORMATPCMEX* format);
 148
 149   // Returns true if the specified |channel_layout| is supported for the
 150   // default IMMDevice where flow direction and role is define by |data_flow|
 151   // and |role|. If this method returns true for a certain channel layout, it
 152   // means that SharedModeInitialize() will succeed using a format based on
 153   // the preferred format where the channel layout has been modified.
 154   static bool IsChannelLayoutSupported(const std::string& device_id,
 155                                        EDataFlow data_flow,
 156                                        ERole role,
 157                                        ChannelLayout channel_layout);
 158
 159   // For a shared-mode stream, the audio engine periodically processes the
 160   // data in the endpoint buffer at the period obtained in |device_period|.
 161   // For an exclusive mode stream, |device_period| corresponds to the minimum
 162   // time interval between successive processing by the endpoint device.
 163   // This period plus the stream latency between the buffer and endpoint device
 164   // represents the minimum possible latency that an audio application can
 165   // achieve. The time in |device_period| is expressed in 100-nanosecond units.
 166   static HRESULT GetDevicePeriod(IAudioClient* client,
 167                                  AUDCLNT_SHAREMODE share_mode,
 168                                  REFERENCE_TIME* device_period);
 169
 170   // Get the preferred audio parameters for the specified |client| or the
 171   // given direction and role is define by |data_flow| and |role|, or the
 172   // unique device id given by |device_id|.
 173   // The acquired values should only be utilized for shared mode streamed since
 174   // there are no preferred settings for an exclusive mode stream.
 175   static HRESULT GetPreferredAudioParameters(IAudioClient* client,
 176                                              AudioParameters* params);
 177   static HRESULT GetPreferredAudioParameters(EDataFlow data_flow, ERole role,
 178                                              AudioParameters* params);
 179   static HRESULT GetPreferredAudioParameters(const std::string& device_id,
 180                                              AudioParameters* params);
 181
 182   // Retrieves an integer mask which corresponds to the channel layout the
 183   // audio engine uses for its internal processing/mixing of shared-mode
 184   // streams. This mask indicates which channels are present in the multi-
 185   // channel stream. The least significant bit corresponds with the Front Left
 186   // speaker, the next least significant bit corresponds to the Front Right
 187   // speaker, and so on, continuing in the order defined in KsMedia.h.
 188   // See http://msdn.microsoft.com/en-us/library/windows/hardware/ff537083(v=vs.85).aspx
 189   // for more details.
 190   // To get the channel config of the default device, pass an empty string
 191   // for |device_id|.
 192   static ChannelConfig GetChannelConfig(const std::string& device_id,
 193                                         EDataFlow data_flow);
 194
 195   // After activating an IAudioClient interface on an audio endpoint device,
 196   // the client must initialize it once, and only once, to initialize the audio
 197   // stream between the client and the device. In shared mode, the client
 198   // connects indirectly through the audio engine which does the mixing.
 199   // In exclusive mode, the client connects directly to the audio hardware.
 200   // If a valid event is provided in |event_handle|, the client will be
 201   // initialized for event-driven buffer handling. If |event_handle| is set to
 202   // NULL, event-driven buffer handling is not utilized.
 203   static HRESULT SharedModeInitialize(IAudioClient* client,
 204                                       const WAVEFORMATPCMEX* format,
 205                                       HANDLE event_handle,
 206                                       uint32* endpoint_buffer_size);
 207   // TODO(henrika): add ExclusiveModeInitialize(...)
 208
 209   // Create an IAudioRenderClient client for an existing IAudioClient given by
 210   // |client|. The IAudioRenderClient interface enables a client to write
 211   // output data to a rendering endpoint buffer.
 212   static ScopedComPtr<IAudioRenderClient> CreateRenderClient(
 213       IAudioClient* client);
 214
 215   // Create an IAudioCaptureClient client for an existing IAudioClient given by
 216   // |client|. The IAudioCaptureClient interface enables a client to read
 217   // input data from a capture endpoint buffer.
 218   static ScopedComPtr<IAudioCaptureClient> CreateCaptureClient(
 219       IAudioClient* client);
 220
 221   // Fills up the endpoint rendering buffer with silence for an existing
 222   // IAudioClient given by |client| and a corresponding IAudioRenderClient
 223   // given by |render_client|.
 224   static bool FillRenderEndpointBufferWithSilence(
 225       IAudioClient* client, IAudioRenderClient* render_client);
 226
 227  private:
 228   CoreAudioUtil() {}
 229   ~CoreAudioUtil() {}
 230   DISALLOW_COPY_AND_ASSIGN(CoreAudioUtil);
 231 };
 232
 233 }  // namespace media
 234
 235 #endif  // MEDIA_AUDIO_WIN_CORE_AUDIO_UTIL_WIN_H_