-------
Seeking in GStreamer means configuring the pipeline for playback of the
-media between a certain start and stop time, called a segment.
+media between a certain start and stop time, called a segment. By default a
+pipeline will play from position 0 to the total duration of the media at a rate
+of 1.0.
-Different kinds of seeking exist:
+A seek is performed by sending a seek event to the sink elements of a
+pipeline. Sending the seek event to a bin will by default forward
+the event to all sinks in the bin.
- - immediate seeking with low latency (FLUSH seek)
- - seeking without flush, playback will start from the new
- position after all the queues are emptied with old data.
- - segment seeking with and without FLUSH, this can be used to
- implement seamless looping or NLE functionality.
+When performing a seek, the start and stop values of the segment can be
+specified as absoulte positions or relative to the currently configured
+playback segment. Note that it is not possible to seek relative to the current
+playback position.
+
+Feedback of the seek operation can be immediatly using the GST_SEEK_FLAG_FLUSH
+flag. With this flag, all pending data in the pipeline is discarded and playback
+starts from the new position immediatly.
+
+When the FLUSH flag is not set, the seek will be queued and executed as
+soon as possible, which might be after all queues are emptied.
Seeking can be performed in different formats such as time, frames
or samples.
-Seeking can be performed to an absolute position or relative to the
-currently configured segment.
+The seeking can be performed to a nearby key unit or to the exact
+(estimated) unit in the media (GST_SEEK_FLAG_KEY_UNIT).
-For seeking to work reliably, all plugins in the pipeline need to follow
-the well-defined rules in this document.
+The seeking can be performed by using an estimated target position or in an
+accurate way (GST_SEEK_FLAG_ACCURATE). For some formats this can result in
+having to scan the complete file in order to accurately find the target unit.
Non segment seeking will make the pipeline emit EOS when the configured
segment has been played.
-Segment seeking will not emit an EOS at the end of the range but will
-post a SEGMENT_DONE message on the bus. This message is posted by the
-earliest element in the pipeline, typically a demuxer. After receiving
-the message, the application can reconnect the pipeline or issue other
-seek events in the pipeline. Since the message is posted as early as
-possible in the pipeline, the application has some time to issue a new
-seek to make the transition seamless. Typically the allowed delay is
-defined by the buffer sizes of the sinks as well as the size of any
-queues in the pipeline.
+Segment seeking (using the GST_SEEK_FLAG_SEGMENT) will not emit an EOS at
+the end of the playback segment but will post a SEGMENT_DONE message on the
+bus. This message is posted by the element driving the playback in the
+pipeline, typically a demuxer. After receiving the message, the application
+can reconnect the pipeline or issue other seek events in the pipeline.
+Since the message is posted as early as possible in the pipeline, the
+application has some time to issue a new seek to make the transition seamless.
+Typically the allowed delay is defined by the buffer sizes of the sinks as well
+as the size of any queues in the pipeline.
The seek can also change the playback speed of the configured segment.
A speed of 1.0 is normal speed, 2.0 is double speed. Negative values
mean backward playback.
+When performing a seek with a playback rate different from 1.0, the
+GST_SEEK_FLAG_SKIP flag can be used to instruct decoders and demuxers that they
+are allowed to skip decoding. This can be useful when resource consumption is
+more important than accurately producing all frames.
+
Generating seeking events
-------------------------
+A seek event is created with gst_event_new_seek ().
#include "gstevent.h"
#include "gstenumtypes.h"
#include "gstutils.h"
+#include "gstquark.h"
static void gst_event_init (GTypeInstance * instance, gpointer g_class);
static void gst_event_class_init (gpointer g_class, gpointer class_data);
gdouble applied_rate, GstFormat format, gint64 start, gint64 stop,
gint64 position)
{
+ GstEvent *event;
+ GstStructure *structure;
+
g_return_val_if_fail (rate != 0.0, NULL);
g_return_val_if_fail (applied_rate != 0.0, NULL);
if (stop != -1)
g_return_val_if_fail (start <= stop, NULL);
- return gst_event_new_custom (GST_EVENT_NEWSEGMENT,
- gst_structure_new ("GstEventNewsegment",
- "update", G_TYPE_BOOLEAN, update,
- "rate", G_TYPE_DOUBLE, rate,
- "applied_rate", G_TYPE_DOUBLE, applied_rate,
- "format", GST_TYPE_FORMAT, format,
- "start", G_TYPE_INT64, start,
- "stop", G_TYPE_INT64, stop,
- "position", G_TYPE_INT64, position, NULL));
+ structure = gst_structure_empty_new ("GstEventNewsegment");
+ gst_structure_id_set (structure,
+ GST_QUARK (UPDATE), G_TYPE_BOOLEAN, update,
+ GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
+ GST_QUARK (APPLIED_RATE), G_TYPE_DOUBLE, applied_rate,
+ GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
+ GST_QUARK (START), G_TYPE_INT64, start,
+ GST_QUARK (STOP), G_TYPE_INT64, stop,
+ GST_QUARK (POSITION), G_TYPE_INT64, position, NULL);
+ event = gst_event_new_custom (GST_EVENT_NEWSEGMENT, structure);
+
+ return event;
}
/**
structure = gst_event_get_structure (event);
if (G_LIKELY (update))
*update =
- g_value_get_boolean (gst_structure_get_value (structure, "update"));
+ g_value_get_boolean (gst_structure_id_get_value (structure,
+ GST_QUARK (UPDATE)));
if (G_LIKELY (rate))
- *rate = g_value_get_double (gst_structure_get_value (structure, "rate"));
+ *rate =
+ g_value_get_double (gst_structure_id_get_value (structure,
+ GST_QUARK (RATE)));
if (G_LIKELY (applied_rate))
*applied_rate =
- g_value_get_double (gst_structure_get_value (structure,
- "applied_rate"));
+ g_value_get_double (gst_structure_id_get_value (structure,
+ GST_QUARK (APPLIED_RATE)));
if (G_LIKELY (format))
- *format = g_value_get_enum (gst_structure_get_value (structure, "format"));
+ *format =
+ g_value_get_enum (gst_structure_id_get_value (structure,
+ GST_QUARK (FORMAT)));
if (G_LIKELY (start))
- *start = g_value_get_int64 (gst_structure_get_value (structure, "start"));
+ *start =
+ g_value_get_int64 (gst_structure_id_get_value (structure,
+ GST_QUARK (START)));
if (G_LIKELY (stop))
- *stop = g_value_get_int64 (gst_structure_get_value (structure, "stop"));
+ *stop =
+ g_value_get_int64 (gst_structure_id_get_value (structure,
+ GST_QUARK (STOP)));
if (G_LIKELY (position))
*position =
- g_value_get_int64 (gst_structure_get_value (structure, "position"));
+ g_value_get_int64 (gst_structure_id_get_value (structure,
+ GST_QUARK (POSITION)));
}
/**
gst_event_new_buffer_size (GstFormat format, gint64 minsize,
gint64 maxsize, gboolean async)
{
+ GstEvent *event;
+ GstStructure *structure;
+
GST_CAT_INFO (GST_CAT_EVENT,
"creating buffersize format %s, minsize %" G_GINT64_FORMAT
", maxsize %" G_GINT64_FORMAT ", async %d", gst_format_get_name (format),
minsize, maxsize, async);
- return gst_event_new_custom (GST_EVENT_BUFFERSIZE,
- gst_structure_new ("GstEventBufferSize",
- "format", GST_TYPE_FORMAT, format,
- "minsize", G_TYPE_INT64, minsize,
- "maxsize", G_TYPE_INT64, maxsize,
- "async", G_TYPE_BOOLEAN, async, NULL));
+ structure = gst_structure_empty_new ("GstEventBufferSize");
+ gst_structure_id_set (structure,
+ GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
+ GST_QUARK (MINSIZE), G_TYPE_INT64, minsize,
+ GST_QUARK (MAXSIZE), G_TYPE_INT64, maxsize,
+ GST_QUARK (ASYNC), G_TYPE_BOOLEAN, async, NULL);
+ event = gst_event_new_custom (GST_EVENT_BUFFERSIZE, structure);
+
+ return event;
}
/**
structure = gst_event_get_structure (event);
if (format)
- *format = g_value_get_enum (gst_structure_get_value (structure, "format"));
+ *format =
+ g_value_get_enum (gst_structure_id_get_value (structure,
+ GST_QUARK (FORMAT)));
if (minsize)
*minsize =
- g_value_get_int64 (gst_structure_get_value (structure, "minsize"));
+ g_value_get_int64 (gst_structure_id_get_value (structure,
+ GST_QUARK (MINSIZE)));
if (maxsize)
*maxsize =
- g_value_get_int64 (gst_structure_get_value (structure, "maxsize"));
+ g_value_get_int64 (gst_structure_id_get_value (structure,
+ GST_QUARK (MAXSIZE)));
if (async)
- *async = g_value_get_boolean (gst_structure_get_value (structure, "async"));
+ *async =
+ g_value_get_boolean (gst_structure_id_get_value (structure,
+ GST_QUARK (ASYNC)));
}
/**
gst_event_new_qos (gdouble proportion, GstClockTimeDiff diff,
GstClockTime timestamp)
{
+ GstEvent *event;
+ GstStructure *structure;
+
/* diff must be positive or timestamp + diff must be positive */
g_return_val_if_fail (diff >= 0 || -diff <= timestamp, NULL);
", timestamp %" GST_TIME_FORMAT, proportion,
diff, GST_TIME_ARGS (timestamp));
- return gst_event_new_custom (GST_EVENT_QOS,
- gst_structure_new ("GstEventQOS",
- "proportion", G_TYPE_DOUBLE, proportion,
- "diff", G_TYPE_INT64, diff,
- "timestamp", G_TYPE_UINT64, timestamp, NULL));
+ structure = gst_structure_empty_new ("GstEventQOS");
+ gst_structure_id_set (structure,
+ GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
+ GST_QUARK (DIFF), G_TYPE_INT64, diff,
+ GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp, NULL);
+ event = gst_event_new_custom (GST_EVENT_QOS, structure);
+
+ return event;
}
/**
structure = gst_event_get_structure (event);
if (proportion)
*proportion =
- g_value_get_double (gst_structure_get_value (structure, "proportion"));
+ g_value_get_double (gst_structure_id_get_value (structure,
+ GST_QUARK (PROPORTION)));
if (diff)
- *diff = g_value_get_int64 (gst_structure_get_value (structure, "diff"));
+ *diff =
+ g_value_get_int64 (gst_structure_id_get_value (structure,
+ GST_QUARK (DIFF)));
if (timestamp)
*timestamp =
- g_value_get_uint64 (gst_structure_get_value (structure, "timestamp"));
+ g_value_get_uint64 (gst_structure_id_get_value (structure,
+ GST_QUARK (TIMESTAMP)));
}
/**
* configured playback segment can be queried with #GST_QUERY_SEGMENT.
*
* @start_type and @stop_type specify how to adjust the currently configured
- * start and stop fields in @segment. Adjustments can be made relative or
- * absolute to the last configured values. A type of #GST_SEEK_TYPE_NONE means
- * that the position should not be updated.
+ * start and stop fields in playback segment. Adjustments can be made relative
+ * or absolute to the last configured values. A type of #GST_SEEK_TYPE_NONE
+ * means that the position should not be updated.
*
* When the rate is positive and @start has been updated, playback will start
* from the newly configured start position.
* It is not possible to seek relative to the current playback position, to do
* this, PAUSE the pipeline, query the current playback position with
* #GST_QUERY_POSITION and update the playback segment current position with a
- * #GST_SEEK_TYPE_SET to the desired position.
+ * #GST_SEEK_TYPE_SET to the desired position.
*
* Returns: A new seek event.
*/
gst_event_new_seek (gdouble rate, GstFormat format, GstSeekFlags flags,
GstSeekType start_type, gint64 start, GstSeekType stop_type, gint64 stop)
{
+ GstEvent *event;
+ GstStructure *structure;
+
g_return_val_if_fail (rate != 0.0, NULL);
if (format == GST_FORMAT_TIME) {
stop);
}
- return gst_event_new_custom (GST_EVENT_SEEK,
- gst_structure_new ("GstEventSeek", "rate", G_TYPE_DOUBLE, rate,
- "format", GST_TYPE_FORMAT, format,
- "flags", GST_TYPE_SEEK_FLAGS, flags,
- "cur_type", GST_TYPE_SEEK_TYPE, start_type,
- "cur", G_TYPE_INT64, start,
- "stop_type", GST_TYPE_SEEK_TYPE, stop_type,
- "stop", G_TYPE_INT64, stop, NULL));
+ structure = gst_structure_empty_new ("GstEventSeek");
+ gst_structure_id_set (structure,
+ GST_QUARK (RATE), G_TYPE_DOUBLE, rate,
+ GST_QUARK (FORMAT), GST_TYPE_FORMAT, format,
+ GST_QUARK (FLAGS), GST_TYPE_SEEK_FLAGS, flags,
+ GST_QUARK (CUR_TYPE), GST_TYPE_SEEK_TYPE, start_type,
+ GST_QUARK (CUR), G_TYPE_INT64, start,
+ GST_QUARK (STOP_TYPE), GST_TYPE_SEEK_TYPE, stop_type,
+ GST_QUARK (STOP), G_TYPE_INT64, stop, NULL);
+ event = gst_event_new_custom (GST_EVENT_SEEK, structure);
+
+ return event;
}
/**
structure = gst_event_get_structure (event);
if (rate)
- *rate = g_value_get_double (gst_structure_get_value (structure, "rate"));
+ *rate =
+ g_value_get_double (gst_structure_id_get_value (structure,
+ GST_QUARK (RATE)));
if (format)
- *format = g_value_get_enum (gst_structure_get_value (structure, "format"));
+ *format =
+ g_value_get_enum (gst_structure_id_get_value (structure,
+ GST_QUARK (FORMAT)));
if (flags)
- *flags = g_value_get_flags (gst_structure_get_value (structure, "flags"));
+ *flags =
+ g_value_get_flags (gst_structure_id_get_value (structure,
+ GST_QUARK (FLAGS)));
if (start_type)
*start_type =
- g_value_get_enum (gst_structure_get_value (structure, "cur_type"));
+ g_value_get_enum (gst_structure_id_get_value (structure,
+ GST_QUARK (CUR_TYPE)));
if (start)
- *start = g_value_get_int64 (gst_structure_get_value (structure, "cur"));
+ *start =
+ g_value_get_int64 (gst_structure_id_get_value (structure,
+ GST_QUARK (CUR)));
if (stop_type)
*stop_type =
- g_value_get_enum (gst_structure_get_value (structure, "stop_type"));
+ g_value_get_enum (gst_structure_id_get_value (structure,
+ GST_QUARK (STOP_TYPE)));
if (stop)
- *stop = g_value_get_int64 (gst_structure_get_value (structure, "stop"));
+ *stop =
+ g_value_get_int64 (gst_structure_id_get_value (structure,
+ GST_QUARK (STOP)));
}
/**
GstEvent *
gst_event_new_latency (GstClockTime latency)
{
+ GstEvent *event;
+ GstStructure *structure;
+
GST_CAT_INFO (GST_CAT_EVENT,
"creating latency event %" GST_TIME_FORMAT, GST_TIME_ARGS (latency));
- return gst_event_new_custom (GST_EVENT_LATENCY,
- gst_structure_new ("GstEventLatency",
- "latency", G_TYPE_UINT64, latency, NULL));
+ structure = gst_structure_empty_new ("GstEventLatency");
+ gst_structure_id_set (structure,
+ GST_QUARK (LATENCY), G_TYPE_UINT64, latency, NULL);
+ event = gst_event_new_custom (GST_EVENT_LATENCY, structure);
+
+ return event;
}
/**
structure = gst_event_get_structure (event);
if (latency)
*latency =
- g_value_get_uint64 (gst_structure_get_value (structure, "latency"));
+ g_value_get_uint64 (gst_structure_id_get_value (structure,
+ GST_QUARK (LATENCY)));
}
projects / platform / upstream / gstreamer.git / commitdiff