gstreamer/docs/design/part-seeking.txt

Seeking
-------

Seeking in GStreamer means configuring the pipeline for playback of the
media between a certain start and stop time, called a segment.

Different kinds of seeking exist:

 - 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.

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
current playback position.

For seeking to work reliably, all plugins in the pipeline need to follow
the well-defined rules in this document.

Non segment seeking will make the pipeline emit EOS when the configured 
playback range has been played.

Segment seeking will not emit an EOS at the end of the range but will
post a SEGMENT_STOP 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.

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.


Generating seeking events
-------------------------


The different kinds of seeking methods and their internal workings are
described below.


FLUSH seeking
-------------

This is the most common way of performing a seek in a playback application.
The application issues a seek on the pipeline and the new media is immediatly
played after the seek calls returns.


seeking without FLUSH
---------------------

This seek type is typically performed after issuing segment seeks to finish
the playback of the pipeline.


segment seeking with FLUSH
--------------------------

This seek is typically performed when starting seamless looping.


segment seeking without FLUSH
-----------------------------

This seek is typically performed when continuing seamless looping.
docs/design/: Some more docs in the works. Original commit message from CVS: * docs/design/part-dynamic.txt: * docs/design/part-events.txt: * docs/design/part-seeking.txt: Some more docs in the works. * gst/base/gstbasetransform.c: (gst_base_transform_transform_caps), (gst_base_transform_getcaps), (gst_base_transform_configure_caps), (gst_base_transform_setcaps), (gst_base_transform_get_size), (gst_base_transform_buffer_alloc), (gst_base_transform_event), (gst_base_transform_handle_buffer), (gst_base_transform_sink_activate_push), (gst_base_transform_src_activate_pull), (gst_base_transform_set_passthrough), (gst_base_transform_is_passthrough): Refcounting fixes. * gst/gstbus.c: (gst_bus_source_dispatch), (gst_bus_poll): Cleanups. * gst/gstevent.c: (gst_event_finalize): Set SRC to NULL. * gst/gstutils.c: (gst_element_unlink), (gst_pad_get_parent_element), (gst_pad_proxy_getcaps), (gst_pad_proxy_setcaps): * gst/gstutils.h: Add _get_parent_element() to get a pads parent as an element. 2005-07-18 08:28:48 +00:00			`Seeking`
			`-------`

			`Seeking in GStreamer means configuring the pipeline for playback of the`
docs/design/part-seeking.txt: Some small additions. Original commit message from CVS: * docs/design/part-seeking.txt: Some small additions. * gst/base/gstbasesink.c: (gst_base_sink_handle_object), (gst_base_sink_get_times), (gst_base_sink_do_sync), (gst_base_sink_activate_push), (gst_base_sink_activate_pull): * gst/base/gstbasesink.h: discont values are gint64, handle the math correctly. * gst/base/gstbasesrc.c: (gst_base_src_loop): Make the basesrc report error if the source pad is not linked. * gst/gstqueue.c: (gst_queue_link_src), (gst_queue_chain), (gst_queue_loop), (gst_queue_handle_src_query), (gst_queue_src_activate_push): Make queue collect data even if the srcpad is not linked. Start pushing out data as soon as it is linked. * gst/gstutils.c: (gst_element_unlink), (gst_flow_get_name): * gst/gstutils.h: Added gst_flow_get_name() to ease error reporting. 2005-07-21 17:22:13 +00:00			`media between a certain start and stop time, called a segment.`
docs/design/: Some more docs in the works. Original commit message from CVS: * docs/design/part-dynamic.txt: * docs/design/part-events.txt: * docs/design/part-seeking.txt: Some more docs in the works. * gst/base/gstbasetransform.c: (gst_base_transform_transform_caps), (gst_base_transform_getcaps), (gst_base_transform_configure_caps), (gst_base_transform_setcaps), (gst_base_transform_get_size), (gst_base_transform_buffer_alloc), (gst_base_transform_event), (gst_base_transform_handle_buffer), (gst_base_transform_sink_activate_push), (gst_base_transform_src_activate_pull), (gst_base_transform_set_passthrough), (gst_base_transform_is_passthrough): Refcounting fixes. * gst/gstbus.c: (gst_bus_source_dispatch), (gst_bus_poll): Cleanups. * gst/gstevent.c: (gst_event_finalize): Set SRC to NULL. * gst/gstutils.c: (gst_element_unlink), (gst_pad_get_parent_element), (gst_pad_proxy_getcaps), (gst_pad_proxy_setcaps): * gst/gstutils.h: Add _get_parent_element() to get a pads parent as an element. 2005-07-18 08:28:48 +00:00
			`Different kinds of seeking exist:`

check/: I wrote a test! Original commit message from CVS: * check/Makefile.am: * check/gst/gstevents.c: (GST_START_TEST), (event_probe), (test_event), (timediff), (gstevents_suite), (main): I wrote a test! * docs/design/part-seeking.txt: Spelling correction * docs/gst/tmpl/gstevent.sgml: Docs updates. * gst/base/gstbasesink.c: (gst_base_sink_handle_object): Treat a buffer-without-newsegment the same as a receiving a newsegment not in time format, and disable syncing to the clock with a warning. * gst/gstbus.c: (gst_bus_set_sync_handler): Assert if anyone tries to replace the existing sync_handler for bus, as only the owner should be setting it. * gst/gstevent.h: Have a fixed set of custom event enums with events identified by their structure name (as in 0.8), rather than a free-for-all allowing collisions between enum values from different plugins. * gst/gstpad.c: (gst_pad_class_init): Docs change. * gst/gstqueue.c: (gst_queue_handle_sink_event): Handle out-of-band downstream events from the sending thread. 2005-08-18 15:31:28 +00:00			`- immediate seeking with low latency (FLUSH seek)`
docs/design/: Some more docs in the works. Original commit message from CVS: * docs/design/part-dynamic.txt: * docs/design/part-events.txt: * docs/design/part-seeking.txt: Some more docs in the works. * gst/base/gstbasetransform.c: (gst_base_transform_transform_caps), (gst_base_transform_getcaps), (gst_base_transform_configure_caps), (gst_base_transform_setcaps), (gst_base_transform_get_size), (gst_base_transform_buffer_alloc), (gst_base_transform_event), (gst_base_transform_handle_buffer), (gst_base_transform_sink_activate_push), (gst_base_transform_src_activate_pull), (gst_base_transform_set_passthrough), (gst_base_transform_is_passthrough): Refcounting fixes. * gst/gstbus.c: (gst_bus_source_dispatch), (gst_bus_poll): Cleanups. * gst/gstevent.c: (gst_event_finalize): Set SRC to NULL. * gst/gstutils.c: (gst_element_unlink), (gst_pad_get_parent_element), (gst_pad_proxy_getcaps), (gst_pad_proxy_setcaps): * gst/gstutils.h: Add _get_parent_element() to get a pads parent as an element. 2005-07-18 08:28:48 +00:00			`- 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.`

			`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`
			`current playback position.`

			`For seeking to work reliably, all plugins in the pipeline need to follow`
			`the well-defined rules in this document.`

			`Non segment seeking will make the pipeline emit EOS when the configured`
			`playback range has been played.`

			`Segment seeking will not emit an EOS at the end of the range but will`
			`post a SEGMENT_STOP 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.`

docs/design/part-seeking.txt: Some small additions. Original commit message from CVS: * docs/design/part-seeking.txt: Some small additions. * gst/base/gstbasesink.c: (gst_base_sink_handle_object), (gst_base_sink_get_times), (gst_base_sink_do_sync), (gst_base_sink_activate_push), (gst_base_sink_activate_pull): * gst/base/gstbasesink.h: discont values are gint64, handle the math correctly. * gst/base/gstbasesrc.c: (gst_base_src_loop): Make the basesrc report error if the source pad is not linked. * gst/gstqueue.c: (gst_queue_link_src), (gst_queue_chain), (gst_queue_loop), (gst_queue_handle_src_query), (gst_queue_src_activate_push): Make queue collect data even if the srcpad is not linked. Start pushing out data as soon as it is linked. * gst/gstutils.c: (gst_element_unlink), (gst_flow_get_name): * gst/gstutils.h: Added gst_flow_get_name() to ease error reporting. 2005-07-21 17:22:13 +00:00			`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.`

docs/design/: Some more docs in the works. Original commit message from CVS: * docs/design/part-dynamic.txt: * docs/design/part-events.txt: * docs/design/part-seeking.txt: Some more docs in the works. * gst/base/gstbasetransform.c: (gst_base_transform_transform_caps), (gst_base_transform_getcaps), (gst_base_transform_configure_caps), (gst_base_transform_setcaps), (gst_base_transform_get_size), (gst_base_transform_buffer_alloc), (gst_base_transform_event), (gst_base_transform_handle_buffer), (gst_base_transform_sink_activate_push), (gst_base_transform_src_activate_pull), (gst_base_transform_set_passthrough), (gst_base_transform_is_passthrough): Refcounting fixes. * gst/gstbus.c: (gst_bus_source_dispatch), (gst_bus_poll): Cleanups. * gst/gstevent.c: (gst_event_finalize): Set SRC to NULL. * gst/gstutils.c: (gst_element_unlink), (gst_pad_get_parent_element), (gst_pad_proxy_getcaps), (gst_pad_proxy_setcaps): * gst/gstutils.h: Add _get_parent_element() to get a pads parent as an element. 2005-07-18 08:28:48 +00:00
			`Generating seeking events`
			`-------------------------`





			`The different kinds of seeking methods and their internal workings are`
			`described below.`


			`FLUSH seeking`
			`-------------`

			`This is the most common way of performing a seek in a playback application.`
			`The application issues a seek on the pipeline and the new media is immediatly`
			`played after the seek calls returns.`


			`seeking without FLUSH`
			`---------------------`

			`This seek type is typically performed after issuing segment seeks to finish`
			`the playback of the pipeline.`


			`segment seeking with FLUSH`
			`--------------------------`

			`This seek is typically performed when starting seamless looping.`


			`segment seeking without FLUSH`
			`-----------------------------`

			`This seek is typically performed when continuing seamless looping.`