2 * Copyright (C) 2008 Ole André Vadla Ravnås <ole.andre.ravnas@tandberg.com>
3 * Copyright (C) 2013 Collabora Ltd.
4 * Author: Sebastian Dröge <sebastian.droege@collabora.co.uk>
5 * Copyright (C) 2018 Centricular Ltd.
6 * Author: Nirbheek Chauhan <nirbheek@centricular.com>
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
25 * SECTION:element-wasapisink
28 * Provides audio playback using the Windows Audio Session API available with
31 * ## Example pipelines
33 * gst-launch-1.0 -v audiotestsrc samplesperbuffer=160 ! wasapisink
34 * ]| Generate 20 ms buffers and render to the default audio device.
41 #include "gstwasapisink.h"
45 GST_DEBUG_CATEGORY_STATIC (gst_wasapi_sink_debug);
46 #define GST_CAT_DEFAULT gst_wasapi_sink_debug
48 static GstStaticPadTemplate sink_template = GST_STATIC_PAD_TEMPLATE ("sink",
51 GST_STATIC_CAPS (GST_WASAPI_STATIC_CAPS));
53 #define DEFAULT_ROLE GST_WASAPI_DEVICE_ROLE_CONSOLE
54 #define DEFAULT_MUTE FALSE
55 #define DEFAULT_EXCLUSIVE FALSE
56 #define DEFAULT_LOW_LATENCY FALSE
57 #define DEFAULT_AUDIOCLIENT3 TRUE
70 static void gst_wasapi_sink_dispose (GObject * object);
71 static void gst_wasapi_sink_finalize (GObject * object);
72 static void gst_wasapi_sink_set_property (GObject * object, guint prop_id,
73 const GValue * value, GParamSpec * pspec);
74 static void gst_wasapi_sink_get_property (GObject * object, guint prop_id,
75 GValue * value, GParamSpec * pspec);
77 static GstCaps *gst_wasapi_sink_get_caps (GstBaseSink * bsink,
80 static gboolean gst_wasapi_sink_prepare (GstAudioSink * asink,
81 GstAudioRingBufferSpec * spec);
82 static gboolean gst_wasapi_sink_unprepare (GstAudioSink * asink);
83 static gboolean gst_wasapi_sink_open (GstAudioSink * asink);
84 static gboolean gst_wasapi_sink_close (GstAudioSink * asink);
85 static gint gst_wasapi_sink_write (GstAudioSink * asink,
86 gpointer data, guint length);
87 static guint gst_wasapi_sink_delay (GstAudioSink * asink);
88 static void gst_wasapi_sink_reset (GstAudioSink * asink);
90 #define gst_wasapi_sink_parent_class parent_class
91 G_DEFINE_TYPE (GstWasapiSink, gst_wasapi_sink, GST_TYPE_AUDIO_SINK);
94 gst_wasapi_sink_class_init (GstWasapiSinkClass * klass)
96 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
97 GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
98 GstBaseSinkClass *gstbasesink_class = GST_BASE_SINK_CLASS (klass);
99 GstAudioSinkClass *gstaudiosink_class = GST_AUDIO_SINK_CLASS (klass);
101 gobject_class->dispose = gst_wasapi_sink_dispose;
102 gobject_class->finalize = gst_wasapi_sink_finalize;
103 gobject_class->set_property = gst_wasapi_sink_set_property;
104 gobject_class->get_property = gst_wasapi_sink_get_property;
106 g_object_class_install_property (gobject_class,
108 g_param_spec_enum ("role", "Role",
109 "Role of the device: communications, multimedia, etc",
110 GST_WASAPI_DEVICE_TYPE_ROLE, DEFAULT_ROLE, G_PARAM_READWRITE |
111 G_PARAM_STATIC_STRINGS | GST_PARAM_MUTABLE_READY));
113 g_object_class_install_property (gobject_class,
115 g_param_spec_boolean ("mute", "Mute", "Mute state of this stream",
116 DEFAULT_MUTE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS |
117 GST_PARAM_MUTABLE_PLAYING));
119 g_object_class_install_property (gobject_class,
121 g_param_spec_string ("device", "Device",
122 "WASAPI playback device as a GUID string",
123 NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
125 g_object_class_install_property (gobject_class,
127 g_param_spec_boolean ("exclusive", "Exclusive mode",
128 "Open the device in exclusive mode",
129 DEFAULT_EXCLUSIVE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
131 g_object_class_install_property (gobject_class,
133 g_param_spec_boolean ("low-latency", "Low latency",
134 "Optimize all settings for lowest latency",
135 DEFAULT_LOW_LATENCY, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
137 g_object_class_install_property (gobject_class,
139 g_param_spec_boolean ("use-audioclient3", "Use the AudioClient3 API",
140 "Use the Windows 10 AudioClient3 API when available",
141 DEFAULT_AUDIOCLIENT3, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
143 gst_element_class_add_static_pad_template (gstelement_class, &sink_template);
144 gst_element_class_set_static_metadata (gstelement_class, "WasapiSrc",
146 "Stream audio to an audio capture device through WASAPI",
147 "Ole André Vadla Ravnås <ole.andre.ravnas@tandberg.com>");
149 gstbasesink_class->get_caps = GST_DEBUG_FUNCPTR (gst_wasapi_sink_get_caps);
151 gstaudiosink_class->prepare = GST_DEBUG_FUNCPTR (gst_wasapi_sink_prepare);
152 gstaudiosink_class->unprepare = GST_DEBUG_FUNCPTR (gst_wasapi_sink_unprepare);
153 gstaudiosink_class->open = GST_DEBUG_FUNCPTR (gst_wasapi_sink_open);
154 gstaudiosink_class->close = GST_DEBUG_FUNCPTR (gst_wasapi_sink_close);
155 gstaudiosink_class->write = GST_DEBUG_FUNCPTR (gst_wasapi_sink_write);
156 gstaudiosink_class->delay = GST_DEBUG_FUNCPTR (gst_wasapi_sink_delay);
157 gstaudiosink_class->reset = GST_DEBUG_FUNCPTR (gst_wasapi_sink_reset);
159 GST_DEBUG_CATEGORY_INIT (gst_wasapi_sink_debug, "wasapisink",
160 0, "Windows audio session API sink");
164 gst_wasapi_sink_init (GstWasapiSink * self)
166 self->role = DEFAULT_ROLE;
167 self->mute = DEFAULT_MUTE;
168 self->sharemode = AUDCLNT_SHAREMODE_SHARED;
169 self->low_latency = DEFAULT_LOW_LATENCY;
170 self->try_audioclient3 = DEFAULT_AUDIOCLIENT3;
171 self->event_handle = CreateEvent (NULL, FALSE, FALSE, NULL);
177 gst_wasapi_sink_dispose (GObject * object)
179 GstWasapiSink *self = GST_WASAPI_SINK (object);
181 if (self->event_handle != NULL) {
182 CloseHandle (self->event_handle);
183 self->event_handle = NULL;
186 if (self->client != NULL) {
187 IUnknown_Release (self->client);
191 if (self->render_client != NULL) {
192 IUnknown_Release (self->render_client);
193 self->render_client = NULL;
196 G_OBJECT_CLASS (gst_wasapi_sink_parent_class)->dispose (object);
200 gst_wasapi_sink_finalize (GObject * object)
202 GstWasapiSink *self = GST_WASAPI_SINK (object);
204 g_clear_pointer (&self->mix_format, CoTaskMemFree);
208 if (self->cached_caps != NULL) {
209 gst_caps_unref (self->cached_caps);
210 self->cached_caps = NULL;
213 g_clear_pointer (&self->positions, g_free);
214 g_clear_pointer (&self->device_strid, g_free);
217 G_OBJECT_CLASS (gst_wasapi_sink_parent_class)->finalize (object);
221 gst_wasapi_sink_set_property (GObject * object, guint prop_id,
222 const GValue * value, GParamSpec * pspec)
224 GstWasapiSink *self = GST_WASAPI_SINK (object);
228 self->role = gst_wasapi_device_role_to_erole (g_value_get_enum (value));
231 self->mute = g_value_get_boolean (value);
235 const gchar *device = g_value_get_string (value);
236 g_free (self->device_strid);
238 device ? g_utf8_to_utf16 (device, -1, NULL, NULL, NULL) : NULL;
242 self->sharemode = g_value_get_boolean (value)
243 ? AUDCLNT_SHAREMODE_EXCLUSIVE : AUDCLNT_SHAREMODE_SHARED;
245 case PROP_LOW_LATENCY:
246 self->low_latency = g_value_get_boolean (value);
248 case PROP_AUDIOCLIENT3:
249 self->try_audioclient3 = g_value_get_boolean (value);
252 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
258 gst_wasapi_sink_get_property (GObject * object, guint prop_id,
259 GValue * value, GParamSpec * pspec)
261 GstWasapiSink *self = GST_WASAPI_SINK (object);
265 g_value_set_enum (value, gst_wasapi_erole_to_device_role (self->role));
268 g_value_set_boolean (value, self->mute);
271 g_value_take_string (value, self->device_strid ?
272 g_utf16_to_utf8 (self->device_strid, -1, NULL, NULL, NULL) : NULL);
275 g_value_set_boolean (value,
276 self->sharemode == AUDCLNT_SHAREMODE_EXCLUSIVE);
278 case PROP_LOW_LATENCY:
279 g_value_set_boolean (value, self->low_latency);
281 case PROP_AUDIOCLIENT3:
282 g_value_set_boolean (value, self->try_audioclient3);
285 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
291 gst_wasapi_sink_can_audioclient3 (GstWasapiSink * self)
293 if (self->sharemode == AUDCLNT_SHAREMODE_SHARED &&
294 self->try_audioclient3 && gst_wasapi_util_have_audioclient3 ())
300 gst_wasapi_sink_get_caps (GstBaseSink * bsink, GstCaps * filter)
302 GstWasapiSink *self = GST_WASAPI_SINK (bsink);
303 WAVEFORMATEX *format = NULL;
304 GstCaps *caps = NULL;
306 GST_DEBUG_OBJECT (self, "entering get caps");
308 if (self->cached_caps) {
309 caps = gst_caps_ref (self->cached_caps);
311 GstCaps *template_caps;
314 template_caps = gst_pad_get_pad_template_caps (bsink->sinkpad);
317 gst_wasapi_sink_open (GST_AUDIO_SINK (bsink));
319 ret = gst_wasapi_util_get_device_format (GST_ELEMENT (self),
320 self->sharemode, self->device, self->client, &format);
322 GST_ELEMENT_ERROR (self, STREAM, FORMAT, (NULL),
323 ("failed to detect format"));
327 gst_wasapi_util_parse_waveformatex ((WAVEFORMATEXTENSIBLE *) format,
328 template_caps, &caps, &self->positions);
330 GST_ELEMENT_ERROR (self, STREAM, FORMAT, (NULL), ("unknown format"));
335 gchar *pos_str = gst_audio_channel_positions_to_string (self->positions,
337 GST_INFO_OBJECT (self, "positions are: %s", pos_str);
341 self->mix_format = format;
342 gst_caps_replace (&self->cached_caps, caps);
343 gst_caps_unref (template_caps);
348 gst_caps_intersect_full (filter, caps, GST_CAPS_INTERSECT_FIRST);
349 gst_caps_unref (caps);
353 GST_DEBUG_OBJECT (self, "returning caps %" GST_PTR_FORMAT, caps);
360 gst_wasapi_sink_open (GstAudioSink * asink)
362 GstWasapiSink *self = GST_WASAPI_SINK (asink);
363 gboolean res = FALSE;
364 IMMDevice *device = NULL;
365 IAudioClient *client = NULL;
367 GST_DEBUG_OBJECT (self, "opening device");
372 /* FIXME: Switching the default device does not switch the stream to it,
373 * even if the old device was unplugged. We need to handle this somehow.
374 * For example, perhaps we should automatically switch to the new device if
375 * the default device is changed and a device isn't explicitly selected. */
376 if (!gst_wasapi_util_get_device_client (GST_ELEMENT (self), FALSE,
377 self->role, self->device_strid, &device, &client)) {
378 if (!self->device_strid)
379 GST_ELEMENT_ERROR (self, RESOURCE, OPEN_WRITE, (NULL),
380 ("Failed to get default device"));
382 GST_ELEMENT_ERROR (self, RESOURCE, OPEN_WRITE, (NULL),
383 ("Failed to open device %S", self->device_strid));
387 self->client = client;
388 self->device = device;
397 gst_wasapi_sink_close (GstAudioSink * asink)
399 GstWasapiSink *self = GST_WASAPI_SINK (asink);
401 if (self->device != NULL) {
402 IUnknown_Release (self->device);
406 if (self->client != NULL) {
407 IUnknown_Release (self->client);
414 /* Get the empty space in the buffer that we have to write to */
416 gst_wasapi_sink_get_can_frames (GstWasapiSink * self)
419 guint n_frames_padding;
421 /* There is no padding in exclusive mode since there is no ringbuffer */
422 if (self->sharemode == AUDCLNT_SHAREMODE_EXCLUSIVE) {
423 GST_DEBUG_OBJECT (self, "exclusive mode, can write: %i",
424 self->buffer_frame_count);
425 return self->buffer_frame_count;
428 /* Frames the card hasn't rendered yet */
429 hr = IAudioClient_GetCurrentPadding (self->client, &n_frames_padding);
430 HR_FAILED_RET (hr, IAudioClient::GetCurrentPadding, -1);
432 GST_DEBUG_OBJECT (self, "%i unread frames (padding)", n_frames_padding);
434 /* We can write out these many frames */
435 return self->buffer_frame_count - n_frames_padding;
439 gst_wasapi_sink_prepare (GstAudioSink * asink, GstAudioRingBufferSpec * spec)
441 GstWasapiSink *self = GST_WASAPI_SINK (asink);
442 gboolean res = FALSE;
443 REFERENCE_TIME latency_rt;
444 guint bpf, rate, devicep_frames;
447 if (gst_wasapi_sink_can_audioclient3 (self)) {
448 if (!gst_wasapi_util_initialize_audioclient3 (GST_ELEMENT (self), spec,
449 (IAudioClient3 *) self->client, self->mix_format, self->low_latency,
453 if (!gst_wasapi_util_initialize_audioclient (GST_ELEMENT (self), spec,
454 self->client, self->mix_format, self->sharemode, self->low_latency,
459 bpf = GST_AUDIO_INFO_BPF (&spec->info);
460 rate = GST_AUDIO_INFO_RATE (&spec->info);
462 /* Total size of the allocated buffer that we will write to */
463 hr = IAudioClient_GetBufferSize (self->client, &self->buffer_frame_count);
464 HR_FAILED_GOTO (hr, IAudioClient::GetBufferSize, beach);
466 GST_INFO_OBJECT (self, "buffer size is %i frames, device period is %i "
467 "frames, bpf is %i bytes, rate is %i Hz", self->buffer_frame_count,
468 devicep_frames, bpf, rate);
470 /* Actual latency-time/buffer-time will be different now */
471 spec->segsize = devicep_frames * bpf;
473 /* We need a minimum of 2 segments to ensure glitch-free playback */
474 spec->segtotal = MAX (self->buffer_frame_count * bpf / spec->segsize, 2);
476 GST_INFO_OBJECT (self, "segsize is %i, segtotal is %i", spec->segsize,
479 /* Get latency for logging */
480 hr = IAudioClient_GetStreamLatency (self->client, &latency_rt);
481 HR_FAILED_GOTO (hr, IAudioClient::GetStreamLatency, beach);
483 GST_INFO_OBJECT (self, "wasapi stream latency: %" G_GINT64_FORMAT " (%"
484 G_GINT64_FORMAT "ms)", latency_rt, latency_rt / 10000);
486 /* Set the event handler which will trigger writes */
487 hr = IAudioClient_SetEventHandle (self->client, self->event_handle);
488 HR_FAILED_GOTO (hr, IAudioClient::SetEventHandle, beach);
490 /* Get render sink client and start it up */
491 if (!gst_wasapi_util_get_render_client (GST_ELEMENT (self), self->client,
492 &self->render_client)) {
496 GST_INFO_OBJECT (self, "got render client");
498 /* To avoid start-up glitches, before starting the streaming, we fill the
499 * buffer with silence as recommended by the documentation:
500 * https://msdn.microsoft.com/en-us/library/windows/desktop/dd370879%28v=vs.85%29.aspx */
505 n_frames = gst_wasapi_sink_get_can_frames (self);
507 GST_ELEMENT_ERROR (self, RESOURCE, WRITE, (NULL),
508 ("should have more than %i frames to write", n_frames));
512 len = n_frames * self->mix_format->nBlockAlign;
514 hr = IAudioRenderClient_GetBuffer (self->render_client, n_frames,
516 HR_FAILED_GOTO (hr, IAudioRenderClient::GetBuffer, beach);
518 GST_DEBUG_OBJECT (self, "pre-wrote %i bytes of silence", len);
520 hr = IAudioRenderClient_ReleaseBuffer (self->render_client, n_frames,
521 AUDCLNT_BUFFERFLAGS_SILENT);
522 HR_FAILED_GOTO (hr, IAudioRenderClient::ReleaseBuffer, beach);
525 hr = IAudioClient_Start (self->client);
526 HR_FAILED_GOTO (hr, IAudioClient::Start, beach);
528 gst_audio_ring_buffer_set_channel_positions (GST_AUDIO_BASE_SINK
529 (self)->ringbuffer, self->positions);
531 /* Increase the thread priority to reduce glitches */
532 self->thread_priority_handle = gst_wasapi_util_set_thread_characteristics ();
537 /* unprepare() is not called if prepare() fails, but we want it to be, so call
538 * it manually when needed */
540 gst_wasapi_sink_unprepare (asink);
546 gst_wasapi_sink_unprepare (GstAudioSink * asink)
548 GstWasapiSink *self = GST_WASAPI_SINK (asink);
550 if (self->sharemode == AUDCLNT_SHAREMODE_EXCLUSIVE &&
551 !gst_wasapi_sink_can_audioclient3 (self))
554 if (self->thread_priority_handle != NULL) {
555 gst_wasapi_util_revert_thread_characteristics
556 (self->thread_priority_handle);
557 self->thread_priority_handle = NULL;
560 if (self->client != NULL) {
561 IAudioClient_Stop (self->client);
564 if (self->render_client != NULL) {
565 IUnknown_Release (self->render_client);
566 self->render_client = NULL;
573 gst_wasapi_sink_write (GstAudioSink * asink, gpointer data, guint length)
575 GstWasapiSink *self = GST_WASAPI_SINK (asink);
578 guint pending = length;
580 while (pending > 0) {
581 guint can_frames, have_frames, n_frames, write_len;
583 WaitForSingleObject (self->event_handle, INFINITE);
585 /* We have N frames to be written out */
586 have_frames = pending / (self->mix_format->nBlockAlign);
587 /* We have can_frames space in the output buffer */
588 can_frames = gst_wasapi_sink_get_can_frames (self);
589 /* We will write out these many frames, and this much length */
590 n_frames = MIN (can_frames, have_frames);
591 write_len = n_frames * self->mix_format->nBlockAlign;
593 GST_DEBUG_OBJECT (self, "total: %i, have_frames: %i (%i bytes), "
594 "can_frames: %i, will write: %i (%i bytes)", self->buffer_frame_count,
595 have_frames, pending, can_frames, n_frames, write_len);
597 hr = IAudioRenderClient_GetBuffer (self->render_client, n_frames,
599 HR_FAILED_AND (hr, IAudioRenderClient::GetBuffer, length = 0; goto beach);
601 memcpy (dst, data, write_len);
603 hr = IAudioRenderClient_ReleaseBuffer (self->render_client, n_frames,
604 self->mute ? AUDCLNT_BUFFERFLAGS_SILENT : 0);
605 HR_FAILED_AND (hr, IAudioRenderClient::ReleaseBuffer, length = 0;
608 pending -= write_len;
617 gst_wasapi_sink_delay (GstAudioSink * asink)
619 GstWasapiSink *self = GST_WASAPI_SINK (asink);
623 hr = IAudioClient_GetCurrentPadding (self->client, &delay);
624 HR_FAILED_RET (hr, IAudioClient::GetCurrentPadding, 0);
630 gst_wasapi_sink_reset (GstAudioSink * asink)
632 GstWasapiSink *self = GST_WASAPI_SINK (asink);
638 hr = IAudioClient_Stop (self->client);
639 HR_FAILED_RET (hr, IAudioClient::Stop,);
641 hr = IAudioClient_Reset (self->client);
642 HR_FAILED_RET (hr, IAudioClient::Reset,);