2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2004,2005 Wim Taymans <wim@fluendo.com>
5 * gstpipeline.c: Overall pipeline management element
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 * @short_description: Top-level bin with clocking and bus management
28 * @see_also: #GstElement, #GstBin, #GstClock, #GstBus
30 * A #GstPipeline is a special #GstBin used as the toplevel container for
31 * the filter graph. The #GstPipeline will manage the selection and
32 * distribution of a global #GstClock as well as provide a #GstBus to the
35 * gst_pipeline_new() is used to create a pipeline. when you are done with
36 * the pipeline, use gst_object_unref() to free its resources including all
37 * added #GstElement objects (if not otherwise referenced).
39 * Elements are added and removed from the pipeline using the #GstBin
40 * methods like gst_bin_add() and gst_bin_remove() (see #GstBin).
42 * Before changing the state of the #GstPipeline (see #GstElement) a #GstBus
43 * should be retrieved with gst_pipeline_get_bus(). This #GstBus should then
44 * be used to receive #GstMessage from the elements in the pipeline. Listening
45 * to the #GstBus is necessary for retrieving error messages from the
46 * #GstPipeline and otherwise the #GstPipeline might stop without any
47 * indication, why. Furthermore, the #GstPipeline posts messages even if
48 * nobody listens on the #GstBus, which will pile up and use up memory.
50 * By default, a #GstPipeline will automatically flush the pending #GstBus
51 * messages when going to the NULL state to ensure that no circular
52 * references exist when no messages are read from the #GstBus. This
53 * behaviour can be changed with gst_pipeline_set_auto_flush_bus().
55 * When the #GstPipeline performs the PAUSED to PLAYING state change it will
56 * select a clock for the elements. The clock selection algorithm will by
57 * default select a clock provided by an element that is most upstream
58 * (closest to the source). For live pipelines (ones that return
59 * #GST_STATE_CHANGE_NO_PREROLL from the gst_element_set_state() call) this
60 * will select the clock provided by the live source. For normal pipelines
61 * this will select a clock provided by the sinks (most likely the audio
62 * sink). If no element provides a clock, a default #GstSystemClock is used.
64 * The clock selection can be controlled with the gst_pipeline_use_clock()
65 * method, which will enforce a given clock on the pipeline. With
66 * gst_pipeline_auto_clock() the default clock selection algorithm can be
69 * A #GstPipeline maintains a running time for the elements. The running
70 * time is defined as the difference between the current clock time and
71 * the base time. When the pipeline goes to READY or a flushing seek is
72 * performed on it, the running time is reset to 0. When the pipeline is
73 * set from PLAYING to PAUSED, the current clock time is sampled and used to
74 * configure the base time for the elements when the pipeline is set
75 * to PLAYING again. The effect is that the running time (as the difference
76 * between the clock time and the base time) will count how much time was spent
77 * in the PLAYING state. This default behaviour can be changed with the
78 * gst_element_set_start_time() method.
81 #include "gst_private.h"
83 #include "gst-i18n-lib.h"
85 #include "gstpipeline.h"
87 #include "gstsystemclock.h"
90 GST_DEBUG_CATEGORY_STATIC (pipeline_debug);
91 #define GST_CAT_DEFAULT pipeline_debug
93 /* Pipeline signals and args */
100 #define DEFAULT_DELAY 0
101 #define DEFAULT_AUTO_FLUSH_BUS TRUE
102 #define DEFAULT_LATENCY GST_CLOCK_TIME_NONE
112 struct _GstPipelinePrivate
115 gboolean auto_flush_bus;
118 /* when we need to update stream_time or clock when going back to
120 GstClockTime last_start_time;
121 gboolean update_clock;
123 GstClockTime latency;
125 /* seqnum of the most recent instant-rate-request, %GST_SEQNUM_INVALID if none */
126 guint32 instant_rate_seqnum;
127 gdouble active_instant_rate;
128 GstClockTime instant_rate_upstream_anchor;
129 GstClockTime instant_rate_clock_anchor;
133 static void gst_pipeline_dispose (GObject * object);
134 static void gst_pipeline_set_property (GObject * object, guint prop_id,
135 const GValue * value, GParamSpec * pspec);
136 static void gst_pipeline_get_property (GObject * object, guint prop_id,
137 GValue * value, GParamSpec * pspec);
139 static GstClock *gst_pipeline_provide_clock_func (GstElement * element);
140 static GstStateChangeReturn gst_pipeline_change_state (GstElement * element,
141 GstStateChange transition);
143 static void gst_pipeline_handle_message (GstBin * bin, GstMessage * message);
144 static gboolean gst_pipeline_do_latency (GstBin * bin);
145 static gboolean gst_pipeline_handle_instant_rate (GstPipeline * pipeline,
146 gdouble rate, guint32 seqnum);
148 /* static guint gst_pipeline_signals[LAST_SIGNAL] = { 0 }; */
152 GST_DEBUG_CATEGORY_INIT (pipeline_debug, "pipeline", GST_DEBUG_BOLD, \
153 "debugging info for the 'pipeline' container element"); \
156 #define gst_pipeline_parent_class parent_class
157 G_DEFINE_TYPE_WITH_CODE (GstPipeline, gst_pipeline, GST_TYPE_BIN,
158 G_ADD_PRIVATE (GstPipeline) _do_init);
161 gst_pipeline_class_init (GstPipelineClass * klass)
163 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
164 GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
165 GstBinClass *gstbin_class = GST_BIN_CLASS (klass);
167 gobject_class->set_property = gst_pipeline_set_property;
168 gobject_class->get_property = gst_pipeline_get_property;
173 * The expected delay needed for elements to spin up to the
174 * PLAYING state expressed in nanoseconds.
175 * see gst_pipeline_set_delay() for more information on this option.
177 g_object_class_install_property (gobject_class, PROP_DELAY,
178 g_param_spec_uint64 ("delay", "Delay",
179 "Expected delay needed for elements "
180 "to spin up to PLAYING in nanoseconds", 0, G_MAXUINT64, DEFAULT_DELAY,
181 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
184 * GstPipeline:auto-flush-bus:
186 * Whether or not to automatically flush all messages on the
187 * pipeline's bus when going from READY to NULL state. Please see
188 * gst_pipeline_set_auto_flush_bus() for more information on this option.
190 g_object_class_install_property (gobject_class, PROP_AUTO_FLUSH_BUS,
191 g_param_spec_boolean ("auto-flush-bus", "Auto Flush Bus",
192 "Whether to automatically flush the pipeline's bus when going "
193 "from READY into NULL state", DEFAULT_AUTO_FLUSH_BUS,
194 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
197 * GstPipeline:latency:
199 * Latency to configure on the pipeline. See gst_pipeline_set_latency().
203 g_object_class_install_property (gobject_class, PROP_LATENCY,
204 g_param_spec_uint64 ("latency", "Latency",
205 "Latency to configure on the pipeline", 0, G_MAXUINT64,
206 DEFAULT_LATENCY, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
208 gobject_class->dispose = gst_pipeline_dispose;
210 gst_element_class_set_static_metadata (gstelement_class, "Pipeline object",
212 "Complete pipeline object",
213 "Erik Walthinsen <omega@cse.ogi.edu>, Wim Taymans <wim@fluendo.com>");
215 gstelement_class->change_state =
216 GST_DEBUG_FUNCPTR (gst_pipeline_change_state);
217 gstelement_class->provide_clock =
218 GST_DEBUG_FUNCPTR (gst_pipeline_provide_clock_func);
219 gstbin_class->handle_message =
220 GST_DEBUG_FUNCPTR (gst_pipeline_handle_message);
221 gstbin_class->do_latency = GST_DEBUG_FUNCPTR (gst_pipeline_do_latency);
225 gst_pipeline_init (GstPipeline * pipeline)
229 pipeline->priv = gst_pipeline_get_instance_private (pipeline);
231 /* set default property values */
232 pipeline->priv->auto_flush_bus = DEFAULT_AUTO_FLUSH_BUS;
233 pipeline->delay = DEFAULT_DELAY;
234 pipeline->priv->latency = DEFAULT_LATENCY;
236 pipeline->priv->is_live = FALSE;
238 /* create and set a default bus */
239 bus = gst_bus_new ();
241 /* FIXME, disabled for 0.10.5 release as it caused to many regressions */
242 /* Start our bus in flushing if appropriate */
243 if (pipeline->priv->auto_flush_bus)
244 gst_bus_set_flushing (bus, TRUE);
247 gst_element_set_bus (GST_ELEMENT_CAST (pipeline), bus);
248 GST_DEBUG_OBJECT (pipeline, "set bus %" GST_PTR_FORMAT " on pipeline", bus);
249 gst_object_unref (bus);
253 gst_pipeline_dispose (GObject * object)
255 GstPipeline *pipeline = GST_PIPELINE (object);
256 GstClock **clock_p = &pipeline->fixed_clock;
258 GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, pipeline, "%p dispose", pipeline);
260 /* clear and unref any fixed clock */
261 gst_object_replace ((GstObject **) clock_p, NULL);
263 G_OBJECT_CLASS (parent_class)->dispose (object);
267 gst_pipeline_set_property (GObject * object, guint prop_id,
268 const GValue * value, GParamSpec * pspec)
270 GstPipeline *pipeline = GST_PIPELINE (object);
274 gst_pipeline_set_delay (pipeline, g_value_get_uint64 (value));
276 case PROP_AUTO_FLUSH_BUS:
277 gst_pipeline_set_auto_flush_bus (pipeline, g_value_get_boolean (value));
280 gst_pipeline_set_latency (pipeline, g_value_get_uint64 (value));
283 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
289 gst_pipeline_get_property (GObject * object, guint prop_id,
290 GValue * value, GParamSpec * pspec)
292 GstPipeline *pipeline = GST_PIPELINE (object);
296 g_value_set_uint64 (value, gst_pipeline_get_delay (pipeline));
298 case PROP_AUTO_FLUSH_BUS:
299 g_value_set_boolean (value, gst_pipeline_get_auto_flush_bus (pipeline));
302 g_value_set_uint64 (value, gst_pipeline_get_latency (pipeline));
305 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
310 /* set the start_time to 0, this will cause us to select a new base_time and
311 * make the running_time start from 0 again. */
313 reset_start_time (GstPipeline * pipeline, GstClockTime start_time)
315 GST_OBJECT_LOCK (pipeline);
316 if (GST_ELEMENT_START_TIME (pipeline) != GST_CLOCK_TIME_NONE) {
317 GST_DEBUG_OBJECT (pipeline, "reset start_time to 0");
318 GST_ELEMENT_START_TIME (pipeline) = start_time;
319 pipeline->priv->last_start_time = -1;
321 /* Reset instant rate multiplier because we flushed / reset time.
322 * Old anchor's don't make sense */
323 pipeline->priv->instant_rate_seqnum = GST_SEQNUM_INVALID;
324 pipeline->priv->instant_rate_upstream_anchor =
325 pipeline->priv->instant_rate_clock_anchor = GST_CLOCK_TIME_NONE;
326 pipeline->priv->active_instant_rate = 1.0;
327 GST_DEBUG_OBJECT (pipeline, "Reset start time to %" GST_TIME_FORMAT,
328 GST_TIME_ARGS (start_time));
330 GST_DEBUG_OBJECT (pipeline, "application asked to not reset stream_time");
332 GST_OBJECT_UNLOCK (pipeline);
337 * @name: (allow-none): name of new pipeline
339 * Create a new pipeline with the given name.
341 * Returns: (transfer floating): newly created GstPipeline
346 gst_pipeline_new (const gchar * name)
348 return gst_element_factory_make ("pipeline", name);
351 /* takes a snapshot of the running_time of the pipeline and store this as the
352 * element start_time. This is the time we will set as the running_time of the
353 * pipeline when we go to PLAYING next. */
355 pipeline_update_start_time (GstElement * element)
357 GstPipeline *pipeline = GST_PIPELINE_CAST (element);
360 GST_OBJECT_LOCK (element);
361 if ((clock = element->clock)) {
364 gst_object_ref (clock);
365 GST_OBJECT_UNLOCK (element);
367 /* calculate the time when we stopped */
368 now = gst_clock_get_time (clock);
369 gst_object_unref (clock);
371 GST_OBJECT_LOCK (element);
372 /* store the current running time */
373 if (GST_ELEMENT_START_TIME (pipeline) != GST_CLOCK_TIME_NONE) {
374 if (now != GST_CLOCK_TIME_NONE)
375 GST_ELEMENT_START_TIME (pipeline) = now - element->base_time;
377 GST_WARNING_OBJECT (element,
378 "Clock %s returned invalid time, can't calculate "
379 "running_time when going to the PAUSED state",
380 GST_OBJECT_NAME (clock));
382 /* we went to PAUSED, when going to PLAYING select clock and new
384 pipeline->priv->update_clock = TRUE;
386 GST_DEBUG_OBJECT (element,
387 "start_time=%" GST_TIME_FORMAT ", now=%" GST_TIME_FORMAT
388 ", base_time %" GST_TIME_FORMAT,
389 GST_TIME_ARGS (GST_ELEMENT_START_TIME (pipeline)),
390 GST_TIME_ARGS (now), GST_TIME_ARGS (element->base_time));
392 GST_OBJECT_UNLOCK (element);
396 static GstStateChangeReturn
397 gst_pipeline_change_state (GstElement * element, GstStateChange transition)
399 GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
400 GstPipeline *pipeline = GST_PIPELINE_CAST (element);
403 switch (transition) {
404 case GST_STATE_CHANGE_NULL_TO_NULL:
406 case GST_STATE_CHANGE_READY_TO_READY:
408 case GST_STATE_CHANGE_PAUSED_TO_PAUSED:
410 case GST_STATE_CHANGE_PLAYING_TO_PLAYING:
412 case GST_STATE_CHANGE_NULL_TO_READY:
413 GST_OBJECT_LOCK (element);
415 gst_bus_set_flushing (element->bus, FALSE);
416 GST_OBJECT_UNLOCK (element);
418 case GST_STATE_CHANGE_READY_TO_PAUSED:
419 GST_OBJECT_LOCK (element);
420 pipeline->priv->update_clock = TRUE;
421 GST_OBJECT_UNLOCK (element);
423 /* READY to PAUSED starts running_time from 0 */
424 reset_start_time (pipeline, 0);
426 case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
428 GstClockTime now, start_time, last_start_time, delay;
429 gboolean update_clock;
432 GST_DEBUG_OBJECT (element, "selecting clock and base_time");
434 GST_OBJECT_LOCK (element);
435 cur_clock = element->clock;
437 gst_object_ref (cur_clock);
438 /* get the desired running_time of the first buffer aka the start_time */
439 start_time = GST_ELEMENT_START_TIME (pipeline);
440 last_start_time = pipeline->priv->last_start_time;
441 pipeline->priv->last_start_time = start_time;
442 /* see if we need to update the clock */
443 update_clock = pipeline->priv->update_clock;
444 pipeline->priv->update_clock = FALSE;
445 delay = pipeline->delay;
446 GST_OBJECT_UNLOCK (element);
448 /* running time changed, either with a PAUSED or a flush, we need to check
449 * if there is a new clock & update the base time */
450 /* only do this for top-level, however */
451 if (GST_OBJECT_PARENT (element) == NULL &&
452 (update_clock || last_start_time != start_time)) {
453 GST_DEBUG_OBJECT (pipeline, "Need to update start_time");
455 /* when going to PLAYING, select a clock when needed. If we just got
456 * flushed, we don't reselect the clock. */
458 GST_DEBUG_OBJECT (pipeline, "Need to update clock.");
459 clock = gst_element_provide_clock (element);
461 GST_DEBUG_OBJECT (pipeline,
462 "Don't need to update clock, using old clock.");
463 /* only try to ref if cur_clock is not NULL */
465 gst_object_ref (cur_clock);
470 now = gst_clock_get_time (clock);
472 GST_DEBUG_OBJECT (pipeline, "no clock, using base time of NONE");
473 now = GST_CLOCK_TIME_NONE;
476 if (clock != cur_clock) {
477 /* now distribute the clock (which could be NULL). If some
478 * element refuses the clock, this will return FALSE and
479 * we effectively fail the state change. */
480 if (!gst_element_set_clock (element, clock))
483 /* if we selected and distributed a new clock, let the app
485 gst_element_post_message (element,
486 gst_message_new_new_clock (GST_OBJECT_CAST (element), clock));
490 gst_object_unref (clock);
492 if (start_time != GST_CLOCK_TIME_NONE && now != GST_CLOCK_TIME_NONE) {
493 GstClockTime new_base_time = now - start_time + delay;
494 GST_DEBUG_OBJECT (element,
495 "start_time=%" GST_TIME_FORMAT ", now=%" GST_TIME_FORMAT
496 ", base_time %" GST_TIME_FORMAT,
497 GST_TIME_ARGS (start_time), GST_TIME_ARGS (now),
498 GST_TIME_ARGS (new_base_time));
500 gst_element_set_base_time (element, new_base_time);
502 GST_DEBUG_OBJECT (pipeline,
503 "NOT adjusting base_time because start_time is NONE");
506 GST_DEBUG_OBJECT (pipeline,
507 "NOT adjusting base_time because we selected one before");
511 gst_object_unref (cur_clock);
514 case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
516 /* we take a start_time snapshot before calling the children state changes
517 * so that they know about when the pipeline PAUSED. */
518 pipeline_update_start_time (element);
521 case GST_STATE_CHANGE_PAUSED_TO_READY:
522 pipeline->priv->is_live = FALSE;
523 reset_start_time (pipeline, 0);
525 case GST_STATE_CHANGE_READY_TO_NULL:
529 result = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);
531 if (GST_STATE_TRANSITION_NEXT (transition) == GST_STATE_PAUSED) {
532 pipeline->priv->is_live = result == GST_STATE_CHANGE_NO_PREROLL;
533 GST_INFO_OBJECT (pipeline, "pipeline is%slive",
534 pipeline->priv->is_live ? " " : " not ");
537 switch (transition) {
538 case GST_STATE_CHANGE_NULL_TO_NULL:
540 case GST_STATE_CHANGE_READY_TO_READY:
542 case GST_STATE_CHANGE_PAUSED_TO_PAUSED:
544 case GST_STATE_CHANGE_PLAYING_TO_PLAYING:
546 case GST_STATE_CHANGE_NULL_TO_READY:
548 case GST_STATE_CHANGE_READY_TO_PAUSED:
550 case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
552 case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
554 /* Take a new snapshot of the start_time after calling the state change on
555 * all children. This will be the running_time of the pipeline when we go
557 pipeline_update_start_time (element);
560 case GST_STATE_CHANGE_PAUSED_TO_READY:
562 case GST_STATE_CHANGE_READY_TO_NULL:
567 /* grab some stuff before we release the lock to flush out the bus */
568 GST_OBJECT_LOCK (element);
569 if ((bus = element->bus))
570 gst_object_ref (bus);
571 auto_flush = pipeline->priv->auto_flush_bus;
572 GST_OBJECT_UNLOCK (element);
576 gst_bus_set_flushing (bus, TRUE);
578 GST_INFO_OBJECT (element, "not flushing bus, auto-flushing disabled");
580 gst_object_unref (bus);
590 /* we generate this error when the selected clock was not
591 * accepted by some element */
592 GST_ELEMENT_ERROR (pipeline, CORE, CLOCK,
593 (_("Selected clock cannot be used in pipeline.")),
594 ("Pipeline cannot operate with selected clock"));
595 GST_DEBUG_OBJECT (pipeline,
596 "Pipeline cannot operate with selected clock %p", clock);
598 gst_object_unref (clock);
599 return GST_STATE_CHANGE_FAILURE;
603 /* intercept the bus messages from our children. We watch for the ASYNC_START
604 * message with is posted by the elements (sinks) that require a reset of the
605 * running_time after a flush. ASYNC_START also brings the pipeline back into
606 * the PAUSED, pending PAUSED state. When the ASYNC_DONE message is received the
607 * pipeline will redistribute the new base_time and will bring the elements back
608 * to the desired state of the pipeline. */
609 /* GST_MESSAGE_INSTANT_RATE_REQUEST: This message is only posted by sinks and
610 * bins containing sinks (which are also considered sinks). Once all sinks
611 * have posted this message it is posted to the parent bin, or if this is
612 * a top-level bin (e.g. pipeline), a instant-rate-sync-time event with
613 * the current running time is sent to the whole pipeline.
616 gst_pipeline_handle_message (GstBin * bin, GstMessage * message)
618 GstPipeline *pipeline = GST_PIPELINE_CAST (bin);
620 switch (GST_MESSAGE_TYPE (message)) {
621 case GST_MESSAGE_RESET_TIME:
623 GstClockTime running_time;
625 gst_message_parse_reset_time (message, &running_time);
627 /* reset our running time if we need to distribute a new base_time to the
629 reset_start_time (pipeline, running_time);
631 /* If we are live, sample a new base_time immediately */
632 if (pipeline->priv->is_live
633 && GST_STATE_TARGET (pipeline) == GST_STATE_PLAYING) {
634 gst_pipeline_change_state (GST_ELEMENT (pipeline),
635 GST_STATE_CHANGE_PAUSED_TO_PLAYING);
640 case GST_MESSAGE_CLOCK_LOST:
644 gst_message_parse_clock_lost (message, &clock);
646 GST_OBJECT_LOCK (bin);
647 if (clock == GST_ELEMENT_CAST (bin)->clock) {
648 GST_DEBUG_OBJECT (bin, "Used clock '%s' got lost",
649 GST_OBJECT_NAME (clock));
650 pipeline->priv->update_clock = TRUE;
652 GST_OBJECT_UNLOCK (bin);
656 case GST_MESSAGE_INSTANT_RATE_REQUEST:{
657 guint32 seqnum = gst_message_get_seqnum (message);
658 gdouble rate_multiplier;
660 gst_message_parse_instant_rate_request (message, &rate_multiplier);
662 gst_pipeline_handle_instant_rate (pipeline, rate_multiplier, seqnum);
669 GST_BIN_CLASS (parent_class)->handle_message (bin, message);
673 gst_pipeline_do_latency (GstBin * bin)
675 GstPipeline *pipeline = GST_PIPELINE (bin);
677 GstClockTime latency;
678 GstClockTime min_latency, max_latency;
681 GST_OBJECT_LOCK (pipeline);
682 latency = pipeline->priv->latency;
683 GST_OBJECT_UNLOCK (pipeline);
685 if (latency == GST_CLOCK_TIME_NONE)
686 return GST_BIN_CLASS (parent_class)->do_latency (bin);
688 GST_DEBUG_OBJECT (pipeline, "querying latency");
690 query = gst_query_new_latency ();
691 if ((res = gst_element_query (GST_ELEMENT_CAST (pipeline), query))) {
694 gst_query_parse_latency (query, &live, &min_latency, &max_latency);
696 GST_DEBUG_OBJECT (pipeline,
697 "got min latency %" GST_TIME_FORMAT ", max latency %"
698 GST_TIME_FORMAT ", live %d", GST_TIME_ARGS (min_latency),
699 GST_TIME_ARGS (max_latency), live);
701 if (max_latency < min_latency) {
702 /* this is an impossible situation, some parts of the pipeline might not
703 * work correctly. We post a warning for now. */
704 GST_ELEMENT_WARNING (pipeline, CORE, CLOCK, (NULL),
705 ("Impossible to configure latency: max %" GST_TIME_FORMAT " < min %"
706 GST_TIME_FORMAT ". Add queues or other buffering elements.",
707 GST_TIME_ARGS (max_latency), GST_TIME_ARGS (min_latency)));
710 if (latency < min_latency) {
711 /* This is a problematic situation as we will most likely drop lots of
712 * data if we configure a too low latency */
713 GST_ELEMENT_WARNING (pipeline, CORE, CLOCK, (NULL),
714 ("Configured latency is lower than detected minimum latency: configured %"
715 GST_TIME_FORMAT " < min %" GST_TIME_FORMAT,
716 GST_TIME_ARGS (latency), GST_TIME_ARGS (min_latency)));
719 /* this is not a real problem, we just don't configure any latency. */
720 GST_WARNING_OBJECT (pipeline, "failed to query latency");
722 gst_query_unref (query);
725 /* configure latency on elements */
727 gst_element_send_event (GST_ELEMENT_CAST (pipeline),
728 gst_event_new_latency (latency));
730 GST_INFO_OBJECT (pipeline, "configured latency of %" GST_TIME_FORMAT,
731 GST_TIME_ARGS (latency));
733 GST_WARNING_OBJECT (pipeline,
734 "did not really configure latency of %" GST_TIME_FORMAT,
735 GST_TIME_ARGS (latency));
742 * gst_pipeline_get_bus:
743 * @pipeline: a #GstPipeline
745 * Gets the #GstBus of @pipeline. The bus allows applications to receive
746 * #GstMessage packets.
748 * Returns: (transfer full): a #GstBus, unref after usage.
753 gst_pipeline_get_bus (GstPipeline * pipeline)
755 return gst_element_get_bus (GST_ELEMENT_CAST (pipeline));
759 gst_pipeline_provide_clock_func (GstElement * element)
761 GstClock *clock = NULL;
762 GstPipeline *pipeline = GST_PIPELINE (element);
764 /* if we have a fixed clock, use that one */
765 GST_OBJECT_LOCK (pipeline);
766 if (GST_OBJECT_FLAG_IS_SET (pipeline, GST_PIPELINE_FLAG_FIXED_CLOCK)) {
767 clock = pipeline->fixed_clock;
769 gst_object_ref (clock);
770 GST_OBJECT_UNLOCK (pipeline);
772 GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline using fixed clock %p (%s)",
773 clock, clock ? GST_STR_NULL (GST_OBJECT_NAME (clock)) : "-");
775 GST_OBJECT_UNLOCK (pipeline);
776 /* let the parent bin select a clock */
778 GST_ELEMENT_CLASS (parent_class)->provide_clock (GST_ELEMENT
780 /* no clock, use a system clock */
782 clock = gst_system_clock_obtain ();
784 GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline obtained system clock: %p (%s)",
785 clock, clock ? GST_STR_NULL (GST_OBJECT_NAME (clock)) : "-");
787 GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline obtained clock: %p (%s)",
788 clock, clock ? GST_STR_NULL (GST_OBJECT_NAME (clock)) : "-");
795 * gst_pipeline_get_clock: (skip)
796 * @pipeline: a #GstPipeline
798 * Gets the current clock used by @pipeline. Users of object
799 * oriented languages should use gst_pipeline_get_pipeline_clock()
800 * to avoid confusion with gst_element_get_clock() which has a different behavior.
802 * Unlike gst_element_get_clock(), this function will always return a
803 * clock, even if the pipeline is not in the PLAYING state.
805 * Returns: (transfer full): a #GstClock, unref after usage.
808 gst_pipeline_get_clock (GstPipeline * pipeline)
810 return gst_pipeline_get_pipeline_clock (pipeline);
814 * gst_pipeline_get_pipeline_clock:
815 * @pipeline: a #GstPipeline
817 * Gets the current clock used by @pipeline.
819 * Unlike gst_element_get_clock(), this function will always return a
820 * clock, even if the pipeline is not in the PLAYING state.
822 * Returns: (transfer full): a #GstClock, unref after usage.
827 gst_pipeline_get_pipeline_clock (GstPipeline * pipeline)
829 g_return_val_if_fail (GST_IS_PIPELINE (pipeline), NULL);
831 return gst_pipeline_provide_clock_func (GST_ELEMENT_CAST (pipeline));
836 * gst_pipeline_use_clock:
837 * @pipeline: a #GstPipeline
838 * @clock: (transfer none) (allow-none): the clock to use
840 * Force @pipeline to use the given @clock. The pipeline will
841 * always use the given clock even if new clock providers are added
844 * If @clock is %NULL all clocking will be disabled which will make
845 * the pipeline run as fast as possible.
850 gst_pipeline_use_clock (GstPipeline * pipeline, GstClock * clock)
854 g_return_if_fail (GST_IS_PIPELINE (pipeline));
856 GST_OBJECT_LOCK (pipeline);
857 GST_OBJECT_FLAG_SET (pipeline, GST_PIPELINE_FLAG_FIXED_CLOCK);
859 clock_p = &pipeline->fixed_clock;
860 gst_object_replace ((GstObject **) clock_p, (GstObject *) clock);
861 GST_OBJECT_UNLOCK (pipeline);
863 GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline using fixed clock %p (%s)", clock,
864 (clock ? GST_OBJECT_NAME (clock) : "nil"));
868 * gst_pipeline_set_clock: (skip)
869 * @pipeline: a #GstPipeline
870 * @clock: (transfer none): the clock to set
872 * Set the clock for @pipeline. The clock will be distributed
873 * to all the elements managed by the pipeline.
875 * Returns: %TRUE if the clock could be set on the pipeline. %FALSE if
876 * some element did not accept the clock.
881 gst_pipeline_set_clock (GstPipeline * pipeline, GstClock * clock)
883 g_return_val_if_fail (pipeline != NULL, FALSE);
884 g_return_val_if_fail (GST_IS_PIPELINE (pipeline), FALSE);
887 GST_ELEMENT_CLASS (parent_class)->set_clock (GST_ELEMENT_CAST (pipeline),
892 * gst_pipeline_auto_clock:
893 * @pipeline: a #GstPipeline
895 * Let @pipeline select a clock automatically. This is the default
898 * Use this function if you previous forced a fixed clock with
899 * gst_pipeline_use_clock() and want to restore the default
900 * pipeline clock selection algorithm.
905 gst_pipeline_auto_clock (GstPipeline * pipeline)
909 g_return_if_fail (pipeline != NULL);
910 g_return_if_fail (GST_IS_PIPELINE (pipeline));
912 GST_OBJECT_LOCK (pipeline);
913 GST_OBJECT_FLAG_UNSET (pipeline, GST_PIPELINE_FLAG_FIXED_CLOCK);
915 clock_p = &pipeline->fixed_clock;
916 gst_object_replace ((GstObject **) clock_p, NULL);
917 GST_OBJECT_UNLOCK (pipeline);
919 GST_CAT_DEBUG (GST_CAT_CLOCK, "pipeline using automatic clock");
923 * gst_pipeline_set_delay:
924 * @pipeline: a #GstPipeline
927 * Set the expected delay needed for all elements to perform the
928 * PAUSED to PLAYING state change. @delay will be added to the
929 * base time of the elements so that they wait an additional @delay
930 * amount of time before starting to process buffers and cannot be
931 * #GST_CLOCK_TIME_NONE.
933 * This option is used for tuning purposes and should normally not be
939 gst_pipeline_set_delay (GstPipeline * pipeline, GstClockTime delay)
941 g_return_if_fail (GST_IS_PIPELINE (pipeline));
942 g_return_if_fail (delay != GST_CLOCK_TIME_NONE);
944 GST_OBJECT_LOCK (pipeline);
945 pipeline->delay = delay;
946 GST_OBJECT_UNLOCK (pipeline);
950 * gst_pipeline_get_delay:
951 * @pipeline: a #GstPipeline
953 * Get the configured delay (see gst_pipeline_set_delay()).
955 * Returns: The configured delay.
960 gst_pipeline_get_delay (GstPipeline * pipeline)
964 g_return_val_if_fail (GST_IS_PIPELINE (pipeline), GST_CLOCK_TIME_NONE);
966 GST_OBJECT_LOCK (pipeline);
967 res = pipeline->delay;
968 GST_OBJECT_UNLOCK (pipeline);
974 * gst_pipeline_set_auto_flush_bus:
975 * @pipeline: a #GstPipeline
976 * @auto_flush: whether or not to automatically flush the bus when
977 * the pipeline goes from READY to NULL state
979 * Usually, when a pipeline goes from READY to NULL state, it automatically
980 * flushes all pending messages on the bus, which is done for refcounting
981 * purposes, to break circular references.
983 * This means that applications that update state using (async) bus messages
984 * (e.g. do certain things when a pipeline goes from PAUSED to READY) might
985 * not get to see messages when the pipeline is shut down, because they might
986 * be flushed before they can be dispatched in the main thread. This behaviour
987 * can be disabled using this function.
989 * It is important that all messages on the bus are handled when the
990 * automatic flushing is disabled else memory leaks will be introduced.
995 gst_pipeline_set_auto_flush_bus (GstPipeline * pipeline, gboolean auto_flush)
997 g_return_if_fail (GST_IS_PIPELINE (pipeline));
999 GST_OBJECT_LOCK (pipeline);
1000 pipeline->priv->auto_flush_bus = auto_flush;
1001 GST_OBJECT_UNLOCK (pipeline);
1005 * gst_pipeline_get_auto_flush_bus:
1006 * @pipeline: a #GstPipeline
1008 * Check if @pipeline will automatically flush messages when going to
1011 * Returns: whether the pipeline will automatically flush its bus when
1012 * going from READY to NULL state or not.
1017 gst_pipeline_get_auto_flush_bus (GstPipeline * pipeline)
1021 g_return_val_if_fail (GST_IS_PIPELINE (pipeline), FALSE);
1023 GST_OBJECT_LOCK (pipeline);
1024 res = pipeline->priv->auto_flush_bus;
1025 GST_OBJECT_UNLOCK (pipeline);
1031 * gst_pipeline_set_latency:
1032 * @pipeline: a #GstPipeline
1033 * @latency: latency to configure
1035 * Sets the latency that should be configured on the pipeline. Setting
1036 * GST_CLOCK_TIME_NONE will restore the default behaviour of using the minimum
1037 * latency from the LATENCY query. Setting this is usually not required and
1038 * the pipeline will figure out an appropriate latency automatically.
1040 * Setting a too low latency, especially lower than the minimum latency from
1041 * the LATENCY query, will most likely cause the pipeline to fail.
1046 gst_pipeline_set_latency (GstPipeline * pipeline, GstClockTime latency)
1050 g_return_if_fail (GST_IS_PIPELINE (pipeline));
1052 GST_OBJECT_LOCK (pipeline);
1053 changed = (pipeline->priv->latency != latency);
1054 pipeline->priv->latency = latency;
1055 GST_OBJECT_UNLOCK (pipeline);
1058 gst_bin_recalculate_latency (GST_BIN_CAST (pipeline));
1062 * gst_pipeline_get_latency:
1063 * @pipeline: a #GstPipeline
1065 * Gets the latency that should be configured on the pipeline. See
1066 * gst_pipeline_set_latency().
1068 * Returns: Latency to configure on the pipeline or GST_CLOCK_TIME_NONE
1074 gst_pipeline_get_latency (GstPipeline * pipeline)
1076 GstClockTime latency;
1078 g_return_val_if_fail (GST_IS_PIPELINE (pipeline), GST_CLOCK_TIME_NONE);
1080 GST_OBJECT_LOCK (pipeline);
1081 latency = pipeline->priv->latency;
1082 GST_OBJECT_UNLOCK (pipeline);
1088 gst_pipeline_handle_instant_rate (GstPipeline * pipeline, gdouble rate,
1091 GstClockTime running_time = GST_CLOCK_TIME_NONE;
1092 GstClockTime upstream_running_time = GST_CLOCK_TIME_NONE;
1093 gboolean is_playing;
1096 GST_OBJECT_LOCK (pipeline);
1098 if (pipeline->priv->instant_rate_seqnum != GST_SEQNUM_INVALID &&
1099 pipeline->priv->instant_rate_seqnum == seqnum) {
1100 GST_DEBUG_OBJECT (pipeline,
1101 "Handling duplicate instant-rate-request message with seqnum %u",
1103 upstream_running_time = pipeline->priv->instant_rate_upstream_anchor;
1104 running_time = pipeline->priv->instant_rate_clock_anchor;
1106 if (G_UNLIKELY (rate != pipeline->priv->active_instant_rate)) {
1107 GST_WARNING_OBJECT (pipeline,
1108 "Repeated instant-rate-request has a different rate to before! %f != %f",
1109 rate, pipeline->priv->active_instant_rate);
1110 rate = pipeline->priv->active_instant_rate;
1113 /* Get the current running time of the pipeline */
1114 is_playing = GST_STATE (pipeline) == GST_STATE_PLAYING
1115 && (GST_STATE_PENDING (pipeline) == GST_STATE_VOID_PENDING ||
1116 GST_STATE_PENDING (pipeline) == GST_STATE_PLAYING);
1119 GstClockTime base_time, clock_time;
1122 base_time = GST_ELEMENT_CAST (pipeline)->base_time;
1123 clock = GST_ELEMENT_CLOCK (pipeline);
1126 clock_time = gst_clock_get_time (clock);
1127 running_time = clock_time - base_time;
1130 running_time = GST_ELEMENT_START_TIME (pipeline);
1133 if (!GST_CLOCK_TIME_IS_VALID (running_time)) {
1134 GST_OBJECT_UNLOCK (pipeline);
1138 if (GST_CLOCK_TIME_IS_VALID (pipeline->priv->instant_rate_upstream_anchor)) {
1139 /* Already had an override, calculate the adjustment due to that
1140 * elapsed duration */
1141 GstClockTime elapsed =
1142 running_time - pipeline->priv->instant_rate_clock_anchor;
1143 pipeline->priv->instant_rate_upstream_anchor +=
1144 elapsed * pipeline->priv->active_instant_rate;
1145 pipeline->priv->instant_rate_clock_anchor = running_time;
1147 /* Else this is the first override event */
1148 pipeline->priv->instant_rate_upstream_anchor =
1149 pipeline->priv->instant_rate_clock_anchor = running_time;
1151 upstream_running_time = pipeline->priv->instant_rate_upstream_anchor;
1153 pipeline->priv->instant_rate_seqnum = seqnum;
1154 pipeline->priv->active_instant_rate = rate;
1157 GST_OBJECT_UNLOCK (pipeline);
1159 GST_DEBUG_OBJECT (pipeline,
1160 "Instant rate multiplier to %f rt %" GST_TIME_FORMAT " upstream %"
1161 GST_TIME_FORMAT, rate, GST_TIME_ARGS (running_time),
1162 GST_TIME_ARGS (upstream_running_time));
1165 gst_event_new_instant_rate_sync_time (rate, running_time,
1166 upstream_running_time);
1167 gst_event_set_seqnum (event, seqnum);
1169 return gst_element_send_event (GST_ELEMENT_CAST (pipeline), event);