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=<inputsegment.rate>.
the duration of the segment is the maximum absolute difference between #GstSegment.start and #GstSegment.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.
flags for this segment
the unit used for all of the segment's values.
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.
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 + #GstBuffer.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).
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.
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.
the format of the segment.
the start position in the segment
the stop position in the segment
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 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 %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.
the rate of the segment.
the format of the segment.
the segment flags for the segment
the seek method
the seek start value
the seek method
the seek stop value
Free the allocated segment segment.
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.
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.
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 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.
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.
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.
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.
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 #GstFormat 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_SEEK_TYPE_NONE, playback continues from the position position, possibly with updated flags or rate.
For elements that want to use #GstSegment 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).