GI.Gst.Structs.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 segmentInit, which takes a 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 segmentDoSeek 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 Segment to track the playback region, update the segment fields with the information from the newsegment event. The segmentClip 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, segmentToRunningTime 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, segmentToStreamTime 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).

Exported types

newtype Segment

Memory-managed wrapper type.

Constructors

Segment (ManagedPtr Segment)

Instances

BoxedObject Segment

Defined in GI.Gst.Structs.Segment

Methods

boxedType :: Segment -> IO GType

tag ~ AttrSet => Constructible Segment tag

Defined in GI.Gst.Structs.Segment

Methods

new :: MonadIO m => (ManagedPtr Segment -> Segment) -> [AttrOp Segment tag] -> m Segment

newZeroSegment :: MonadIO m => m Segment

Construct a Segment struct initialized to zero.

noSegment :: Maybe Segment

A convenience alias for Nothing :: Maybe Segment.

Methods

clip

segmentClip

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

start: the start position in the segment

-> Word64

stop: the stop position in the segment

-> m (Bool, Word64, Word64)

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.

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 clipStart and clipStop are not updated.

When the function returns True, clipStart and clipStop will be updated. If clipStart or clipStop are different from start or stop respectively, the region fell partially in the segment.

Note that when stop is -1, clipStop will be set to the end of the segment. Depending on the use case, this may or may not be what you want.

copy

segmentCopy

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment

-> m Segment

Returns: a new Segment, free with segmentFree.

Create a copy of given segment.

Free-function: gst_segment_free

copyInto

segmentCopyInto

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

src: a Segment

-> Segment

dest: a Segment

-> m ()

Copy the contents of src into dest.

doSeek

segmentDoSeek

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Double

rate: the rate of the segment.

-> Format

format: the format of the segment.

-> [SeekFlags]

flags: the segment flags for the segment

-> SeekType

startType: the seek method

-> Word64

start: the seek start value

-> SeekType

stopType: the seek method

-> Word64

stop: the seek stop value

-> m (Bool, Bool)

Returns: True if the seek could be performed.

Update the segment structure with the field values of a seek event (see eventNewSeek).

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 startType and stopType.

For positive rate, the new position in the segment is the new segment start field when it was updated with a startType 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 stopType 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.

free

segmentFree

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment

-> m ()

Free the allocated segment segment.

init

segmentInit

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> m ()

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.

isEqual

segmentIsEqual

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

s0: a Segment structure.

-> Segment

s1: a Segment structure.

-> m Bool

Returns: True if the segments are equal, False otherwise.

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

Since: 1.6

new

segmentNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Segment

Returns: a new Segment, free with segmentFree.

Allocate a new Segment structure and initialize it using segmentInit.

Free-function: gst_segment_free

offsetRunningTime

segmentOffsetRunningTime

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Int64

offset: the offset to apply in the segment

-> m Bool

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

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

Since: 1.2.3

positionFromRunningTime

segmentPositionFromRunningTime

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

runningTime: the running_time in the segment

-> m Word64

Returns: the position in the segment for runningTime. This function returns -1 when runningTime is -1 or when it is not inside segment.

Convert runningTime into a position in the segment so that segmentToRunningTime with that position returns runningTime.

Since: 1.8

positionFromRunningTimeFull

segmentPositionFromRunningTimeFull

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

runningTime: the running-time

-> m (Int32, Word64)

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

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

runningTime can be any value and the result of this function for values outside of the segment is extrapolated.

When 1 is returned, runningTime 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.

Since: 1.8

positionFromStreamTime

segmentPositionFromStreamTime

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

streamTime: the stream_time in the segment

-> m Word64

Returns: the position in the segment for streamTime. This function returns -1 when streamTime is -1 or when it is not inside segment.

Convert streamTime into a position in the segment so that segmentToStreamTime with that position returns streamTime.

Since: 1.8

positionFromStreamTimeFull

segmentPositionFromStreamTimeFull

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

streamTime: the stream-time

-> m (Int32, Word64)

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

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

streamTime can be any value and the result of this function for values outside of the segment is extrapolated.

When 1 is returned, streamTime 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.

Since: 1.8

setRunningTime

segmentSetRunningTime

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

runningTime: the running_time in the segment

-> m Bool

Returns: True if the segment could be updated successfully. If False is returned, runningTime is -1 or not in segment.

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

toPosition

segmentToPosition

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

runningTime: the running_time in the segment

-> m Word64

Returns: the position in the segment for runningTime. This function returns -1 when runningTime is -1 or when it is not inside segment.

Deprecated: Use segmentPositionFromRunningTime instead.

Convert runningTime into a position in the segment so that segmentToRunningTime with that position returns runningTime.

toRunningTime

segmentToRunningTime

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

position: the position in the segment

-> m Word64

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

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 segmentInit is called, this value will reset to 0.

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

toRunningTimeFull

segmentToRunningTimeFull

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

position: the position in the segment

-> m (Int32, Word64)

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

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

When this function returns -1, the returned runningTime should be negated to get the real negative running time.

Since: 1.6

toStreamTime

segmentToStreamTime

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

position: the position in the segment

-> m Word64

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

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.

Since: 1.8

toStreamTimeFull

segmentToStreamTimeFull

Arguments

:: (HasCallStack, MonadIO m)

=> Segment

segment: a Segment structure.

-> Format

format: the format of the segment.

-> Word64

position: the position in the segment

-> m (Int32, Word64)

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

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

When this function returns -1, the returned streamTime should be negated to get the real negative stream time.

Since: 1.8

Properties

appliedRate

the already applied rate to the segment

getSegmentAppliedRate :: MonadIO m => Segment -> m Double

Get the value of the “applied_rate” field. When overloading is enabled, this is equivalent to

get segment #appliedRate

setSegmentAppliedRate :: MonadIO m => Segment -> Double -> m ()

Set the value of the “applied_rate” field. When overloading is enabled, this is equivalent to

set segment [ #appliedRate := value ]

base

the running time (plus elapsed time, see offset) of the segment start

getSegmentBase :: MonadIO m => Segment -> m Word64

Get the value of the “base” field. When overloading is enabled, this is equivalent to

get segment #base

setSegmentBase :: MonadIO m => Segment -> Word64 -> m ()

Set the value of the “base” field. When overloading is enabled, this is equivalent to

set segment [ #base := value ]

duration

the duration of the stream

getSegmentDuration :: MonadIO m => Segment -> m Word64

Get the value of the “duration” field. When overloading is enabled, this is equivalent to

get segment #duration

setSegmentDuration :: MonadIO m => Segment -> Word64 -> m ()

Set the value of the “duration” field. When overloading is enabled, this is equivalent to

set segment [ #duration := value ]

flags

flags for this segment

getSegmentFlags :: MonadIO m => Segment -> m [SegmentFlags]

Get the value of the “flags” field. When overloading is enabled, this is equivalent to

get segment #flags

setSegmentFlags :: MonadIO m => Segment -> [SegmentFlags] -> m ()

Set the value of the “flags” field. When overloading is enabled, this is equivalent to

set segment [ #flags := value ]

format

the format of the segment values

getSegmentFormat :: MonadIO m => Segment -> m Format

Get the value of the “format” field. When overloading is enabled, this is equivalent to

get segment #format

setSegmentFormat :: MonadIO m => Segment -> Format -> m ()

Set the value of the “format” field. When overloading is enabled, this is equivalent to

set segment [ #format := value ]

offset

the amount (in buffer timestamps) that has already been elapsed in the segment

getSegmentOffset :: MonadIO m => Segment -> m Word64

Get the value of the “offset” field. When overloading is enabled, this is equivalent to

get segment #offset

setSegmentOffset :: MonadIO m => Segment -> Word64 -> m ()

Set the value of the “offset” field. When overloading is enabled, this is equivalent to

set segment [ #offset := value ]

position

the buffer timestamp position in the segment (used internally by elements such as sources, demuxers or parsers to track progress)

getSegmentPosition :: MonadIO m => Segment -> m Word64

Get the value of the “position” field. When overloading is enabled, this is equivalent to

get segment #position

setSegmentPosition :: MonadIO m => Segment -> Word64 -> m ()

Set the value of the “position” field. When overloading is enabled, this is equivalent to

set segment [ #position := value ]

rate

the playback rate of the segment

getSegmentRate :: MonadIO m => Segment -> m Double

Get the value of the “rate” field. When overloading is enabled, this is equivalent to

get segment #rate

setSegmentRate :: MonadIO m => Segment -> Double -> m ()

Set the value of the “rate” field. When overloading is enabled, this is equivalent to

set segment [ #rate := value ]

start

the start of the segment in buffer timestamp time (PTS)

getSegmentStart :: MonadIO m => Segment -> m Word64

Get the value of the “start” field. When overloading is enabled, this is equivalent to

get segment #start

setSegmentStart :: MonadIO m => Segment -> Word64 -> m ()

Set the value of the “start” field. When overloading is enabled, this is equivalent to

set segment [ #start := value ]

stop

the stop of the segment in buffer timestamp time (PTS)

getSegmentStop :: MonadIO m => Segment -> m Word64

Get the value of the “stop” field. When overloading is enabled, this is equivalent to

get segment #stop

setSegmentStop :: MonadIO m => Segment -> Word64 -> m ()

Set the value of the “stop” field. When overloading is enabled, this is equivalent to

set segment [ #stop := value ]

time

the stream time of the segment start

getSegmentTime :: MonadIO m => Segment -> m Word64

Get the value of the “time” field. When overloading is enabled, this is equivalent to

get segment #time

setSegmentTime :: MonadIO m => Segment -> Word64 -> m ()

Set the value of the “time” field. When overloading is enabled, this is equivalent to

set segment [ #time := value ]