2 * Copyright (C) 2008 Ole André Vadla Ravnås <ole.andre.ravnas@tandberg.com>
3 * Copyright (C) 2018 Centricular Ltd.
4 * Author: Nirbheek Chauhan <nirbheek@centricular.com>
5 * Copyright (C) 2020 Seungha Yang <seungha@centricular.com>
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
26 #include "gstwasapi2util.h"
27 #include <audioclient.h>
28 #include <mmdeviceapi.h>
31 GST_DEBUG_CATEGORY_EXTERN (gst_wasapi2_debug);
32 #define GST_CAT_DEFAULT gst_wasapi2_debug
34 /* Desktop only defines */
35 #ifndef KSAUDIO_SPEAKER_MONO
36 #define KSAUDIO_SPEAKER_MONO (SPEAKER_FRONT_CENTER)
38 #ifndef KSAUDIO_SPEAKER_1POINT1
39 #define KSAUDIO_SPEAKER_1POINT1 (SPEAKER_FRONT_CENTER | SPEAKER_LOW_FREQUENCY)
41 #ifndef KSAUDIO_SPEAKER_STEREO
42 #define KSAUDIO_SPEAKER_STEREO (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT)
44 #ifndef KSAUDIO_SPEAKER_2POINT1
45 #define KSAUDIO_SPEAKER_2POINT1 (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_LOW_FREQUENCY)
47 #ifndef KSAUDIO_SPEAKER_3POINT0
48 #define KSAUDIO_SPEAKER_3POINT0 (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_FRONT_CENTER)
50 #ifndef KSAUDIO_SPEAKER_3POINT1
51 #define KSAUDIO_SPEAKER_3POINT1 (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | \
52 SPEAKER_FRONT_CENTER | SPEAKER_LOW_FREQUENCY)
54 #ifndef KSAUDIO_SPEAKER_QUAD
55 #define KSAUDIO_SPEAKER_QUAD (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | \
56 SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT)
58 #define KSAUDIO_SPEAKER_SURROUND (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | \
59 SPEAKER_FRONT_CENTER | SPEAKER_BACK_CENTER)
60 #ifndef KSAUDIO_SPEAKER_5POINT0
61 #define KSAUDIO_SPEAKER_5POINT0 (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_FRONT_CENTER | \
62 SPEAKER_SIDE_LEFT | SPEAKER_SIDE_RIGHT)
64 #define KSAUDIO_SPEAKER_5POINT1 (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | \
65 SPEAKER_FRONT_CENTER | SPEAKER_LOW_FREQUENCY | \
66 SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT)
67 #ifndef KSAUDIO_SPEAKER_7POINT0
68 #define KSAUDIO_SPEAKER_7POINT0 (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | SPEAKER_FRONT_CENTER | \
69 SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT | \
70 SPEAKER_SIDE_LEFT | SPEAKER_SIDE_RIGHT)
72 #ifndef KSAUDIO_SPEAKER_7POINT1
73 #define KSAUDIO_SPEAKER_7POINT1 (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | \
74 SPEAKER_FRONT_CENTER | SPEAKER_LOW_FREQUENCY | \
75 SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT | \
76 SPEAKER_FRONT_LEFT_OF_CENTER | SPEAKER_FRONT_RIGHT_OF_CENTER)
83 GstAudioChannelPosition gst_pos;
84 } wasapi_to_gst_pos[] = {
85 {SPEAKER_FRONT_LEFT, GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT},
86 {SPEAKER_FRONT_RIGHT, GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT},
87 {SPEAKER_FRONT_CENTER, GST_AUDIO_CHANNEL_POSITION_FRONT_CENTER},
88 {SPEAKER_LOW_FREQUENCY, GST_AUDIO_CHANNEL_POSITION_LFE1},
89 {SPEAKER_BACK_LEFT, GST_AUDIO_CHANNEL_POSITION_REAR_LEFT},
90 {SPEAKER_BACK_RIGHT, GST_AUDIO_CHANNEL_POSITION_REAR_RIGHT},
91 {SPEAKER_FRONT_LEFT_OF_CENTER,
92 GST_AUDIO_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER},
93 {SPEAKER_FRONT_RIGHT_OF_CENTER,
94 GST_AUDIO_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER},
95 {SPEAKER_BACK_CENTER, GST_AUDIO_CHANNEL_POSITION_REAR_CENTER},
96 /* Enum values diverge from this point onwards */
97 {SPEAKER_SIDE_LEFT, GST_AUDIO_CHANNEL_POSITION_SIDE_LEFT},
98 {SPEAKER_SIDE_RIGHT, GST_AUDIO_CHANNEL_POSITION_SIDE_RIGHT},
99 {SPEAKER_TOP_CENTER, GST_AUDIO_CHANNEL_POSITION_TOP_CENTER},
100 {SPEAKER_TOP_FRONT_LEFT, GST_AUDIO_CHANNEL_POSITION_TOP_FRONT_LEFT},
101 {SPEAKER_TOP_FRONT_CENTER, GST_AUDIO_CHANNEL_POSITION_TOP_FRONT_CENTER},
102 {SPEAKER_TOP_FRONT_RIGHT, GST_AUDIO_CHANNEL_POSITION_TOP_FRONT_RIGHT},
103 {SPEAKER_TOP_BACK_LEFT, GST_AUDIO_CHANNEL_POSITION_TOP_REAR_LEFT},
104 {SPEAKER_TOP_BACK_CENTER, GST_AUDIO_CHANNEL_POSITION_TOP_REAR_CENTER},
105 {SPEAKER_TOP_BACK_RIGHT, GST_AUDIO_CHANNEL_POSITION_TOP_REAR_RIGHT}
108 static DWORD default_ch_masks[] = {
110 KSAUDIO_SPEAKER_MONO,
112 KSAUDIO_SPEAKER_STEREO,
114 /* KSAUDIO_SPEAKER_3POINT0 ? */
115 KSAUDIO_SPEAKER_2POINT1,
117 /* KSAUDIO_SPEAKER_3POINT1 or KSAUDIO_SPEAKER_SURROUND ? */
118 KSAUDIO_SPEAKER_QUAD,
120 KSAUDIO_SPEAKER_5POINT0,
122 KSAUDIO_SPEAKER_5POINT1,
124 KSAUDIO_SPEAKER_7POINT0,
126 KSAUDIO_SPEAKER_7POINT1,
131 hresult_to_string_fallback (HRESULT hr)
133 const gchar *s = "unknown error";
136 case AUDCLNT_E_NOT_INITIALIZED:
137 s = "AUDCLNT_E_NOT_INITIALIZED";
139 case AUDCLNT_E_ALREADY_INITIALIZED:
140 s = "AUDCLNT_E_ALREADY_INITIALIZED";
142 case AUDCLNT_E_WRONG_ENDPOINT_TYPE:
143 s = "AUDCLNT_E_WRONG_ENDPOINT_TYPE";
145 case AUDCLNT_E_DEVICE_INVALIDATED:
146 s = "AUDCLNT_E_DEVICE_INVALIDATED";
148 case AUDCLNT_E_NOT_STOPPED:
149 s = "AUDCLNT_E_NOT_STOPPED";
151 case AUDCLNT_E_BUFFER_TOO_LARGE:
152 s = "AUDCLNT_E_BUFFER_TOO_LARGE";
154 case AUDCLNT_E_OUT_OF_ORDER:
155 s = "AUDCLNT_E_OUT_OF_ORDER";
157 case AUDCLNT_E_UNSUPPORTED_FORMAT:
158 s = "AUDCLNT_E_UNSUPPORTED_FORMAT";
160 case AUDCLNT_E_INVALID_DEVICE_PERIOD:
161 s = "AUDCLNT_E_INVALID_DEVICE_PERIOD";
163 case AUDCLNT_E_INVALID_SIZE:
164 s = "AUDCLNT_E_INVALID_SIZE";
166 case AUDCLNT_E_DEVICE_IN_USE:
167 s = "AUDCLNT_E_DEVICE_IN_USE";
169 case AUDCLNT_E_BUFFER_OPERATION_PENDING:
170 s = "AUDCLNT_E_BUFFER_OPERATION_PENDING";
172 case AUDCLNT_E_BUFFER_SIZE_ERROR:
173 s = "AUDCLNT_E_BUFFER_SIZE_ERROR";
175 case AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED:
176 s = "AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED";
178 case AUDCLNT_E_THREAD_NOT_REGISTERED:
179 s = "AUDCLNT_E_THREAD_NOT_REGISTERED";
181 case AUDCLNT_E_EXCLUSIVE_MODE_NOT_ALLOWED:
182 s = "AUDCLNT_E_EXCLUSIVE_MODE_NOT_ALLOWED";
184 case AUDCLNT_E_ENDPOINT_CREATE_FAILED:
185 s = "AUDCLNT_E_ENDPOINT_CREATE_FAILED";
187 case AUDCLNT_E_SERVICE_NOT_RUNNING:
188 s = "AUDCLNT_E_SERVICE_NOT_RUNNING";
190 case AUDCLNT_E_EVENTHANDLE_NOT_EXPECTED:
191 s = "AUDCLNT_E_EVENTHANDLE_NOT_EXPECTED";
193 case AUDCLNT_E_EXCLUSIVE_MODE_ONLY:
194 s = "AUDCLNT_E_EXCLUSIVE_MODE_ONLY";
196 case AUDCLNT_E_BUFDURATION_PERIOD_NOT_EQUAL:
197 s = "AUDCLNT_E_BUFDURATION_PERIOD_NOT_EQUAL";
199 case AUDCLNT_E_EVENTHANDLE_NOT_SET:
200 s = "AUDCLNT_E_EVENTHANDLE_NOT_SET";
202 case AUDCLNT_E_INCORRECT_BUFFER_SIZE:
203 s = "AUDCLNT_E_INCORRECT_BUFFER_SIZE";
205 case AUDCLNT_E_CPUUSAGE_EXCEEDED:
206 s = "AUDCLNT_E_CPUUSAGE_EXCEEDED";
208 case AUDCLNT_S_BUFFER_EMPTY:
209 s = "AUDCLNT_S_BUFFER_EMPTY";
211 case AUDCLNT_S_THREAD_ALREADY_REGISTERED:
212 s = "AUDCLNT_S_THREAD_ALREADY_REGISTERED";
214 case AUDCLNT_S_POSITION_STALLED:
215 s = "AUDCLNT_S_POSITION_STALLED";
229 gst_wasapi2_util_get_error_message (HRESULT hr)
231 gchar *error_text = NULL;
233 error_text = g_win32_error_message ((gint) hr);
234 if (!error_text || strlen (error_text) == 0) {
236 error_text = g_strdup (hresult_to_string_fallback (hr));
243 _gst_wasapi2_result (HRESULT hr, GstDebugCategory * cat, const gchar * file,
244 const gchar * function, gint line)
246 #ifndef GST_DISABLE_GST_DEBUG
250 gchar *error_text = NULL;
251 gboolean free_string = TRUE;
253 error_text = g_win32_error_message ((gint) hr);
254 /* g_win32_error_message() seems to be returning empty string for
256 if (!error_text || strlen (error_text) == 0) {
258 error_text = (gchar *) hresult_to_string_fallback (hr);
263 gst_debug_log (cat, GST_LEVEL_WARNING, file, function, line,
264 NULL, "WASAPI call failed: 0x%x, %s", (guint) hr, error_text);
274 return SUCCEEDED (hr);
279 gst_wasapi_util_channel_position_all_none (guint channels,
280 GstAudioChannelPosition * position)
284 for (i = 0; i < channels; i++)
285 position[i] = GST_AUDIO_CHANNEL_POSITION_NONE;
289 gst_wasapi2_util_waveformatex_to_channel_mask (WAVEFORMATEX * format,
290 GstAudioChannelPosition ** out_position)
294 GstAudioChannelPosition *pos = NULL;
296 DWORD dwChannelMask = 0;
298 nChannels = format->nChannels;
299 if (format->wFormatTag == WAVE_FORMAT_EXTENSIBLE) {
300 WAVEFORMATEXTENSIBLE *extensible = (WAVEFORMATEXTENSIBLE *) format;
301 dwChannelMask = extensible->dwChannelMask;
305 *out_position = NULL;
307 if (nChannels > 2 && !dwChannelMask) {
308 GST_WARNING ("Unknown channel mask value for %d channel stream", nChannels);
310 if (nChannels >= G_N_ELEMENTS (default_ch_masks)) {
311 GST_ERROR ("To may channels %d", nChannels);
315 dwChannelMask = default_ch_masks[nChannels];
318 pos = g_new (GstAudioChannelPosition, nChannels);
319 gst_wasapi_util_channel_position_all_none (nChannels, pos);
321 /* Too many channels, have to assume that they are all non-positional */
322 if (nChannels > G_N_ELEMENTS (wasapi_to_gst_pos)) {
323 GST_INFO ("Got too many (%i) channels, assuming non-positional", nChannels);
327 /* Too many bits in the channel mask, and the bits don't match nChannels */
328 if (dwChannelMask >> (G_N_ELEMENTS (wasapi_to_gst_pos) + 1) != 0) {
329 GST_WARNING ("Too many bits in channel mask (%lu), assuming "
330 "non-positional", dwChannelMask);
334 /* Map WASAPI's channel mask to Gstreamer's channel mask and positions.
335 * If the no. of bits in the mask > nChannels, we will ignore the extra. */
336 for (i = 0, ch = 0; i < G_N_ELEMENTS (wasapi_to_gst_pos) && ch < nChannels;
338 if (!(dwChannelMask & wasapi_to_gst_pos[i].wasapi_pos))
339 /* no match, try next */
341 mask |= G_GUINT64_CONSTANT (1) << wasapi_to_gst_pos[i].gst_pos;
342 pos[ch++] = wasapi_to_gst_pos[i].gst_pos;
345 /* XXX: Warn if some channel masks couldn't be mapped? */
347 GST_DEBUG ("Converted WASAPI mask 0x%" G_GINT64_MODIFIER "x -> 0x%"
348 G_GINT64_MODIFIER "x", (guint64) dwChannelMask, (guint64) mask);
361 gst_wasapi2_util_waveformatex_to_audio_format (WAVEFORMATEX * format)
363 const gchar *fmt_str = NULL;
364 GstAudioFormat fmt = GST_AUDIO_FORMAT_UNKNOWN;
366 switch (format->wFormatTag) {
367 case WAVE_FORMAT_PCM:
368 fmt = gst_audio_format_build_integer (TRUE, G_LITTLE_ENDIAN,
369 format->wBitsPerSample, format->wBitsPerSample);
371 case WAVE_FORMAT_IEEE_FLOAT:
372 if (format->wBitsPerSample == 32)
373 fmt = GST_AUDIO_FORMAT_F32LE;
374 else if (format->wBitsPerSample == 64)
375 fmt = GST_AUDIO_FORMAT_F64LE;
377 case WAVE_FORMAT_EXTENSIBLE:
379 WAVEFORMATEXTENSIBLE *ex = (WAVEFORMATEXTENSIBLE *) format;
380 if (IsEqualGUID (&ex->SubFormat, &KSDATAFORMAT_SUBTYPE_PCM)) {
381 fmt = gst_audio_format_build_integer (TRUE, G_LITTLE_ENDIAN,
382 format->wBitsPerSample, ex->Samples.wValidBitsPerSample);
383 } else if (IsEqualGUID (&ex->SubFormat, &KSDATAFORMAT_SUBTYPE_IEEE_FLOAT)) {
384 if (format->wBitsPerSample == 32
385 && ex->Samples.wValidBitsPerSample == 32)
386 fmt = GST_AUDIO_FORMAT_F32LE;
387 else if (format->wBitsPerSample == 64 &&
388 ex->Samples.wValidBitsPerSample == 64)
389 fmt = GST_AUDIO_FORMAT_F64LE;
397 if (fmt != GST_AUDIO_FORMAT_UNKNOWN)
398 fmt_str = gst_audio_format_to_string (fmt);
404 gst_wasapi2_util_parse_waveformatex (WAVEFORMATEX * format,
405 GstCaps * template_caps, GstCaps ** out_caps,
406 GstAudioChannelPosition ** out_positions)
409 guint64 channel_mask;
413 /* TODO: handle SPDIF and other encoded formats */
415 /* 1 or 2 channels <= 16 bits sample size OR
416 * 1 or 2 channels > 16 bits sample size or >2 channels */
417 if (format->wFormatTag != WAVE_FORMAT_PCM &&
418 format->wFormatTag != WAVE_FORMAT_IEEE_FLOAT &&
419 format->wFormatTag != WAVE_FORMAT_EXTENSIBLE)
420 /* Unhandled format tag */
423 /* WASAPI can only tell us one canonical mix format that it will accept. The
424 * alternative is calling IsFormatSupported on all combinations of formats.
425 * Instead, it's simpler and faster to require conversion inside gstreamer */
426 afmt = gst_wasapi2_util_waveformatex_to_audio_format (format);
430 *out_caps = gst_caps_copy (template_caps);
432 channel_mask = gst_wasapi2_util_waveformatex_to_channel_mask (format,
435 gst_caps_set_simple (*out_caps,
436 "format", G_TYPE_STRING, afmt,
437 "channels", G_TYPE_INT, format->nChannels,
438 "rate", G_TYPE_INT, format->nSamplesPerSec, NULL);
441 gst_caps_set_simple (*out_caps,
442 "channel-mask", GST_TYPE_BITMASK, channel_mask, NULL);
449 gst_wasapi2_can_automatic_stream_routing (void)
451 #ifdef GST_WASAPI2_WINAPI_ONLY_APP
452 /* Assume we are on very recent OS */
455 static gboolean ret = FALSE;
456 static gsize version_once = 0;
458 if (g_once_init_enter (&version_once)) {
459 OSVERSIONINFOEXW osverinfo;
460 typedef NTSTATUS (WINAPI fRtlGetVersion) (PRTL_OSVERSIONINFOEXW);
461 fRtlGetVersion *RtlGetVersion = NULL;
462 HMODULE hmodule = NULL;
464 memset (&osverinfo, 0, sizeof (OSVERSIONINFOEXW));
465 osverinfo.dwOSVersionInfoSize = sizeof (OSVERSIONINFOEXW);
467 hmodule = LoadLibraryW (L"ntdll.dll");
470 (fRtlGetVersion *) GetProcAddress (hmodule, "RtlGetVersion");
473 RtlGetVersion (&osverinfo);
475 /* automatic stream routing requires Windows 10
476 * Anniversary Update (version 1607, build number 14393.0) */
477 if (osverinfo.dwMajorVersion > 10 ||
478 (osverinfo.dwMajorVersion == 10 && osverinfo.dwBuildNumber >= 14393))
483 FreeLibrary (hmodule);
485 g_once_init_leave (&version_once, 1);
488 GST_INFO ("Automatic stream routing support: %d", ret);
495 gst_wasapi2_can_process_loopback (void)
497 #ifdef GST_WASAPI2_WINAPI_ONLY_APP
498 /* FIXME: Needs WinRT (Windows.System.Profile) API call
499 * for OS version check */
502 static gboolean ret = FALSE;
503 static gsize version_once = 0;
505 if (g_once_init_enter (&version_once)) {
506 OSVERSIONINFOEXW osverinfo;
507 typedef NTSTATUS (WINAPI fRtlGetVersion) (PRTL_OSVERSIONINFOEXW);
508 fRtlGetVersion *RtlGetVersion = NULL;
509 HMODULE hmodule = NULL;
511 memset (&osverinfo, 0, sizeof (OSVERSIONINFOEXW));
512 osverinfo.dwOSVersionInfoSize = sizeof (OSVERSIONINFOEXW);
514 hmodule = LoadLibraryW (L"ntdll.dll");
517 (fRtlGetVersion *) GetProcAddress (hmodule, "RtlGetVersion");
520 RtlGetVersion (&osverinfo);
522 /* Process loopback requires Windows 10 build 20348
523 * https://learn.microsoft.com/en-us/windows/win32/api/audioclientactivationparams/ns-audioclientactivationparams-audioclient_process_loopback_params
525 * Note: "Windows 10 build 20348" would mean "Windows server 2022" or
526 * "Windows 11", since build number of "Windows 10 version 21H2" is
530 /* But other software enables this for build number 19041 or higher... */
531 if (osverinfo.dwMajorVersion > 10 ||
532 (osverinfo.dwMajorVersion == 10 && osverinfo.dwBuildNumber >= 19041))
537 FreeLibrary (hmodule);
539 g_once_init_leave (&version_once, 1);
542 GST_INFO ("Process loopback support: %d", ret);
549 gst_wasapi2_get_default_mix_format (void)
551 WAVEFORMATEX *format;
553 /* virtual loopback device might not provide mix format. Create our default
555 format = CoTaskMemAlloc (sizeof (WAVEFORMATEX));
556 format->wFormatTag = WAVE_FORMAT_PCM;
557 format->nChannels = 2;
558 format->nSamplesPerSec = 44100;
559 format->wBitsPerSample = 16;
560 format->nBlockAlign = format->nChannels * format->wBitsPerSample / 8;
561 format->nAvgBytesPerSec = format->nSamplesPerSec * format->nBlockAlign;