:right-sidebar: True Segment =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Segment(**kwargs) :no-contents-entry: This helper structure holds the relevant values for tracking the region of interest in a media file, called a segment. The structure can be used for two purposes: - performing seeks (handling seek events) - tracking playback regions (handling newsegment events) The segment is usually configured by the application with a seek event which is propagated upstream and eventually handled by an element that performs the seek. The configured segment is then propagated back downstream with a newsegment event. This information is then used to clip media to the segment boundaries. A segment structure is initialized with :func:`~gi.repository.Gst.Segment.init`, which takes a :obj:`~gi.repository.Gst.Format` that will be used as the format of the segment values. The segment will be configured with a start value of 0 and a stop/duration of -1, which is undefined. The default rate and applied_rate is 1.0. The public duration field contains the duration of the segment. When using the segment for seeking, the start and time members should normally be left to their default 0 value. The stop position is left to -1 unless explicitly configured to a different value after a seek event. The current position in the segment should be set by changing the position member in the structure. For elements that perform seeks, the current segment should be updated with the :func:`~gi.repository.Gst.Segment.do_seek` and the values from the seek event. This method will update all the segment fields. The position field will contain the new playback position. If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from the position position, possibly with updated flags or rate. For elements that want to use :obj:`~gi.repository.Gst.Segment` to track the playback region, update the segment fields with the information from the newsegment event. The :func:`~gi.repository.Gst.Segment.clip` method can be used to check and clip the media data to the segment boundaries. For elements that want to synchronize to the pipeline clock, :func:`~gi.repository.Gst.Segment.to_running_time` can be used to convert a timestamp to a value that can be used to synchronize to the clock. This function takes into account the base as well as any rate or applied_rate conversions. For elements that need to perform operations on media data in stream_time, :func:`~gi.repository.Gst.Segment.to_stream_time` can be used to convert a timestamp and the segment info to stream time (which is always between 0 and the duration of the stream). Constructors ------------ .. rst-class:: interim-class .. class:: Segment :no-index: .. classmethod:: new() -> ~gi.repository.Gst.Segment Allocate a new :obj:`~gi.repository.Gst.Segment` structure and initialize it using :func:`~gi.repository.Gst.Segment.init`. Free-function: gst_segment_free Methods ------- .. rst-class:: interim-class .. class:: Segment :no-index: .. method:: clip(format: ~gi.repository.Gst.Format, start: int, stop: int) -> ~typing.Tuple[bool, int, int] Clip the given ``start`` and ``stop`` values to the segment boundaries given in ``segment``\. ``start`` and ``stop`` are compared and clipped to ``segment`` start and stop values. If the function returns :const:`False`, ``start`` and ``stop`` are known to fall outside of ``segment`` and ``clip_start`` and ``clip_stop`` are not updated. When the function returns :const:`True`, ``clip_start`` and ``clip_stop`` will be updated. If ``clip_start`` or ``clip_stop`` are different from ``start`` or ``stop`` respectively, the region fell partially in the segment. Note that when ``stop`` is -1, ``clip_stop`` will be set to the end of the segment. Depending on the use case, this may or may not be what you want. :param format: the format of the segment. :param start: the start position in the segment :param stop: the stop position in the segment .. method:: do_seek(rate: float, format: ~gi.repository.Gst.Format, flags: ~gi.repository.Gst.SeekFlags, start_type: ~gi.repository.Gst.SeekType, start: int, stop_type: ~gi.repository.Gst.SeekType, stop: int) -> ~typing.Tuple[bool, bool] Update the segment structure with the field values of a seek event (see :func:`~gi.repository.Gst.Event.new_seek`). After calling this method, the segment field position and time will contain the requested new position in the segment. The new requested position in the segment depends on ``rate`` and ``start_type`` and ``stop_type``\. For positive ``rate``\, the new position in the segment is the new ``segment`` start field when it was updated with a ``start_type`` different from ``GST_SEEK_TYPE_NONE``. If no update was performed on ``segment`` start position (``GST_SEEK_TYPE_NONE``), ``start`` is ignored and ``segment`` position is unmodified. For negative ``rate``\, the new position in the segment is the new ``segment`` stop field when it was updated with a ``stop_type`` different from ``GST_SEEK_TYPE_NONE``. If no stop was previously configured in the segment, the duration of the segment will be used to update the stop position. If no update was performed on ``segment`` stop position (``GST_SEEK_TYPE_NONE``), ``stop`` is ignored and ``segment`` position is unmodified. The applied rate of the segment will be set to 1.0 by default. If the caller can apply a rate change, it should update ``segment`` rate and applied_rate after calling this function. ``update`` will be set to :const:`True` if a seek should be performed to the segment position field. This field can be :const:`False` if, for example, only the ``rate`` has been changed but not the playback position. :param rate: the rate of the segment. :param format: the format of the segment. :param flags: the segment flags for the segment :param start_type: the seek method :param start: the seek start value :param stop_type: the seek method :param stop: the seek stop value .. method:: free() -> None Free the allocated segment ``segment``\. .. method:: init(format: ~gi.repository.Gst.Format) -> None The start/position fields are set to 0 and the stop/duration fields are set to -1 (unknown). The default rate of 1.0 and no flags are set. Initialize ``segment`` to its default values. :param format: the format of the segment. .. method:: is_equal(s1: ~gi.repository.Gst.Segment) -> bool Checks for two segments being equal. Equality here is defined as perfect equality, including floating point values. .. versionadded:: 1.6 :param s1: a :obj:`~gi.repository.Gst.Segment` structure. .. method:: offset_running_time(format: ~gi.repository.Gst.Format, offset: int) -> bool Adjust the values in ``segment`` so that ``offset`` is applied to all future running-time calculations. .. versionadded:: 1.2.3 :param format: the format of the segment. :param offset: the offset to apply in the segment .. method:: position_from_running_time(format: ~gi.repository.Gst.Format, running_time: int) -> int Convert ``running_time`` into a position in the segment so that :func:`~gi.repository.Gst.Segment.to_running_time` with that position returns ``running_time``\. .. versionadded:: 1.8 :param format: the format of the segment. :param running_time: the running_time in the segment .. method:: position_from_running_time_full(format: ~gi.repository.Gst.Format, running_time: int) -> ~typing.Tuple[int, int] Translate ``running_time`` to the segment position using the currently configured segment. Compared to :func:`~gi.repository.Gst.Segment.position_from_running_time` this function can return negative segment position. This function is typically used by elements that need to synchronize buffers against the clock or each other. ``running_time`` can be any value and the result of this function for values outside of the segment is extrapolated. When 1 is returned, ``running_time`` resulted in a positive position returned in ``position``\. When this function returns -1, the returned ``position`` was < 0, and the value in the position variable should be negated to get the real negative segment position. .. versionadded:: 1.8 :param format: the format of the segment. :param running_time: the running-time .. method:: position_from_stream_time(format: ~gi.repository.Gst.Format, stream_time: int) -> int Convert ``stream_time`` into a position in the segment so that :func:`~gi.repository.Gst.Segment.to_stream_time` with that position returns ``stream_time``\. .. versionadded:: 1.8 :param format: the format of the segment. :param stream_time: the stream_time in the segment .. method:: position_from_stream_time_full(format: ~gi.repository.Gst.Format, stream_time: int) -> ~typing.Tuple[int, int] Translate ``stream_time`` to the segment position using the currently configured segment. Compared to :func:`~gi.repository.Gst.Segment.position_from_stream_time` this function can return negative segment position. This function is typically used by elements that need to synchronize buffers against the clock or each other. ``stream_time`` can be any value and the result of this function for values outside of the segment is extrapolated. When 1 is returned, ``stream_time`` resulted in a positive position returned in ``position``\. When this function returns -1, the returned ``position`` should be negated to get the real negative segment position. .. versionadded:: 1.8 :param format: the format of the segment. :param stream_time: the stream-time .. method:: set_running_time(format: ~gi.repository.Gst.Format, running_time: int) -> bool Adjust the start/stop and base values of ``segment`` such that the next valid buffer will be one with ``running_time``\. :param format: the format of the segment. :param running_time: the running_time in the segment .. method:: to_position(format: ~gi.repository.Gst.Format, running_time: int) -> int Convert ``running_time`` into a position in the segment so that :func:`~gi.repository.Gst.Segment.to_running_time` with that position returns ``running_time``\. .. deprecated:: Unknown Use :func:`~gi.repository.Gst.Segment.position_from_running_time` instead. :param format: the format of the segment. :param running_time: the running_time in the segment .. method:: to_running_time(format: ~gi.repository.Gst.Format, position: int) -> int Translate ``position`` to the total running time using the currently configured segment. Position is a value between ``segment`` start and stop time. This function is typically used by elements that need to synchronize to the global clock in a pipeline. The running time is a constantly increasing value starting from 0. When :func:`~gi.repository.Gst.Segment.init` is called, this value will reset to 0. This function returns -1 if the position is outside of ``segment`` start and stop. :param format: the format of the segment. :param position: the position in the segment .. method:: to_running_time_full(format: ~gi.repository.Gst.Format, position: int) -> ~typing.Tuple[int, int] Translate ``position`` to the total running time using the currently configured segment. Compared to :func:`~gi.repository.Gst.Segment.to_running_time` this function can return negative running-time. This function is typically used by elements that need to synchronize buffers against the clock or each other. ``position`` can be any value and the result of this function for values outside of the segment is extrapolated. When 1 is returned, ``position`` resulted in a positive running-time returned in ``running_time``\. When this function returns -1, the returned ``running_time`` should be negated to get the real negative running time. .. versionadded:: 1.6 :param format: the format of the segment. :param position: the position in the segment .. method:: to_stream_time(format: ~gi.repository.Gst.Format, position: int) -> int Translate ``position`` to stream time using the currently configured segment. The ``position`` value must be between ``segment`` start and stop value. This function is typically used by elements that need to operate on the stream time of the buffers it receives, such as effect plugins. In those use cases, ``position`` is typically the buffer timestamp or clock time that one wants to convert to the stream time. The stream time is always between 0 and the total duration of the media stream. .. versionadded:: 1.8 :param format: the format of the segment. :param position: the position in the segment .. method:: to_stream_time_full(format: ~gi.repository.Gst.Format, position: int) -> ~typing.Tuple[int, int] Translate ``position`` to the total stream time using the currently configured segment. Compared to :func:`~gi.repository.Gst.Segment.to_stream_time` this function can return negative stream-time. This function is typically used by elements that need to synchronize buffers against the clock or each other. ``position`` can be any value and the result of this function for values outside of the segment is extrapolated. When 1 is returned, ``position`` resulted in a positive stream-time returned in ``stream_time``\. When this function returns -1, the returned ``stream_time`` should be negated to get the real negative stream time. .. versionadded:: 1.8 :param format: the format of the segment. :param position: the position in the segment Fields ------ .. rst-class:: interim-class .. class:: Segment :no-index: .. attribute:: applied_rate The applied rate is the rate that has been applied to the stream. The effective/resulting playback rate of a stream is ``rate * applied_rate``\. The applied rate can be set by source elements when a server is sending the stream with an already modified playback speed rate. Filter elements that modify the stream in a way that modifies the playback speed should also modify the applied rate. For example the ``videorate`` element when its ``videorate``:rate property is set will set the applied rate of the segment it pushed downstream. Also ``scaletempo`` applies the input segment rate to the stream and outputs a segment with rate=1.0 and applied_rate=. .. attribute:: base The running time (plus elapsed time, see offset) of the segment `start `__ (`stop `__ if rate < 0.0). .. attribute:: duration The duration of the segment is the maximum absolute difference between :obj:`~gi.repository.Gst.Segment`\.start and :obj:`~gi.repository.Gst.Segment`\.stop if stop is not set, otherwise it should be the difference between those two values. This should be set by elements that know the overall stream duration (like demuxers) and will be used when seeking with ``GST_SEEK_TYPE_END``. .. attribute:: flags Flags for this segment .. attribute:: format The unit used for all of the segment's values. .. attribute:: offset The offset expresses the elapsed time (in buffer timestamps) before a seek with its start (stop if rate < 0.0) seek type set to ``GST_SEEK_TYPE_NONE``, the value is set to the position of the segment at the time of the seek. .. attribute:: position The buffer timestamp position in the segment is supposed to be updated by elements such as sources, demuxers or parsers to track progress by setting it to the last pushed buffer' end time (`timestamp `__ + :obj:`~gi.repository.Gst.Buffer`\.duration) for that specific segment. The position is used when reconfiguring the segment with ``gst_segment_do_seek`` when the seek is only updating the segment (see `offset `__\). .. attribute:: rate The playback rate of the segment is set in response to a seek event and, without any seek, the value should be ``1.0``\. This value is used by elements that synchronize buffer `running times `__ on the clock (usually the sink elements), leading to consuming buffers faster (for a value ``> 1.0``\) or slower (for ``0.0 < value < 1.0``\) than normal playback speed. The rate also defines the playback direction, meaning that when the value is lower than ``0.0``\, the playback happens in reverse, and the `stream-time `__ is going backward. The ``rate`` value should never be ``0.0``\. .. attribute:: start The start time of the segment (in buffer timestamps) `(PTS) `__\, that is the timestamp of the first buffer to output inside the segment (last one during reverse playback). For example decoders will `clip `__ out the buffers before the start time. .. attribute:: stop The stop time of the segment (in buffer timestamps) `(PTS) `__\, that is the timestamp of the last buffer to output inside the segment (first one during reverse playback). For example decoders will `clip `__ out buffers after the stop time. .. attribute:: time The stream time of the segment `start `__ (`stop `__ if rate < 0.0).