GstSegment: GStreamer 1.0 Core Reference Manual

## GstSegment GstSegment — Structure describing the configured region of interest in a media file. |

## Functions

gboolean | gst_segment_clip ()
void | gst_segment_init ()
GstSegment * | gst_segment_new ()
GstSegment * | gst_segment_copy ()
void | gst_segment_free ()
gboolean | gst_segment_do_seek ()
guint64 | gst_segment_position_from_stream_time ()
gint | gst_segment_position_from_stream_time_full ()
guint64 | gst_segment_to_running_time ()
gint | gst_segment_to_running_time_full ()
guint64 | gst_segment_to_stream_time ()
gint | gst_segment_to_stream_time_full ()
guint64 | gst_segment_position_from_running_time ()
gint | gst_segment_position_from_running_time_full ()
guint64 | gst_segment_to_position ()
gboolean | gst_segment_set_running_time ()
void | gst_segment_copy_into ()
gboolean | gst_segment_offset_running_time ()
gboolean | gst_segment_is_equal ()

## Types and Values

struct | GstSegment
enum | GstSegmentFlags

## Object Hierarchy

        GBoxed
        ╰── GstSegment

## Includes

    #include <gst/gstprotection.h>

## Description

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

## Functions

### gst_segment_clip ()

    gboolean
    gst_segment_clip (const GstSegment *segment,
                      GstFormat format,
                      guint64 start,
                      guint64 stop,
                      guint64 *clip_start,
                      guint64 *clip_stop);

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.

#### Parameters

segment | a GstSegment 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. | [out][allow-none]
clip_stop | the clipped stop position in the segment. | [out][allow-none]

#### Returns

`TRUE` if the given `start` and `stop` times fall partially or completely in `segment` , `FALSE` if the values are completely outside of the segment.

### gst_segment_init ()

    void
    gst_segment_init (GstSegment *segment,
                      GstFormat format);

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.

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |

### gst_segment_new ()

    GstSegment *
    gst_segment_new (void);

Allocate a new GstSegment structure and initialize it using `gst_segment_init()`.

Free-function: gst_segment_free

#### Returns

a new GstSegment, free with `gst_segment_free()`.

[transfer full]

### gst_segment_copy ()

    GstSegment *
    gst_segment_copy (const GstSegment *segment);

Create a copy of given `segment` .

Free-function: gst_segment_free

#### Parameters

segment | a GstSegment. | [transfer none]

#### Returns

a new GstSegment, free with `gst_segment_free()`.

[transfer full]

### gst_segment_free ()

    void
    gst_segment_free (GstSegment *segment);

Free the allocated segment `segment` .

#### Parameters

segment | a GstSegment. | [in][transfer full]

### gst_segment_do_seek ()

    gboolean
    gst_segment_do_seek (GstSegment *segment,
                         gdouble rate,
                         GstFormat format,
                         GstSeekFlags flags,
                         GstSeekType start_type,
                         guint64 start,
                         GstSeekType stop_type,
                         guint64 stop,
                         gboolean *update);

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.

#### Parameters

segment | a GstSegment structure. |
rate | the rate of the segment. |
format | the format of the segment. |
flags | the segment 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 position was updated. | [out][allow-none]

#### Returns

`TRUE` if the seek could be performed.

### gst_segment_position_from_stream_time ()

    guint64
    gst_segment_position_from_stream_time (const GstSegment *segment,
                                           GstFormat format,
                                           guint64 stream_time);

Convert `stream_time` into a position in the segment so that `gst_segment_to_stream_time()` with that position returns `stream_time` .

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
stream_time | 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 `segment` .

Since: 1.8

### gst_segment_position_from_stream_time_full ()

    gint
    gst_segment_position_from_stream_time_full
                                   (const GstSegment *segment,
                                    GstFormat format,
                                    guint64 stream_time,
                                    guint64 *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.

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
stream_time | the stream-time |
position | the resulting position in the segment. | [out]

#### Returns

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

Since: 1.8

### gst_segment_to_running_time ()

    guint64
    gst_segment_to_running_time (const GstSegment *segment,
                                 GstFormat format,
                                 guint64 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.

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
position | the position in the segment |

#### Returns

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

### gst_segment_to_running_time_full ()

    gint
    gst_segment_to_running_time_full (const GstSegment *segment,
                                      GstFormat format,
                                      guint64 position,
                                      guint64 *running_time);

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

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

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
position | the position in the segment |
running_time | result running-time. | [out][allow-none]

#### Returns

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

Since: 1.6

### gst_segment_to_stream_time ()

    guint64
    gst_segment_to_stream_time (const GstSegment *segment,
                                GstFormat format,
                                guint64 position);

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.

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
position | the position in the segment |

#### Returns

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

Since: 1.8

### gst_segment_to_stream_time_full ()

    gint
    gst_segment_to_stream_time_full (const GstSegment *segment,
                                     GstFormat format,
                                     guint64 position,
                                     guint64 *stream_time);

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

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

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
position | the position in the segment |
stream_time | result stream-time. | [out]

#### Returns

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

Since: 1.8

### gst_segment_position_from_running_time ()

    guint64
    gst_segment_position_from_running_time
                                   (const GstSegment *segment,
                                    GstFormat format,
                                    guint64 running_time);

Convert `running_time` into a position in the segment so that `gst_segment_to_running_time()` with that position returns `running_time` .

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
running_time | 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 `segment` .

Since: 1.8

### gst_segment_position_from_running_time_full ()

    gint
    gst_segment_position_from_running_time_full
                                   (const GstSegment *segment,
                                    GstFormat format,
                                    guint64 running_time,
                                    guint64 *position);

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.

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
running_time | the running-time |
position | the resulting position in the segment. | [out]

#### Returns

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

Since: 1.8

### gst_segment_to_position ()

    guint64
    gst_segment_to_position (const GstSegment *segment,
                             GstFormat format,
                             guint64 running_time);

`gst_segment_to_position` is deprecated and should not be used in newly-written code.

Use `gst_segment_position_from_running_time()` instead.

Convert `running_time` into a position in the segment so that `gst_segment_to_running_time()` with that position returns `running_time` .

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
running_time | 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 `segment` .

### gst_segment_set_running_time ()

    gboolean
    gst_segment_set_running_time (GstSegment *segment,
                                  GstFormat format,
                                  guint64 running_time);

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

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
running_time | 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 `segment` .

### gst_segment_copy_into ()

    void
    gst_segment_copy_into (const GstSegment *src,
                           GstSegment *dest);

Copy the contents of `src` into `dest` .

#### Parameters

src | a GstSegment. | [transfer none]
dest | a GstSegment. | [transfer none]

### gst_segment_offset_running_time ()

    gboolean
    gst_segment_offset_running_time (GstSegment *segment,
                                     GstFormat format,
                                     gint64 offset);

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

#### Parameters

segment | a GstSegment structure. |
format | the format of the segment. |
offset | the offset to apply in the segment |

#### Returns

`TRUE` if the segment could be updated successfully. If `FALSE` is returned, `offset` is not in `segment` .

Since: 1.2.3

### gst_segment_is_equal ()

    gboolean
    gst_segment_is_equal (const GstSegment *s0,
                          const GstSegment *s1);

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

#### Parameters

s0 | a GstSegment structure. |
s1 | a GstSegment structure. |

#### Returns

`TRUE` if the segments are equal, `FALSE` otherwise.

Since: 1.6

## Types and Values

### struct GstSegment

    struct GstSegment {
      GstSegmentFlags flags;

      gdouble         rate;
      gdouble         applied_rate;

      GstFormat       format;
      guint64         base;
      guint64         offset;
      guint64         start;
      guint64         stop;
      guint64         time;

      guint64         position;
      guint64         duration;
    };

A helper structure that holds the configured region of interest in a media file.

#### Members

GstSegmentFlags `flags`; | flags for this segment |
gdouble `rate`; | the playback rate of the segment |
gdouble `applied_rate`; | the already applied rate to the segment |
GstFormat `format`; | the format of the segment values |
guint64 `base`; | the running time (plus elapsed time, see offset) of the segment start |
guint64 `offset`; | the amount (in buffer timestamps) that has already been elapsed in the segment |
guint64 `start`; | the start of the segment in buffer timestamp time (PTS) |
guint64 `stop`; | the stop of the segment in buffer timestamp time (PTS) |
guint64 `time`; | the stream time of the segment start |
guint64 `position`; | the buffer timestamp position in the segment (used internally by elements such as sources, demuxers or parsers to track progress) |
guint64 `duration`; | the duration of the stream |

### enum GstSegmentFlags

Flags for the GstSegment structure. Currently mapped to the corresponding values of the seek flags.

#### Members

GST_SEGMENT_FLAG_NONE | no flags |
GST_SEGMENT_FLAG_RESET | reset the pipeline running_time to the segment running_time |
GST_SEGMENT_FLAG_TRICKMODE | perform skip playback (Since 1.6) |
GST_SEGMENT_FLAG_SKIP | Deprecated backward compatibility flag, replaced by `GST_SEGMENT_FLAG_TRICKMODE` |
GST_SEGMENT_FLAG_SEGMENT | send SEGMENT_DONE instead of EOS |
GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS | Decode only keyframes, where possible (Since 1.6) |
GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO | Do not decode any audio, where possible (Since 1.6) |

## See Also

GstEvent