2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2005 Wim Taymans <wim@fluendo.com>
5 * gstaudiosink.c: simple audio sink base class
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.
24 * SECTION:gstaudiosink
25 * @short_description: Simple base class for audio sinks
26 * @see_also: #GstAudioBaseSink, #GstAudioRingBuffer, #GstAudioSink.
28 * This is the most simple base class for audio sinks that only requires
29 * subclasses to implement a set of simple functions:
34 * <listitem><para>Open the device.</para></listitem>
37 * <term>prepare()</term>
38 * <listitem><para>Configure the device with the specified format.</para></listitem>
41 * <term>write()</term>
42 * <listitem><para>Write samples to the device.</para></listitem>
45 * <term>reset()</term>
46 * <listitem><para>Unblock writes and flush the device.</para></listitem>
49 * <term>delay()</term>
50 * <listitem><para>Get the number of samples written but not yet played
51 * by the device.</para></listitem>
54 * <term>unprepare()</term>
55 * <listitem><para>Undo operations done by prepare.</para></listitem>
58 * <term>close()</term>
59 * <listitem><para>Close the device.</para></listitem>
63 * All scheduling of samples and timestamps is done in this base class
64 * together with #GstAudioBaseSink using a default implementation of a
65 * #GstAudioRingBuffer that uses threads.
67 * Last reviewed on 2006-09-27 (0.10.12)
72 #include <gst/audio/audio.h>
73 #include "gstaudiosink.h"
75 GST_DEBUG_CATEGORY_STATIC (gst_audio_sink_debug);
76 #define GST_CAT_DEFAULT gst_audio_sink_debug
78 #define GST_TYPE_AUDIO_SINK_RING_BUFFER \
79 (gst_audio_sink_ring_buffer_get_type())
80 #define GST_AUDIO_SINK_RING_BUFFER(obj) \
81 (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_AUDIO_SINK_RING_BUFFER,GstAudioSinkRingBuffer))
82 #define GST_AUDIO_SINK_RING_BUFFER_CLASS(klass) \
83 (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_AUDIO_SINK_RING_BUFFER,GstAudioSinkRingBufferClass))
84 #define GST_AUDIO_SINK_RING_BUFFER_GET_CLASS(obj) \
85 (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_AUDIO_SINK_RING_BUFFER, GstAudioSinkRingBufferClass))
86 #define GST_AUDIO_SINK_RING_BUFFER_CAST(obj) \
87 ((GstAudioSinkRingBuffer *)obj)
88 #define GST_IS_AUDIO_SINK_RING_BUFFER(obj) \
89 (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_AUDIO_SINK_RING_BUFFER))
90 #define GST_IS_AUDIO_SINK_RING_BUFFER_CLASS(klass)\
91 (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_AUDIO_SINK_RING_BUFFER))
93 typedef struct _GstAudioSinkRingBuffer GstAudioSinkRingBuffer;
94 typedef struct _GstAudioSinkRingBufferClass GstAudioSinkRingBufferClass;
96 #define GST_AUDIO_SINK_RING_BUFFER_GET_COND(buf) (&(((GstAudioSinkRingBuffer *)buf)->cond))
97 #define GST_AUDIO_SINK_RING_BUFFER_WAIT(buf) (g_cond_wait (GST_AUDIO_SINK_RING_BUFFER_GET_COND (buf), GST_OBJECT_GET_LOCK (buf)))
98 #define GST_AUDIO_SINK_RING_BUFFER_SIGNAL(buf) (g_cond_signal (GST_AUDIO_SINK_RING_BUFFER_GET_COND (buf)))
99 #define GST_AUDIO_SINK_RING_BUFFER_BROADCAST(buf)(g_cond_broadcast (GST_AUDIO_SINK_RING_BUFFER_GET_COND (buf)))
101 struct _GstAudioSinkRingBuffer
103 GstAudioRingBuffer object;
111 struct _GstAudioSinkRingBufferClass
113 GstAudioRingBufferClass parent_class;
116 static void gst_audio_sink_ring_buffer_class_init (GstAudioSinkRingBufferClass *
118 static void gst_audio_sink_ring_buffer_init (GstAudioSinkRingBuffer *
119 ringbuffer, GstAudioSinkRingBufferClass * klass);
120 static void gst_audio_sink_ring_buffer_dispose (GObject * object);
121 static void gst_audio_sink_ring_buffer_finalize (GObject * object);
123 static GstAudioRingBufferClass *ring_parent_class = NULL;
125 static gboolean gst_audio_sink_ring_buffer_open_device (GstAudioRingBuffer *
127 static gboolean gst_audio_sink_ring_buffer_close_device (GstAudioRingBuffer *
129 static gboolean gst_audio_sink_ring_buffer_acquire (GstAudioRingBuffer * buf,
130 GstAudioRingBufferSpec * spec);
131 static gboolean gst_audio_sink_ring_buffer_release (GstAudioRingBuffer * buf);
132 static gboolean gst_audio_sink_ring_buffer_start (GstAudioRingBuffer * buf);
133 static gboolean gst_audio_sink_ring_buffer_pause (GstAudioRingBuffer * buf);
134 static gboolean gst_audio_sink_ring_buffer_stop (GstAudioRingBuffer * buf);
135 static guint gst_audio_sink_ring_buffer_delay (GstAudioRingBuffer * buf);
136 static gboolean gst_audio_sink_ring_buffer_activate (GstAudioRingBuffer * buf,
139 /* ringbuffer abstract base class */
141 gst_audio_sink_ring_buffer_get_type (void)
143 static GType ringbuffer_type = 0;
145 if (!ringbuffer_type) {
146 static const GTypeInfo ringbuffer_info = {
147 sizeof (GstAudioSinkRingBufferClass),
150 (GClassInitFunc) gst_audio_sink_ring_buffer_class_init,
153 sizeof (GstAudioSinkRingBuffer),
155 (GInstanceInitFunc) gst_audio_sink_ring_buffer_init,
160 g_type_register_static (GST_TYPE_AUDIO_RING_BUFFER,
161 "GstAudioSinkRingBuffer", &ringbuffer_info, 0);
163 return ringbuffer_type;
167 gst_audio_sink_ring_buffer_class_init (GstAudioSinkRingBufferClass * klass)
169 GObjectClass *gobject_class;
170 GstAudioRingBufferClass *gstringbuffer_class;
172 gobject_class = (GObjectClass *) klass;
173 gstringbuffer_class = (GstAudioRingBufferClass *) klass;
175 ring_parent_class = g_type_class_peek_parent (klass);
177 gobject_class->dispose = gst_audio_sink_ring_buffer_dispose;
178 gobject_class->finalize = gst_audio_sink_ring_buffer_finalize;
180 gstringbuffer_class->open_device =
181 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_open_device);
182 gstringbuffer_class->close_device =
183 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_close_device);
184 gstringbuffer_class->acquire =
185 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_acquire);
186 gstringbuffer_class->release =
187 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_release);
188 gstringbuffer_class->start =
189 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_start);
190 gstringbuffer_class->pause =
191 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_pause);
192 gstringbuffer_class->resume =
193 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_start);
194 gstringbuffer_class->stop =
195 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_stop);
197 gstringbuffer_class->delay =
198 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_delay);
199 gstringbuffer_class->activate =
200 GST_DEBUG_FUNCPTR (gst_audio_sink_ring_buffer_activate);
203 typedef gint (*WriteFunc) (GstAudioSink * sink, gpointer data, guint length);
205 /* this internal thread does nothing else but write samples to the audio device.
206 * It will write each segment in the ringbuffer and will update the play
208 * The start/stop methods control the thread.
211 audioringbuffer_thread_func (GstAudioRingBuffer * buf)
214 GstAudioSinkClass *csink;
215 GstAudioSinkRingBuffer *abuf = GST_AUDIO_SINK_RING_BUFFER_CAST (buf);
220 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
221 csink = GST_AUDIO_SINK_GET_CLASS (sink);
223 GST_DEBUG_OBJECT (sink, "enter thread");
225 GST_OBJECT_LOCK (abuf);
226 GST_DEBUG_OBJECT (sink, "signal wait");
227 GST_AUDIO_SINK_RING_BUFFER_SIGNAL (buf);
228 GST_OBJECT_UNLOCK (abuf);
230 writefunc = csink->write;
231 if (writefunc == NULL)
234 message = gst_message_new_stream_status (GST_OBJECT_CAST (buf),
235 GST_STREAM_STATUS_TYPE_ENTER, GST_ELEMENT_CAST (sink));
236 g_value_init (&val, GST_TYPE_G_THREAD);
237 g_value_set_boxed (&val, sink->thread);
238 gst_message_set_stream_status_object (message, &val);
239 g_value_unset (&val);
240 GST_DEBUG_OBJECT (sink, "posting ENTER stream status");
241 gst_element_post_message (GST_ELEMENT_CAST (sink), message);
248 /* buffer must be started */
249 if (gst_audio_ring_buffer_prepare_read (buf, &readseg, &readptr, &len)) {
254 written = writefunc (sink, readptr, left);
255 GST_LOG_OBJECT (sink, "transfered %d bytes of %d from segment %d",
256 written, left, readseg);
257 if (written < 0 || written > left) {
258 /* might not be critical, it e.g. happens when aborting playback */
259 GST_WARNING_OBJECT (sink,
260 "error writing data in %s (reason: %s), skipping segment (left: %d, written: %d)",
261 GST_DEBUG_FUNCPTR_NAME (writefunc),
262 (errno > 1 ? g_strerror (errno) : "unknown"), left, written);
269 /* clear written samples */
270 gst_audio_ring_buffer_clear (buf, readseg);
272 /* we wrote one segment */
273 gst_audio_ring_buffer_advance (buf, 1);
275 GST_OBJECT_LOCK (abuf);
278 if (G_UNLIKELY (g_atomic_int_get (&buf->state) ==
279 GST_AUDIO_RING_BUFFER_STATE_STARTED)) {
280 GST_OBJECT_UNLOCK (abuf);
283 GST_DEBUG_OBJECT (sink, "signal wait");
284 GST_AUDIO_SINK_RING_BUFFER_SIGNAL (buf);
285 GST_DEBUG_OBJECT (sink, "wait for action");
286 GST_AUDIO_SINK_RING_BUFFER_WAIT (buf);
287 GST_DEBUG_OBJECT (sink, "got signal");
290 GST_DEBUG_OBJECT (sink, "continue running");
291 GST_OBJECT_UNLOCK (abuf);
295 /* Will never be reached */
296 g_assert_not_reached ();
302 GST_DEBUG_OBJECT (sink, "no write function, exit thread");
307 GST_OBJECT_UNLOCK (abuf);
308 GST_DEBUG_OBJECT (sink, "stop running, exit thread");
309 message = gst_message_new_stream_status (GST_OBJECT_CAST (buf),
310 GST_STREAM_STATUS_TYPE_LEAVE, GST_ELEMENT_CAST (sink));
311 g_value_init (&val, GST_TYPE_G_THREAD);
312 g_value_set_boxed (&val, sink->thread);
313 gst_message_set_stream_status_object (message, &val);
314 g_value_unset (&val);
315 GST_DEBUG_OBJECT (sink, "posting LEAVE stream status");
316 gst_element_post_message (GST_ELEMENT_CAST (sink), message);
322 gst_audio_sink_ring_buffer_init (GstAudioSinkRingBuffer * ringbuffer,
323 GstAudioSinkRingBufferClass * g_class)
325 ringbuffer->running = FALSE;
326 ringbuffer->queuedseg = 0;
328 g_cond_init (&ringbuffer->cond);
332 gst_audio_sink_ring_buffer_dispose (GObject * object)
334 G_OBJECT_CLASS (ring_parent_class)->dispose (object);
338 gst_audio_sink_ring_buffer_finalize (GObject * object)
340 GstAudioSinkRingBuffer *ringbuffer = GST_AUDIO_SINK_RING_BUFFER_CAST (object);
342 g_cond_clear (&ringbuffer->cond);
344 G_OBJECT_CLASS (ring_parent_class)->finalize (object);
348 gst_audio_sink_ring_buffer_open_device (GstAudioRingBuffer * buf)
351 GstAudioSinkClass *csink;
352 gboolean result = TRUE;
354 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
355 csink = GST_AUDIO_SINK_GET_CLASS (sink);
358 result = csink->open (sink);
367 GST_DEBUG_OBJECT (sink, "could not open device");
373 gst_audio_sink_ring_buffer_close_device (GstAudioRingBuffer * buf)
376 GstAudioSinkClass *csink;
377 gboolean result = TRUE;
379 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
380 csink = GST_AUDIO_SINK_GET_CLASS (sink);
383 result = csink->close (sink);
386 goto could_not_close;
392 GST_DEBUG_OBJECT (sink, "could not close device");
398 gst_audio_sink_ring_buffer_acquire (GstAudioRingBuffer * buf,
399 GstAudioRingBufferSpec * spec)
402 GstAudioSinkClass *csink;
403 gboolean result = FALSE;
405 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
406 csink = GST_AUDIO_SINK_GET_CLASS (sink);
409 result = csink->prepare (sink, spec);
411 goto could_not_prepare;
413 /* set latency to one more segment as we need some headroom */
414 spec->seglatency = spec->segtotal + 1;
416 buf->size = spec->segtotal * spec->segsize;
417 buf->memory = g_malloc0 (buf->size);
424 GST_DEBUG_OBJECT (sink, "could not prepare device");
430 gst_audio_sink_ring_buffer_activate (GstAudioRingBuffer * buf, gboolean active)
433 GstAudioSinkRingBuffer *abuf;
434 GError *error = NULL;
436 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
437 abuf = GST_AUDIO_SINK_RING_BUFFER_CAST (buf);
440 abuf->running = TRUE;
442 GST_DEBUG_OBJECT (sink, "starting thread");
444 sink->thread = g_thread_try_new ("audiosink-ringbuffer",
445 (GThreadFunc) audioringbuffer_thread_func, buf, &error);
447 if (!sink->thread || error != NULL)
450 GST_DEBUG_OBJECT (sink, "waiting for thread");
451 /* the object lock is taken */
452 GST_AUDIO_SINK_RING_BUFFER_WAIT (buf);
453 GST_DEBUG_OBJECT (sink, "thread is started");
455 abuf->running = FALSE;
456 GST_DEBUG_OBJECT (sink, "signal wait");
457 GST_AUDIO_SINK_RING_BUFFER_SIGNAL (buf);
459 GST_OBJECT_UNLOCK (buf);
461 /* join the thread */
462 g_thread_join (sink->thread);
464 GST_OBJECT_LOCK (buf);
472 GST_ERROR_OBJECT (sink, "could not create thread %s", error->message);
474 GST_ERROR_OBJECT (sink, "could not create thread for unknown reason");
479 /* function is called with LOCK */
481 gst_audio_sink_ring_buffer_release (GstAudioRingBuffer * buf)
484 GstAudioSinkClass *csink;
485 gboolean result = FALSE;
487 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
488 csink = GST_AUDIO_SINK_GET_CLASS (sink);
490 /* free the buffer */
491 g_free (buf->memory);
494 if (csink->unprepare)
495 result = csink->unprepare (sink);
498 goto could_not_unprepare;
500 GST_DEBUG_OBJECT (sink, "unprepared");
506 GST_DEBUG_OBJECT (sink, "could not unprepare device");
512 gst_audio_sink_ring_buffer_start (GstAudioRingBuffer * buf)
516 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
518 GST_DEBUG_OBJECT (sink, "start, sending signal");
519 GST_AUDIO_SINK_RING_BUFFER_SIGNAL (buf);
525 gst_audio_sink_ring_buffer_pause (GstAudioRingBuffer * buf)
528 GstAudioSinkClass *csink;
530 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
531 csink = GST_AUDIO_SINK_GET_CLASS (sink);
533 /* unblock any pending writes to the audio device */
535 GST_DEBUG_OBJECT (sink, "reset...");
537 GST_DEBUG_OBJECT (sink, "reset done");
544 gst_audio_sink_ring_buffer_stop (GstAudioRingBuffer * buf)
547 GstAudioSinkClass *csink;
549 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
550 csink = GST_AUDIO_SINK_GET_CLASS (sink);
552 /* unblock any pending writes to the audio device */
554 GST_DEBUG_OBJECT (sink, "reset...");
556 GST_DEBUG_OBJECT (sink, "reset done");
560 GST_DEBUG_OBJECT (sink, "stop, waiting...");
561 GST_AUDIO_SINK_RING_BUFFER_WAIT (buf);
562 GST_DEBUG_OBJECT (sink, "stopped");
570 gst_audio_sink_ring_buffer_delay (GstAudioRingBuffer * buf)
573 GstAudioSinkClass *csink;
576 sink = GST_AUDIO_SINK (GST_OBJECT_PARENT (buf));
577 csink = GST_AUDIO_SINK_GET_CLASS (sink);
580 res = csink->delay (sink);
585 /* AudioSink signals and args */
598 GST_DEBUG_CATEGORY_INIT (gst_audio_sink_debug, "audiosink", 0, "audiosink element");
599 #define gst_audio_sink_parent_class parent_class
600 G_DEFINE_TYPE_WITH_CODE (GstAudioSink, gst_audio_sink,
601 GST_TYPE_AUDIO_BASE_SINK, _do_init);
603 static GstAudioRingBuffer *gst_audio_sink_create_ringbuffer (GstAudioBaseSink *
607 gst_audio_sink_class_init (GstAudioSinkClass * klass)
609 GstAudioBaseSinkClass *gstaudiobasesink_class;
611 gstaudiobasesink_class = (GstAudioBaseSinkClass *) klass;
613 gstaudiobasesink_class->create_ringbuffer =
614 GST_DEBUG_FUNCPTR (gst_audio_sink_create_ringbuffer);
616 g_type_class_ref (GST_TYPE_AUDIO_SINK_RING_BUFFER);
620 gst_audio_sink_init (GstAudioSink * audiosink)
624 static GstAudioRingBuffer *
625 gst_audio_sink_create_ringbuffer (GstAudioBaseSink * sink)
627 GstAudioRingBuffer *buffer;
629 GST_DEBUG_OBJECT (sink, "creating ringbuffer");
630 buffer = g_object_new (GST_TYPE_AUDIO_SINK_RING_BUFFER, NULL);
631 GST_DEBUG_OBJECT (sink, "created ringbuffer @%p", buffer);