Gst.Segment

Fields

Name Type Access Description
applied_rate float r/w the already applied rate to the segment
base int r/w the running time (plus elapsed time, see offset) of the segment start
duration int r/w the duration of the stream
flags Gst.SegmentFlags r/w flags for this segment
format Gst.Format r/w the format of the segment values
offset int r/w the amount (in buffer timestamps) that has already been elapsed in the segment
position int r/w the buffer timestamp position in the segment (used internally by elements such as sources, demuxers or parsers to track progress)
rate float r/w the playback rate of the segment
start int r/w the start of the segment in buffer timestamp time (PTS)
stop int r/w the stop of the segment in buffer timestamp time (PTS)
time int r/w the stream time of the segment start

Methods

class new ()
  clip (format, start, stop)
  copy ()
  copy_into (dest)
  do_seek (rate, format, flags, start_type, start, stop_type, stop)
  free ()
  init (format)
  is_equal (s1)
  offset_running_time (format, offset)
  position_from_running_time (format, running_time)
  position_from_running_time_full (format, running_time)
  position_from_stream_time (format, stream_time)
  position_from_stream_time_full (format, stream_time)
  set_running_time (format, running_time)
  to_position (format, running_time)
  to_running_time (format, position)
  to_running_time_full (format, position)
  to_stream_time (format, position)
  to_stream_time_full (format, position)

Details

class Gst.Segment

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 Gst.Segment.init(), which takes a 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 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.SeekType.NONE, playback continues from the position position, possibly with updated flags or rate.

For elements that want to use Gst.Segment to track the playback region, update the segment fields with the information from the newsegment event. The 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, 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, 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).

classmethod new()[source]
Returns:a new Gst.Segment, free with Gst.Segment.free().
Return type:Gst.Segment

Allocate a new Gst.Segment structure and initialize it using Gst.Segment.init().

Free-function: Gst.Segment.free

clip(format, start, stop)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • start (int) – the start position in the segment
  • stop (int) – the stop position in the segment
Returns:

True if the given start and stop times fall partially or completely in self, False if the values are completely outside of the segment.

clip_start:the clipped start position in the segment
clip_stop:the clipped stop position in the segment

Return type:

(bool, clip_start: int, clip_stop: int)

Clip the given start and stop values to the segment boundaries given in self. start and stop are compared and clipped to self start and stop values.

If the function returns False, start and stop are known to fall outside of self and clip_start and clip_stop are not updated.

When the function returns 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.

copy()[source]
Returns:a new Gst.Segment, free with Gst.Segment.free().
Return type:Gst.Segment

Create a copy of given self.

Free-function: Gst.Segment.free

copy_into(dest)[source]
Parameters:dest (Gst.Segment) – a Gst.Segment

Copy the contents of self into dest.

do_seek(rate, format, flags, start_type, start, stop_type, stop)[source]
Parameters:
  • rate (float) – the rate of the segment.
  • format (Gst.Format) – the format of the segment.
  • flags (Gst.SeekFlags) – the segment flags for the segment
  • start_type (Gst.SeekType) – the seek method
  • start (int) – the seek start value
  • stop_type (Gst.SeekType) – the seek method
  • stop (int) – the seek stop value
Returns:

True if the seek could be performed.

update:boolean holding whether position was updated.

Return type:

(bool, update: bool)

Update the segment structure with the field values of a seek event (see 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 self start field when it was updated with a start_type different from Gst.SeekType.NONE. If no update was performed on self start position (Gst.SeekType.NONE), start is ignored and self position is unmodified.

For negative rate, the new position in the segment is the new self stop field when it was updated with a stop_type different from Gst.SeekType.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 self stop position (Gst.SeekType.NONE), stop is ignored and self 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 self rate and applied_rate after calling this function.

update will be set to True if a seek should be performed to the segment position field. This field can be False if, for example, only the rate has been changed but not the playback position.

free()[source]

Free the allocated segment self.

init(format)[source]
Parameters:format (Gst.Format) – the format of the segment.

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 self to its default values.

is_equal(s1)[source]
Parameters:s1 (Gst.Segment) – a Gst.Segment structure.
Returns:True if the segments are equal, False otherwise.
Return type:bool

Checks for two segments being equal. Equality here is defined as perfect equality, including floating point values.

New in version 1.6.

offset_running_time(format, offset)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • offset (int) – the offset to apply in the segment
Returns:

True if the segment could be updated successfully. If False is returned, offset is not in self.

Return type:

bool

Adjust the values in self so that offset is applied to all future running-time calculations.

New in version 1.2.3.

position_from_running_time(format, running_time)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • running_time (int) – the running_time in the segment
Returns:

the position in the segment for running_time. This function returns -1 when running_time is -1 or when it is not inside self.

Return type:

int

Convert running_time into a position in the segment so that Gst.Segment.to_running_time() with that position returns running_time.

New in version 1.8.

position_from_running_time_full(format, running_time)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • running_time (int) – the running-time
Returns:

a 1 or -1 on success, 0 on failure.

position:the resulting position in the segment

Return type:

(int, position: int)

Translate running_time to the segment position using the currently configured segment. Compared to 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.

New in version 1.8.

position_from_stream_time(format, stream_time)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • stream_time (int) – the stream_time in the segment
Returns:

the position in the segment for stream_time. This function returns -1 when stream_time is -1 or when it is not inside self.

Return type:

int

Convert stream_time into a position in the segment so that Gst.Segment.to_stream_time() with that position returns stream_time.

New in version 1.8.

position_from_stream_time_full(format, stream_time)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • stream_time (int) – the stream-time
Returns:

a 1 or -1 on success, 0 on failure.

position:the resulting position in the segment

Return type:

(int, position: int)

Translate stream_time to the segment position using the currently configured segment. Compared to 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.

New in version 1.8.

set_running_time(format, running_time)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • running_time (int) – the running_time in the segment
Returns:

True if the segment could be updated successfully. If False is returned, running_time is -1 or not in self.

Return type:

bool

Adjust the start/stop and base values of self such that the next valid buffer will be one with running_time.

to_position(format, running_time)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • running_time (int) – the running_time in the segment
Returns:

the position in the segment for running_time. This function returns -1 when running_time is -1 or when it is not inside self.

Return type:

int

Convert running_time into a position in the segment so that Gst.Segment.to_running_time() with that position returns running_time.

Deprecated since version ???: Use Gst.Segment.position_from_running_time() instead.

to_running_time(format, position)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • position (int) – the position in the segment
Returns:

the position as the total running time or -1 when an invalid position was given.

Return type:

int

Translate position to the total running time using the currently configured segment. Position is a value between self 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 Gst.Segment.init() is called, this value will reset to 0.

This function returns -1 if the position is outside of self start and stop.

to_running_time_full(format, position)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • position (int) – the position in the segment
Returns:

a 1 or -1 on success, 0 on failure.

running_time:result running-time

Return type:

(int, running_time: int)

Translate position to the total running time using the currently configured segment. Compared to 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.

New in version 1.6.

to_stream_time(format, position)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • position (int) – the position in the segment
Returns:

the position in stream_time or -1 when an invalid position was given.

Return type:

int

Translate position to stream time using the currently configured segment. The position value must be between self 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.

New in version 1.8.

to_stream_time_full(format, position)[source]
Parameters:
  • format (Gst.Format) – the format of the segment.
  • position (int) – the position in the segment
Returns:

a 1 or -1 on success, 0 on failure.

stream_time:result stream-time

Return type:

(int, stream_time: int)

Translate position to the total stream time using the currently configured segment. Compared to 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.

New in version 1.8.