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>
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
23 * SECTION:element-wasapisrc
26 * Provides audio capture from the Windows Audio Session API available with
29 * ## Example pipelines
31 * gst-launch-1.0 -v wasapisrc ! fakesink
32 * ]| Capture from the default audio device and render to fakesink.
39 #include "gstwasapisrc.h"
43 GST_DEBUG_CATEGORY_STATIC (gst_wasapi_src_debug);
44 #define GST_CAT_DEFAULT gst_wasapi_src_debug
46 static GstStaticPadTemplate src_template = GST_STATIC_PAD_TEMPLATE ("src",
49 GST_STATIC_CAPS (GST_WASAPI_STATIC_CAPS));
51 #define DEFAULT_ROLE GST_WASAPI_DEVICE_ROLE_CONSOLE
52 #define DEFAULT_EXCLUSIVE FALSE
53 #define DEFAULT_LOW_LATENCY FALSE
64 static void gst_wasapi_src_dispose (GObject * object);
65 static void gst_wasapi_src_finalize (GObject * object);
66 static void gst_wasapi_src_set_property (GObject * object, guint prop_id,
67 const GValue * value, GParamSpec * pspec);
68 static void gst_wasapi_src_get_property (GObject * object, guint prop_id,
69 GValue * value, GParamSpec * pspec);
71 static GstCaps *gst_wasapi_src_get_caps (GstBaseSrc * bsrc, GstCaps * filter);
73 static gboolean gst_wasapi_src_open (GstAudioSrc * asrc);
74 static gboolean gst_wasapi_src_close (GstAudioSrc * asrc);
75 static gboolean gst_wasapi_src_prepare (GstAudioSrc * asrc,
76 GstAudioRingBufferSpec * spec);
77 static gboolean gst_wasapi_src_unprepare (GstAudioSrc * asrc);
78 static guint gst_wasapi_src_read (GstAudioSrc * asrc, gpointer data,
79 guint length, GstClockTime * timestamp);
80 static guint gst_wasapi_src_delay (GstAudioSrc * asrc);
81 static void gst_wasapi_src_reset (GstAudioSrc * asrc);
83 static GstClockTime gst_wasapi_src_get_time (GstClock * clock,
86 #define gst_wasapi_src_parent_class parent_class
87 G_DEFINE_TYPE (GstWasapiSrc, gst_wasapi_src, GST_TYPE_AUDIO_SRC);
90 gst_wasapi_src_class_init (GstWasapiSrcClass * klass)
92 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
93 GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
94 GstBaseSrcClass *gstbasesrc_class = GST_BASE_SRC_CLASS (klass);
95 GstAudioSrcClass *gstaudiosrc_class = GST_AUDIO_SRC_CLASS (klass);
97 gobject_class->dispose = gst_wasapi_src_dispose;
98 gobject_class->finalize = gst_wasapi_src_finalize;
99 gobject_class->set_property = gst_wasapi_src_set_property;
100 gobject_class->get_property = gst_wasapi_src_get_property;
102 g_object_class_install_property (gobject_class,
104 g_param_spec_enum ("role", "Role",
105 "Role of the device: communications, multimedia, etc",
106 GST_WASAPI_DEVICE_TYPE_ROLE, DEFAULT_ROLE, G_PARAM_READWRITE |
107 G_PARAM_STATIC_STRINGS | GST_PARAM_MUTABLE_READY));
109 g_object_class_install_property (gobject_class,
111 g_param_spec_string ("device", "Device",
112 "WASAPI playback device as a GUID string",
113 NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
115 g_object_class_install_property (gobject_class,
117 g_param_spec_boolean ("exclusive", "Exclusive mode",
118 "Open the device in exclusive mode",
119 DEFAULT_EXCLUSIVE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
121 g_object_class_install_property (gobject_class,
123 g_param_spec_boolean ("low-latency", "Low latency",
124 "Optimize all settings for lowest latency",
125 DEFAULT_LOW_LATENCY, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
127 gst_element_class_add_static_pad_template (gstelement_class, &src_template);
128 gst_element_class_set_static_metadata (gstelement_class, "WasapiSrc",
130 "Stream audio from an audio capture device through WASAPI",
131 "Ole André Vadla Ravnås <ole.andre.ravnas@tandberg.com>");
133 gstbasesrc_class->get_caps = GST_DEBUG_FUNCPTR (gst_wasapi_src_get_caps);
135 gstaudiosrc_class->open = GST_DEBUG_FUNCPTR (gst_wasapi_src_open);
136 gstaudiosrc_class->close = GST_DEBUG_FUNCPTR (gst_wasapi_src_close);
137 gstaudiosrc_class->read = GST_DEBUG_FUNCPTR (gst_wasapi_src_read);
138 gstaudiosrc_class->prepare = GST_DEBUG_FUNCPTR (gst_wasapi_src_prepare);
139 gstaudiosrc_class->unprepare = GST_DEBUG_FUNCPTR (gst_wasapi_src_unprepare);
140 gstaudiosrc_class->delay = GST_DEBUG_FUNCPTR (gst_wasapi_src_delay);
141 gstaudiosrc_class->reset = GST_DEBUG_FUNCPTR (gst_wasapi_src_reset);
143 GST_DEBUG_CATEGORY_INIT (gst_wasapi_src_debug, "wasapisrc",
144 0, "Windows audio session API source");
148 gst_wasapi_src_init (GstWasapiSrc * self)
150 /* override with a custom clock */
151 if (GST_AUDIO_BASE_SRC (self)->clock)
152 gst_object_unref (GST_AUDIO_BASE_SRC (self)->clock);
154 GST_AUDIO_BASE_SRC (self)->clock = gst_audio_clock_new ("GstWasapiSrcClock",
155 gst_wasapi_src_get_time, gst_object_ref (self),
156 (GDestroyNotify) gst_object_unref);
158 self->event_handle = CreateEvent (NULL, FALSE, FALSE, NULL);
164 gst_wasapi_src_dispose (GObject * object)
166 GstWasapiSrc *self = GST_WASAPI_SRC (object);
168 if (self->event_handle != NULL) {
169 CloseHandle (self->event_handle);
170 self->event_handle = NULL;
173 if (self->client_clock != NULL) {
174 IUnknown_Release (self->client_clock);
175 self->client_clock = NULL;
178 if (self->client != NULL) {
179 IUnknown_Release (self->client);
183 if (self->capture_client != NULL) {
184 IUnknown_Release (self->capture_client);
185 self->capture_client = NULL;
188 G_OBJECT_CLASS (parent_class)->dispose (object);
192 gst_wasapi_src_finalize (GObject * object)
194 GstWasapiSrc *self = GST_WASAPI_SRC (object);
196 g_clear_pointer (&self->mix_format, CoTaskMemFree);
200 g_clear_pointer (&self->cached_caps, gst_caps_unref);
201 g_clear_pointer (&self->positions, g_free);
202 g_clear_pointer (&self->device_strid, g_free);
204 G_OBJECT_CLASS (parent_class)->finalize (object);
208 gst_wasapi_src_set_property (GObject * object, guint prop_id,
209 const GValue * value, GParamSpec * pspec)
211 GstWasapiSrc *self = GST_WASAPI_SRC (object);
215 self->role = gst_wasapi_device_role_to_erole (g_value_get_enum (value));
219 const gchar *device = g_value_get_string (value);
220 g_free (self->device_strid);
222 device ? g_utf8_to_utf16 (device, -1, NULL, NULL, NULL) : NULL;
226 self->sharemode = g_value_get_boolean (value)
227 ? AUDCLNT_SHAREMODE_EXCLUSIVE : AUDCLNT_SHAREMODE_SHARED;
229 case PROP_LOW_LATENCY:
230 self->low_latency = g_value_get_boolean (value);
233 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
239 gst_wasapi_src_get_property (GObject * object, guint prop_id,
240 GValue * value, GParamSpec * pspec)
242 GstWasapiSrc *self = GST_WASAPI_SRC (object);
246 g_value_set_enum (value, gst_wasapi_erole_to_device_role (self->role));
249 g_value_take_string (value, self->device_strid ?
250 g_utf16_to_utf8 (self->device_strid, -1, NULL, NULL, NULL) : NULL);
253 g_value_set_boolean (value,
254 self->sharemode == AUDCLNT_SHAREMODE_EXCLUSIVE);
256 case PROP_LOW_LATENCY:
257 g_value_set_boolean (value, self->low_latency);
260 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
266 gst_wasapi_src_get_caps (GstBaseSrc * bsrc, GstCaps * filter)
268 GstWasapiSrc *self = GST_WASAPI_SRC (bsrc);
269 WAVEFORMATEX *format = NULL;
270 GstCaps *caps = NULL;
272 GST_DEBUG_OBJECT (self, "entering get caps");
274 if (self->cached_caps) {
275 caps = gst_caps_ref (self->cached_caps);
277 GstCaps *template_caps;
280 template_caps = gst_pad_get_pad_template_caps (bsrc->srcpad);
283 gst_wasapi_src_open (GST_AUDIO_SRC (bsrc));
285 ret = gst_wasapi_util_get_device_format (GST_ELEMENT (self),
286 self->sharemode, self->device, self->client, &format);
288 GST_ELEMENT_ERROR (self, STREAM, FORMAT, (NULL),
289 ("failed to detect format"));
293 gst_wasapi_util_parse_waveformatex ((WAVEFORMATEXTENSIBLE *) format,
294 template_caps, &caps, &self->positions);
296 GST_ELEMENT_ERROR (self, STREAM, FORMAT, (NULL), ("unknown format"));
301 gchar *pos_str = gst_audio_channel_positions_to_string (self->positions,
303 GST_INFO_OBJECT (self, "positions are: %s", pos_str);
307 self->mix_format = format;
308 gst_caps_replace (&self->cached_caps, caps);
309 gst_caps_unref (template_caps);
314 gst_caps_intersect_full (filter, caps, GST_CAPS_INTERSECT_FIRST);
315 gst_caps_unref (caps);
319 GST_DEBUG_OBJECT (self, "returning caps %" GST_PTR_FORMAT, caps);
326 gst_wasapi_src_open (GstAudioSrc * asrc)
328 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
329 gboolean res = FALSE;
330 IAudioClient *client = NULL;
331 IMMDevice *device = NULL;
336 /* FIXME: Switching the default device does not switch the stream to it,
337 * even if the old device was unplugged. We need to handle this somehow.
338 * For example, perhaps we should automatically switch to the new device if
339 * the default device is changed and a device isn't explicitly selected. */
340 if (!gst_wasapi_util_get_device_client (GST_ELEMENT (self), TRUE,
341 self->role, self->device_strid, &device, &client)) {
342 if (!self->device_strid)
343 GST_ELEMENT_ERROR (self, RESOURCE, OPEN_READ, (NULL),
344 ("Failed to get default device"));
346 GST_ELEMENT_ERROR (self, RESOURCE, OPEN_READ, (NULL),
347 ("Failed to open device %S", self->device_strid));
351 self->client = client;
352 self->device = device;
361 gst_wasapi_src_close (GstAudioSrc * asrc)
363 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
365 if (self->device != NULL) {
366 IUnknown_Release (self->device);
370 if (self->client != NULL) {
371 IUnknown_Release (self->client);
379 gst_wasapi_src_prepare (GstAudioSrc * asrc, GstAudioRingBufferSpec * spec)
381 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
382 gboolean res = FALSE;
383 REFERENCE_TIME latency_rt, default_period, min_period;
384 REFERENCE_TIME device_period, device_buffer_duration;
385 guint bpf, rate, buffer_frames;
388 hr = IAudioClient_GetDevicePeriod (self->client, &default_period,
391 GST_ERROR_OBJECT (self, "IAudioClient::GetDevicePeriod failed");
394 GST_INFO_OBJECT (self, "wasapi default period: %" G_GINT64_FORMAT
395 ", min period: %" G_GINT64_FORMAT, default_period, min_period);
397 bpf = GST_AUDIO_INFO_BPF (&spec->info);
398 rate = GST_AUDIO_INFO_RATE (&spec->info);
400 if (self->low_latency) {
401 if (self->sharemode == AUDCLNT_SHAREMODE_SHARED) {
402 device_period = default_period;
403 device_buffer_duration = 0;
405 device_period = min_period;
406 device_buffer_duration = min_period;
409 /* Clamp values to integral multiples of an appropriate period */
410 gst_wasapi_util_get_best_buffer_sizes (spec,
411 self->sharemode == AUDCLNT_SHAREMODE_EXCLUSIVE, default_period,
412 min_period, &device_period, &device_buffer_duration);
415 /* For some reason, we need to call this a second time for exclusive mode */
416 if (self->sharemode == AUDCLNT_SHAREMODE_EXCLUSIVE)
419 hr = IAudioClient_Initialize (self->client, self->sharemode,
420 AUDCLNT_STREAMFLAGS_EVENTCALLBACK, device_buffer_duration,
421 /* This must always be 0 in shared mode */
422 self->sharemode == AUDCLNT_SHAREMODE_SHARED ? 0 : device_period,
423 self->mix_format, NULL);
425 if (hr == AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED &&
426 self->sharemode == AUDCLNT_SHAREMODE_EXCLUSIVE) {
429 GST_WARNING_OBJECT (self, "initialize failed due to unaligned period %i",
430 (int) device_period);
432 /* Calculate a new aligned period. First get the aligned buffer size. */
433 hr = IAudioClient_GetBufferSize (self->client, &n_frames);
435 gchar *msg = gst_wasapi_util_hresult_to_string (hr);
436 GST_ELEMENT_ERROR (self, RESOURCE, OPEN_WRITE, (NULL),
437 ("IAudioClient::GetBufferSize() failed: %s", msg));
442 device_period = (GST_SECOND / 100) * n_frames / rate;
444 GST_WARNING_OBJECT (self, "trying to re-initialize with period %i "
445 "(%i frames, %i rate)", (int) device_period, n_frames, rate);
447 hr = IAudioClient_Initialize (self->client, self->sharemode,
448 AUDCLNT_STREAMFLAGS_EVENTCALLBACK, device_period,
449 device_period, self->mix_format, NULL);
452 gchar *msg = gst_wasapi_util_hresult_to_string (hr);
453 GST_ELEMENT_ERROR (self, RESOURCE, OPEN_READ, (NULL),
454 ("IAudioClient::Initialize () failed: %s", msg));
459 /* Total size in frames of the allocated buffer that we will read from */
460 hr = IAudioClient_GetBufferSize (self->client, &buffer_frames);
462 GST_ERROR_OBJECT (self, "IAudioClient::GetBufferSize failed");
466 GST_INFO_OBJECT (self, "buffer size is %i frames, bpf is %i bytes, "
467 "rate is %i Hz", buffer_frames, bpf, rate);
469 spec->segsize = gst_util_uint64_scale_int_round (rate * bpf,
470 device_period * 100, GST_SECOND);
472 /* We need a minimum of 2 segments to ensure glitch-free playback */
473 spec->segtotal = MAX (self->buffer_frame_count * bpf / spec->segsize, 2);
475 GST_INFO_OBJECT (self, "segsize is %i, segtotal is %i", spec->segsize,
478 /* Get WASAPI latency for logging */
479 hr = IAudioClient_GetStreamLatency (self->client, &latency_rt);
481 GST_ERROR_OBJECT (self, "IAudioClient::GetStreamLatency failed");
484 GST_INFO_OBJECT (self, "wasapi stream latency: %" G_GINT64_FORMAT " (%"
485 G_GINT64_FORMAT " ms)", latency_rt, latency_rt / 10000);
487 /* Set the event handler which will trigger reads */
488 hr = IAudioClient_SetEventHandle (self->client, self->event_handle);
490 GST_ERROR_OBJECT (self, "IAudioClient::SetEventHandle failed");
494 /* Get the clock and the clock freq */
495 if (!gst_wasapi_util_get_clock (GST_ELEMENT (self), self->client,
496 &self->client_clock)) {
500 hr = IAudioClock_GetFrequency (self->client_clock, &self->client_clock_freq);
502 GST_ERROR_OBJECT (self, "IAudioClock::GetFrequency failed");
506 /* Get capture source client and start it up */
507 if (!gst_wasapi_util_get_capture_client (GST_ELEMENT (self), self->client,
508 &self->capture_client)) {
512 hr = IAudioClient_Start (self->client);
514 GST_ERROR_OBJECT (self, "IAudioClient::Start failed");
518 gst_audio_ring_buffer_set_channel_positions (GST_AUDIO_BASE_SRC
519 (self)->ringbuffer, self->positions);
521 #if defined(_MSC_VER) || defined(GST_FORCE_WIN_AVRT)
522 /* Increase the thread priority to reduce glitches */
525 self->thread_priority_handle =
526 AvSetMmThreadCharacteristics (TEXT ("Pro Audio"), &taskIndex);
532 /* unprepare() is not called if prepare() fails, but we want it to be, so call
533 * it manually when needed */
535 gst_wasapi_src_unprepare (asrc);
541 gst_wasapi_src_unprepare (GstAudioSrc * asrc)
543 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
545 if (self->sharemode == AUDCLNT_SHAREMODE_EXCLUSIVE)
548 #if defined(_MSC_VER) || defined(GST_FORCE_WIN_AVRT)
549 if (self->thread_priority_handle != NULL) {
550 AvRevertMmThreadCharacteristics (self->thread_priority_handle);
551 self->thread_priority_handle = NULL;
555 if (self->client != NULL) {
556 IAudioClient_Stop (self->client);
559 if (self->capture_client != NULL) {
560 IUnknown_Release (self->capture_client);
561 self->capture_client = NULL;
564 if (self->client_clock != NULL) {
565 IUnknown_Release (self->client_clock);
566 self->client_clock = NULL;
569 self->client_clock_freq = 0;
575 gst_wasapi_src_read (GstAudioSrc * asrc, gpointer data, guint length,
576 GstClockTime * timestamp)
578 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
581 guint wanted = length;
585 guint have_frames, n_frames, want_frames, read_len;
587 /* Wait for data to become available */
588 WaitForSingleObject (self->event_handle, INFINITE);
590 hr = IAudioCaptureClient_GetBuffer (self->capture_client,
591 (BYTE **) & from, &have_frames, &flags, NULL, NULL);
593 gchar *msg = gst_wasapi_util_hresult_to_string (hr);
594 if (hr == AUDCLNT_S_BUFFER_EMPTY)
595 GST_WARNING_OBJECT (self, "IAudioCaptureClient::GetBuffer failed: %s"
598 GST_ERROR_OBJECT (self, "IAudioCaptureClient::GetBuffer failed: %s",
606 GST_INFO_OBJECT (self, "buffer flags=%#08x", (guint) flags);
608 /* XXX: How do we handle AUDCLNT_BUFFERFLAGS_SILENT? We're supposed to write
609 * out silence when that flag is set? See:
610 * https://msdn.microsoft.com/en-us/library/windows/desktop/dd370800(v=vs.85).aspx */
612 if (flags & AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY)
613 GST_WARNING_OBJECT (self, "WASAPI reported glitch in buffer");
615 want_frames = wanted / self->mix_format->nBlockAlign;
617 /* If GetBuffer is returning more frames than we can handle, all we can do is
618 * hope that this is temporary and that things will settle down later. */
619 if (G_UNLIKELY (have_frames > want_frames))
620 GST_WARNING_OBJECT (self, "captured too many frames: have %i, want %i",
621 have_frames, want_frames);
623 /* Only copy data that will fit into the allocated buffer of size @length */
624 n_frames = MIN (have_frames, want_frames);
625 read_len = n_frames * self->mix_format->nBlockAlign;
628 guint bpf = self->mix_format->nBlockAlign;
629 GST_DEBUG_OBJECT (self, "have: %i (%i bytes), can read: %i (%i bytes), "
630 "will read: %i (%i bytes)", have_frames, have_frames * bpf,
631 want_frames, wanted, n_frames, read_len);
634 memcpy (data, from, read_len);
637 /* Always release all captured buffers if we've captured any at all */
638 hr = IAudioCaptureClient_ReleaseBuffer (self->capture_client, have_frames);
640 gchar *msg = gst_wasapi_util_hresult_to_string (hr);
641 GST_ERROR_OBJECT (self,
642 "IAudioCaptureClient::ReleaseBuffer () failed: %s", msg);
655 gst_wasapi_src_delay (GstAudioSrc * asrc)
657 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
661 hr = IAudioClient_GetCurrentPadding (self->client, &delay);
663 gchar *msg = gst_wasapi_util_hresult_to_string (hr);
664 GST_ELEMENT_ERROR (self, RESOURCE, READ, (NULL),
665 ("IAudioClient::GetCurrentPadding failed %s", msg));
673 gst_wasapi_src_reset (GstAudioSrc * asrc)
675 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
679 hr = IAudioClient_Stop (self->client);
681 gchar *msg = gst_wasapi_util_hresult_to_string (hr);
682 GST_ERROR_OBJECT (self, "IAudioClient::Stop () failed: %s", msg);
687 hr = IAudioClient_Reset (self->client);
689 gchar *msg = gst_wasapi_util_hresult_to_string (hr);
690 GST_ERROR_OBJECT (self, "IAudioClient::Reset () failed: %s", msg);
698 gst_wasapi_src_get_time (GstClock * clock, gpointer user_data)
700 GstWasapiSrc *self = GST_WASAPI_SRC (user_data);
705 if (G_UNLIKELY (self->client_clock == NULL))
706 return GST_CLOCK_TIME_NONE;
708 hr = IAudioClock_GetPosition (self->client_clock, &devpos, NULL);
709 if (G_UNLIKELY (hr != S_OK))
710 return GST_CLOCK_TIME_NONE;
712 result = gst_util_uint64_scale_int (devpos, GST_SECOND,
713 self->client_clock_freq);
716 GST_DEBUG_OBJECT (self, "devpos = %" G_GUINT64_FORMAT
717 " frequency = %" G_GUINT64_FORMAT
718 " result = %" G_GUINT64_FORMAT " ms",
719 devpos, self->client_clock_freq, GST_TIME_AS_MSECONDS (result));