Next: , Previous: GstRegistry, Up: Top

32 GstSegment

Structure describing the configured region of interest in a media file.

32.1 Overview

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:

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.

If the segment is used for managing seeks, the segment duration should be set with gst-segment-set-duration. 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 with the gst-segment-set-last-stop. The public last_stop field contains the last set stop position in the segment.

For elements that perform seeks, the current segment should be updated with the gst-segment-set-seek and the values from the seek event. This method will update all the segment fields. The last_stop field will contain the new playback position. If the cur_type was different from GST_SEEK_TYPE_NONE, playback continues from the last_stop position, possibly with updated flags or rate.

For elements that want to use <gst-segment> to track the playback region, use gst-segment-set-newsegment to 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 all accumulated segments 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).

Last reviewed on 2007-05-17 (0.10.13)

32.2 Usage

— Function: gst-segment-clip (self <gst-segment*>) (format <gst-format>) (start int64) (stop int64)   (ret bool) (clip_start int64) (clip_stop int64)

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 FALSE, start and stop are known to fall outside of segment 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.

segment
a <gst-segment> structure.
format
the format of the segment.
start
the start position in the segment
stop
the stop position in the segment
clip-start
the clipped start position in the segment
clip-stop
the clipped stop position in the segment
ret
TRUE if the given start and stop times fall partially or completely in segment, FALSE if the values are completely outside of the segment.
— Function: gst-segment-init (self <gst-segment*>) (format <gst-format>)

The start/last_stop positions 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.

segment
a <gst-segment> structure.
format
the format of the segment.
— Function: gst-segment-new   (ret <gst-segment*>)

Allocate a new <gst-segment> structure and initialize it using gst-segment-init.

ret
a new <gst-segment>, free with gst-segment-free.
— Function: gst-segment-set-duration (self <gst-segment*>) (format <gst-format>) (duration int64)

Set the duration of the segment to duration. This function is mainly used by elements that perform seeking and know the total duration of the segment.

This field should be set to allow seeking requests relative to the duration.

segment
a <gst-segment> structure.
format
the format of the segment.
duration
the duration of the segment info or -1 if unknown.
— Function: gst-segment-set-last-stop (self <gst-segment*>) (format <gst-format>) (position int64)

Set the last observed stop position in the segment to position.

This field should be set to allow seeking requests relative to the current playing position.

segment
a <gst-segment> structure.
format
the format of the segment.
position
the position
— Function: gst-segment-set-newsegment (self <gst-segment*>) (update bool) (rate double) (format <gst-format>) (start int64) (stop int64) (time int64)

Update the segment structure with the field values of a new segment event and with a default applied_rate of 1.0.

segment
a <gst-segment> structure.
update
flag indicating a new segment is started or updated
rate
the rate of the segment.
format
the format of the segment.
start
the new start value
stop
the new stop value
time
the new stream time

Since 0.10.6

— Function: gst-segment-set-newsegment-full (self <gst-segment*>) (update bool) (rate double) (applied_rate double) (format <gst-format>) (start int64) (stop int64) (time int64)

Update the segment structure with the field values of a new segment event.

segment
a <gst-segment> structure.
update
flag indicating a new segment is started or updated
rate
the rate of the segment.
applied-rate
the applied rate of the segment.
format
the format of the segment.
start
the new start value
stop
the new stop value
time
the new stream time
— Function: gst-segment-set-seek (self <gst-segment*>) (rate double) (format <gst-format>) (flags <gst-seek-flags>) (cur_type <gst-seek-type>) (cur int64) (stop_type <gst-seek-type>) (stop int64)   (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 last_stop 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 last_stop 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 last_stop 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 TRUE if a seek should be performed to the segment last_stop field. This field can be FALSE if, for example, only the rate has been changed but not the playback position.

segment
a <gst-segment> structure.
rate
the rate of the segment.
format
the format of the segment.
flags
the seek flags for the segment
start-type
the seek method
start
the seek start value
stop-type
the seek method
stop
the seek stop value
update
boolean holding whether last_stop was updated.
— Function: gst-segment-to-running-time (self <gst-segment*>) (format <gst-format>) (position int64)   (ret int64)

Translate position to the total running time using the currently configured and previously accumulated segments. 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 runnning 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 segment start and stop.

segment
a <gst-segment> structure.
format
the format of the segment.
position
the position in the segment
ret
the position as the total running time or -1 when an invalid position was given.
— Function: gst-segment-to-stream-time (self <gst-segment*>) (format <gst-format>) (position int64)   (ret int64)

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.

segment
a <gst-segment> structure.
format
the format of the segment.
position
the position in the segment
ret
the position in stream_time or -1 when an invalid position was given.