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"
41 #include <mmdeviceapi.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
60 static void gst_wasapi_src_dispose (GObject * object);
61 static void gst_wasapi_src_finalize (GObject * object);
62 static void gst_wasapi_src_set_property (GObject * object, guint prop_id,
63 const GValue * value, GParamSpec * pspec);
64 static void gst_wasapi_src_get_property (GObject * object, guint prop_id,
65 GValue * value, GParamSpec * pspec);
67 static GstCaps *gst_wasapi_src_get_caps (GstBaseSrc * bsrc, GstCaps * filter);
69 static gboolean gst_wasapi_src_open (GstAudioSrc * asrc);
70 static gboolean gst_wasapi_src_close (GstAudioSrc * asrc);
71 static gboolean gst_wasapi_src_prepare (GstAudioSrc * asrc,
72 GstAudioRingBufferSpec * spec);
73 static gboolean gst_wasapi_src_unprepare (GstAudioSrc * asrc);
74 static guint gst_wasapi_src_read (GstAudioSrc * asrc, gpointer data,
75 guint length, GstClockTime * timestamp);
76 static guint gst_wasapi_src_delay (GstAudioSrc * asrc);
77 static void gst_wasapi_src_reset (GstAudioSrc * asrc);
79 static GstClockTime gst_wasapi_src_get_time (GstClock * clock,
82 #define gst_wasapi_src_parent_class parent_class
83 G_DEFINE_TYPE (GstWasapiSrc, gst_wasapi_src, GST_TYPE_AUDIO_SRC);
86 gst_wasapi_src_class_init (GstWasapiSrcClass * klass)
88 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
89 GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
90 GstBaseSrcClass *gstbasesrc_class = GST_BASE_SRC_CLASS (klass);
91 GstAudioSrcClass *gstaudiosrc_class = GST_AUDIO_SRC_CLASS (klass);
93 gobject_class->dispose = gst_wasapi_src_dispose;
94 gobject_class->finalize = gst_wasapi_src_finalize;
95 gobject_class->set_property = gst_wasapi_src_set_property;
96 gobject_class->get_property = gst_wasapi_src_get_property;
98 g_object_class_install_property (gobject_class,
100 g_param_spec_enum ("role", "Role",
101 "Role of the device: communications, multimedia, etc",
102 GST_WASAPI_DEVICE_TYPE_ROLE, DEFAULT_ROLE, G_PARAM_READWRITE |
103 G_PARAM_STATIC_STRINGS | GST_PARAM_MUTABLE_READY));
105 g_object_class_install_property (gobject_class,
107 g_param_spec_string ("device", "Device",
108 "WASAPI playback device as a GUID string",
109 NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
111 gst_element_class_add_static_pad_template (gstelement_class, &src_template);
112 gst_element_class_set_static_metadata (gstelement_class, "WasapiSrc",
114 "Stream audio from an audio capture device through WASAPI",
115 "Ole André Vadla Ravnås <ole.andre.ravnas@tandberg.com>");
117 gstbasesrc_class->get_caps = GST_DEBUG_FUNCPTR (gst_wasapi_src_get_caps);
119 gstaudiosrc_class->open = GST_DEBUG_FUNCPTR (gst_wasapi_src_open);
120 gstaudiosrc_class->close = GST_DEBUG_FUNCPTR (gst_wasapi_src_close);
121 gstaudiosrc_class->read = GST_DEBUG_FUNCPTR (gst_wasapi_src_read);
122 gstaudiosrc_class->prepare = GST_DEBUG_FUNCPTR (gst_wasapi_src_prepare);
123 gstaudiosrc_class->unprepare = GST_DEBUG_FUNCPTR (gst_wasapi_src_unprepare);
124 gstaudiosrc_class->delay = GST_DEBUG_FUNCPTR (gst_wasapi_src_delay);
125 gstaudiosrc_class->reset = GST_DEBUG_FUNCPTR (gst_wasapi_src_reset);
127 GST_DEBUG_CATEGORY_INIT (gst_wasapi_src_debug, "wasapisrc",
128 0, "Windows audio session API source");
132 gst_wasapi_src_init (GstWasapiSrc * self)
134 /* override with a custom clock */
135 if (GST_AUDIO_BASE_SRC (self)->clock)
136 gst_object_unref (GST_AUDIO_BASE_SRC (self)->clock);
138 GST_AUDIO_BASE_SRC (self)->clock = gst_audio_clock_new ("GstWasapiSrcClock",
139 gst_wasapi_src_get_time, gst_object_ref (self),
140 (GDestroyNotify) gst_object_unref);
142 self->event_handle = CreateEvent (NULL, FALSE, FALSE, NULL);
148 gst_wasapi_src_dispose (GObject * object)
150 GstWasapiSrc *self = GST_WASAPI_SRC (object);
152 if (self->event_handle != NULL) {
153 CloseHandle (self->event_handle);
154 self->event_handle = NULL;
157 if (self->client_clock != NULL) {
158 IUnknown_Release (self->client_clock);
159 self->client_clock = NULL;
162 if (self->client != NULL) {
163 IUnknown_Release (self->client);
167 if (self->capture_client != NULL) {
168 IUnknown_Release (self->capture_client);
169 self->capture_client = NULL;
172 G_OBJECT_CLASS (parent_class)->dispose (object);
176 gst_wasapi_src_finalize (GObject * object)
178 GstWasapiSrc *self = GST_WASAPI_SRC (object);
180 g_clear_pointer (&self->mix_format, CoTaskMemFree);
184 g_clear_pointer (&self->cached_caps, gst_caps_unref);
185 g_clear_pointer (&self->positions, g_free);
186 g_clear_pointer (&self->device_strid, g_free);
188 G_OBJECT_CLASS (parent_class)->finalize (object);
192 gst_wasapi_src_set_property (GObject * object, guint prop_id,
193 const GValue * value, GParamSpec * pspec)
195 GstWasapiSrc *self = GST_WASAPI_SRC (object);
199 self->role = gst_wasapi_device_role_to_erole (g_value_get_enum (value));
203 const gchar *device = g_value_get_string (value);
204 g_free (self->device_strid);
206 device ? g_utf8_to_utf16 (device, -1, NULL, NULL, NULL) : NULL;
210 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
216 gst_wasapi_src_get_property (GObject * object, guint prop_id,
217 GValue * value, GParamSpec * pspec)
219 GstWasapiSrc *self = GST_WASAPI_SRC (object);
223 g_value_set_enum (value, gst_wasapi_erole_to_device_role (self->role));
226 g_value_take_string (value, self->device_strid ?
227 g_utf16_to_utf8 (self->device_strid, -1, NULL, NULL, NULL) : NULL);
230 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
236 gst_wasapi_src_get_caps (GstBaseSrc * bsrc, GstCaps * filter)
238 GstWasapiSrc *self = GST_WASAPI_SRC (bsrc);
239 WAVEFORMATEX *format = NULL;
240 GstCaps *caps = NULL;
243 GST_DEBUG_OBJECT (self, "entering get caps");
245 if (self->cached_caps) {
246 caps = gst_caps_ref (self->cached_caps);
248 GstCaps *template_caps;
250 template_caps = gst_pad_get_pad_template_caps (bsrc->srcpad);
253 gst_wasapi_src_open (GST_AUDIO_SRC (bsrc));
255 hr = IAudioClient_GetMixFormat (self->client, &format);
256 if (hr != S_OK || format == NULL) {
257 GST_ELEMENT_ERROR (self, STREAM, FORMAT, (NULL),
258 ("GetMixFormat failed: %s", gst_wasapi_util_hresult_to_string (hr)));
262 gst_wasapi_util_parse_waveformatex ((WAVEFORMATEXTENSIBLE *) format,
263 template_caps, &caps, &self->positions);
265 GST_ELEMENT_ERROR (self, STREAM, FORMAT, (NULL), ("unknown format"));
270 gchar *pos_str = gst_audio_channel_positions_to_string (self->positions,
272 GST_INFO_OBJECT (self, "positions are: %s", pos_str);
276 self->mix_format = format;
277 gst_caps_replace (&self->cached_caps, caps);
278 gst_caps_unref (template_caps);
283 gst_caps_intersect_full (filter, caps, GST_CAPS_INTERSECT_FIRST);
284 gst_caps_unref (caps);
288 GST_DEBUG_OBJECT (self, "returning caps %" GST_PTR_FORMAT, caps);
295 gst_wasapi_src_open (GstAudioSrc * asrc)
297 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
298 gboolean res = FALSE;
299 IAudioClient *client = NULL;
304 /* FIXME: Switching the default device does not switch the stream to it,
305 * even if the old device was unplugged. We need to handle this somehow.
306 * For example, perhaps we should automatically switch to the new device if
307 * the default device is changed and a device isn't explicitly selected. */
308 if (!gst_wasapi_util_get_device_client (GST_ELEMENT (self), TRUE,
309 self->role, self->device_strid, &client)) {
310 if (!self->device_strid)
311 GST_ELEMENT_ERROR (self, RESOURCE, OPEN_READ, (NULL),
312 ("Failed to get default device"));
314 GST_ELEMENT_ERROR (self, RESOURCE, OPEN_READ, (NULL),
315 ("Failed to open device %S", self->device_strid));
319 self->client = client;
328 gst_wasapi_src_close (GstAudioSrc * asrc)
330 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
332 if (self->client != NULL) {
333 IUnknown_Release (self->client);
341 gst_wasapi_src_prepare (GstAudioSrc * asrc, GstAudioRingBufferSpec * spec)
343 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
344 gboolean res = FALSE;
345 IAudioClock *client_clock = NULL;
346 guint64 client_clock_freq = 0;
347 IAudioCaptureClient *capture_client = NULL;
348 REFERENCE_TIME latency_rt;
349 gint64 default_period, min_period;
350 guint bpf, rate, buffer_frames;
353 hr = IAudioClient_GetDevicePeriod (self->client, &default_period,
356 GST_ERROR_OBJECT (self, "IAudioClient::GetDevicePeriod failed");
359 GST_INFO_OBJECT (self, "wasapi default period: %" G_GINT64_FORMAT
360 ", min period: %" G_GINT64_FORMAT, default_period, min_period);
362 /* Set hnsBufferDuration to 0, which should, in theory, tell the device to
363 * create a buffer with the smallest latency possible. In practice, this is
364 * usually 2 * default_period. See:
365 * https://msdn.microsoft.com/en-us/library/windows/desktop/dd370871(v=vs.85).aspx
367 * NOTE: min_period is a lie, and I have never seen WASAPI use it as the
369 hr = IAudioClient_Initialize (self->client, AUDCLNT_SHAREMODE_SHARED,
370 AUDCLNT_STREAMFLAGS_EVENTCALLBACK, 0, 0, self->mix_format, NULL);
372 GST_ELEMENT_ERROR (self, RESOURCE, OPEN_READ, (NULL),
373 ("IAudioClient::Initialize failed: %s",
374 gst_wasapi_util_hresult_to_string (hr)));
378 /* Total size in frames of the allocated buffer that we will read from */
379 hr = IAudioClient_GetBufferSize (self->client, &buffer_frames);
381 GST_ERROR_OBJECT (self, "IAudioClient::GetBufferSize failed");
385 bpf = GST_AUDIO_INFO_BPF (&spec->info);
386 rate = GST_AUDIO_INFO_RATE (&spec->info);
387 GST_INFO_OBJECT (self, "buffer size is %i frames, bpf is %i bytes, "
388 "rate is %i Hz", buffer_frames, bpf, rate);
390 spec->segsize = gst_util_uint64_scale_int_round (rate * bpf,
391 default_period * 100, GST_SECOND);
392 spec->segtotal = (buffer_frames * bpf) / spec->segsize;
394 GST_INFO_OBJECT (self, "segsize is %i, segtotal is %i", spec->segsize,
397 /* Get WASAPI latency for logging */
398 hr = IAudioClient_GetStreamLatency (self->client, &latency_rt);
400 GST_ERROR_OBJECT (self, "IAudioClient::GetStreamLatency failed");
403 GST_INFO_OBJECT (self, "wasapi stream latency: %" G_GINT64_FORMAT " (%"
404 G_GINT64_FORMAT " ms)", latency_rt, latency_rt / 10000);
406 /* Set the event handler which will trigger reads */
407 hr = IAudioClient_SetEventHandle (self->client, self->event_handle);
409 GST_ERROR_OBJECT (self, "IAudioClient::SetEventHandle failed");
413 /* Get the clock and the clock freq */
414 if (!gst_wasapi_util_get_clock (GST_ELEMENT (self), self->client,
419 hr = IAudioClock_GetFrequency (client_clock, &client_clock_freq);
421 GST_ERROR_OBJECT (self, "IAudioClock::GetFrequency failed");
425 /* Get capture source client and start it up */
426 if (!gst_wasapi_util_get_capture_client (GST_ELEMENT (self), self->client,
431 hr = IAudioClient_Start (self->client);
433 GST_ERROR_OBJECT (self, "IAudioClient::Start failed");
437 self->client_clock = client_clock;
438 self->client_clock_freq = client_clock_freq;
439 self->capture_client = capture_client;
441 gst_audio_ring_buffer_set_channel_positions (GST_AUDIO_BASE_SRC
442 (self)->ringbuffer, self->positions);
448 if (capture_client != NULL)
449 IUnknown_Release (capture_client);
451 if (client_clock != NULL)
452 IUnknown_Release (client_clock);
459 gst_wasapi_src_unprepare (GstAudioSrc * asrc)
461 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
463 if (self->client != NULL) {
464 IAudioClient_Stop (self->client);
467 if (self->capture_client != NULL) {
468 IUnknown_Release (self->capture_client);
469 self->capture_client = NULL;
472 if (self->client_clock != NULL) {
473 IUnknown_Release (self->client_clock);
474 self->client_clock = NULL;
481 gst_wasapi_src_read (GstAudioSrc * asrc, gpointer data, guint length,
482 GstClockTime * timestamp)
484 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
487 guint wanted = length;
491 guint have_frames, n_frames, want_frames, read_len;
493 /* Wait for data to become available */
494 WaitForSingleObject (self->event_handle, INFINITE);
496 hr = IAudioCaptureClient_GetBuffer (self->capture_client,
497 (BYTE **) & from, &have_frames, &flags, NULL, NULL);
499 if (hr == AUDCLNT_S_BUFFER_EMPTY)
500 GST_WARNING_OBJECT (self, "IAudioCaptureClient::GetBuffer failed: %s"
501 ", retrying", gst_wasapi_util_hresult_to_string (hr));
503 GST_ERROR_OBJECT (self, "IAudioCaptureClient::GetBuffer failed: %s",
504 gst_wasapi_util_hresult_to_string (hr));
510 GST_INFO_OBJECT (self, "buffer flags=%#08x", (guint) flags);
512 /* XXX: How do we handle AUDCLNT_BUFFERFLAGS_SILENT? We're supposed to write
513 * out silence when that flag is set? See:
514 * https://msdn.microsoft.com/en-us/library/windows/desktop/dd370800(v=vs.85).aspx */
516 if (flags & AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY)
517 GST_WARNING_OBJECT (self, "WASAPI reported glitch in buffer");
519 want_frames = wanted / self->mix_format->nBlockAlign;
521 /* If GetBuffer is returning more frames than we can handle, all we can do is
522 * hope that this is temporary and that things will settle down later. */
523 if (G_UNLIKELY (have_frames > want_frames))
524 GST_WARNING_OBJECT (self, "captured too many frames: have %i, want %i",
525 have_frames, want_frames);
527 /* Only copy data that will fit into the allocated buffer of size @length */
528 n_frames = MIN (have_frames, want_frames);
529 read_len = n_frames * self->mix_format->nBlockAlign;
532 guint bpf = self->mix_format->nBlockAlign;
533 GST_TRACE_OBJECT (self, "have: %i (%i bytes), can read: %i (%i bytes), "
534 "will read: %i (%i bytes)", have_frames, have_frames * bpf,
535 want_frames, wanted, n_frames, read_len);
538 memcpy (data, from, read_len);
541 /* Always release all captured buffers if we've captured any at all */
542 hr = IAudioCaptureClient_ReleaseBuffer (self->capture_client, have_frames);
544 GST_ERROR_OBJECT (self,
545 "IAudioCaptureClient::ReleaseBuffer () failed: %s",
546 gst_wasapi_util_hresult_to_string (hr));
558 gst_wasapi_src_delay (GstAudioSrc * asrc)
560 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
564 hr = IAudioClient_GetCurrentPadding (self->client, &delay);
566 GST_ELEMENT_ERROR (self, RESOURCE, READ, (NULL),
567 ("IAudioClient::GetCurrentPadding failed %s",
568 gst_wasapi_util_hresult_to_string (hr)));
575 gst_wasapi_src_reset (GstAudioSrc * asrc)
577 GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
581 hr = IAudioClient_Stop (self->client);
583 GST_ERROR_OBJECT (self, "IAudioClient::Stop () failed: %s",
584 gst_wasapi_util_hresult_to_string (hr));
588 hr = IAudioClient_Reset (self->client);
590 GST_ERROR_OBJECT (self, "IAudioClient::Reset () failed: %s",
591 gst_wasapi_util_hresult_to_string (hr));
598 gst_wasapi_src_get_time (GstClock * clock, gpointer user_data)
600 GstWasapiSrc *self = GST_WASAPI_SRC (user_data);
605 if (G_UNLIKELY (self->client_clock == NULL))
606 return GST_CLOCK_TIME_NONE;
608 hr = IAudioClock_GetPosition (self->client_clock, &devpos, NULL);
609 if (G_UNLIKELY (hr != S_OK))
610 return GST_CLOCK_TIME_NONE;
612 result = gst_util_uint64_scale_int (devpos, GST_SECOND,
613 self->client_clock_freq);
616 GST_DEBUG_OBJECT (self, "devpos = %" G_GUINT64_FORMAT
617 " frequency = %" G_GUINT64_FORMAT
618 " result = %" G_GUINT64_FORMAT " ms",
619 devpos, self->client_clock_freq, GST_TIME_AS_MSECONDS (result));