org.freedesktop.gstreamer

Class Pipeline

java.lang.Object

org.freedesktop.gstreamer.glib.NativeObject

org.freedesktop.gstreamer.glib.RefCountedObject

org.freedesktop.gstreamer.glib.GObject

org.freedesktop.gstreamer.GstObject

org.freedesktop.gstreamer.Element

org.freedesktop.gstreamer.Bin

org.freedesktop.gstreamer.Pipeline

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

PlayBin

public class Pipeline
extends Bin

A Pipeline is a special Bin used as the top level container for the filter graph. The Pipeline will manage the selection and distribution of a global Clock as well as provide a Bus to the application. It will also implement a default behaviour for managing seek events (see seek).

See upstream documentation at https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstPipeline.html

Elements are added and removed from the pipeline using the Bin methods like add and remove.

Before changing the state of the Pipeline (see Element) a Bus can be retrieved with getBus. This bus can then be used to receive Messages from the elements in the pipeline.

By default, a Pipeline will automatically flush the pending Bus messages when going to the NULL state to ensure that no circular references exist when no messages are read from the Bus. This behaviour can be changed with setAutoFlushBus

When the Pipeline performs the PAUSED to PLAYING state change it will select a clock for the elements. The clock selection algorithm will by default select a clock provided by an element that is most upstream (closest to the source). For live pipelines (ones that return StateChangeReturn.NO_PREROLL from the setState call) this will select the clock provided by the live source. For normal pipelines this will select a clock provided by the sinks (most likely the audio sink). If no element provides a clock, a default SystemClock is used.

The clock selection can be controlled with the gst_pipeline_use_clock() method, which will enforce a given clock on the pipeline. With gst_pipeline_auto_clock() the default clock selection algorithm can be restored.

A Pipeline maintains a stream time for the elements. The stream time is defined as the difference between the current clock time and the base time. When the pipeline goes to READY or a flushing seek is performed on it, the stream time is reset to 0. When the pipeline is set from PLAYING to PAUSED, the current clock time is sampled and used to configure the base time for the elements when the pipeline is set to PLAYING again. This default behaviour can be changed with the gst_pipeline_set_new_stream_time() method. When sending a flushing seek event to a GstPipeline (see seek), it will make sure that the pipeline is properly PAUSED and resumed as well as set the new stream time to 0 when the seek succeeded.

Nested Class Summary

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.Bin

Bin.DebugGraphDetails, Bin.DEEP_ELEMENT_ADDED, Bin.DEEP_ELEMENT_REMOVED, Bin.DO_LATENCY, Bin.ELEMENT_ADDED, Bin.ELEMENT_REMOVED

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.Element

Element.NO_MORE_PADS, Element.PAD_ADDED, Element.PAD_REMOVED

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.glib.GObject

GObject.GCallback, GObject.GInterface

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.glib.NativeObject

NativeObject.Initializer, NativeObject.TypeProvider, NativeObject.TypeRegistration<T extends NativeObject>

Field Summary

Fields

Modifier and Type	Field and Description
static String	GST_NAME
static String	GTYPE_NAME

Constructor Summary

Constructors

Modifier	Constructor and Description
	Pipeline() Creates a new instance of Pipeline with a unique name.
protected	Pipeline(NativeObject.Initializer init)
	Pipeline(String name) Creates a new instance of Pipeline with the given name.

Method Summary

Modifier and Type	Method and Description
boolean	getAutoFlushBus() Checks if the pipeline will automatically flush messages when going to the NULL state.
Bus	getBus() Gets the Bus this pipeline uses for messages.
Clock	getClock() Return the current Clock used by the pipeline.
long	queryDuration(Format format) Queries an element (usually top-level pipeline or playbin element) for the total stream duration in nanoseconds.
long	queryDuration(TimeUnit unit) Gets the time duration of the current media stream.
long	queryPosition(Format format) Queries an element (usually top-level pipeline or playbin element) for the stream position in nanoseconds.
long	queryPosition(TimeUnit unit) Gets the current position in the media stream.
Segment	querySegment() Gets the Segment for the current media stream in terms of time.
Segment	querySegment(Format format) Gets the Segment for the current media stream in terms of the specified Format.
boolean	seek(double rate, Format format, EnumSet<SeekFlags> seekFlags, SeekType startType, long start, SeekType stopType, long stop) Seeks to a new position in the media stream.
boolean	seek(double rate, Format format, Set<SeekFlags> seekFlags, SeekType startType, long start, SeekType stopType, long stop) Sends a seek event to an element.
boolean	seek(long time) Sets the position in the media stream to time in nanoseconds.
boolean	seek(long time, TimeUnit unit) Sets the current position in the media stream.
void	setAutoFlushBus(boolean flush) Usually, when a pipeline goes from READY to NULL state, it automatically flushes all pending messages on the bus, which is done for refcounting purposes, to break circular references.
boolean	setClock(Clock clock) Set the clock for pipeline.
void	useClock(Clock clock) Force the Pipeline to use the a specific clock.

Methods inherited from class org.freedesktop.gstreamer.Bin

add, addMany, connect, connect, connect, connect, connect, debugToDotFile, debugToDotFileWithTS, disconnect, disconnect, disconnect, disconnect, disconnect, getElementByName, getElementByNameRecurseUp, getElements, getElementsRecursive, getElementsSorted, getSinks, getSources, remove, removeMany

Methods inherited from class org.freedesktop.gstreamer.Element

addPad, connect, connect, connect, disconnect, disconnect, disconnect, getBaseTime, getContext, getFactory, getPads, getRequestPad, getSinkPads, getSrcPads, getStartTime, getState, getState, getState, getState, getStaticPad, isPlaying, link, linkFiltered, linkMany, linkPads, linkPadsFiltered, makeRawElement, pause, play, postMessage, query, ready, releaseRequestPad, removePad, seekSimple, sendEvent, setBaseTime, setCaps, setContext, setLockedState, setStartTime, setState, stop, syncStateWithParent, unlink, unlinkMany, unlinkPads

Methods inherited from class org.freedesktop.gstreamer.GstObject

addControlBinding, getAsString, getControlBinding, getName, getParent, hasActiveControlBindings, removeControlBinding, setAsString, setControlBindingDisabled, setControlBindingsDisabled, setName, suggestNextSync, syncValues, toString

Methods inherited from class org.freedesktop.gstreamer.glib.GObject

addCallback, connect, connect, disconnect, dispose, emit, emit, get, getPropertyDefaultValue, getPropertyMaximumValue, getPropertyMinimumValue, getRefCount, getTypeName, invalidate, listPropertyNames, removeCallback, set

Methods inherited from class org.freedesktop.gstreamer.glib.NativeObject

close, disown, equals, getPointer, getRawPointer, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

GST_NAME

public static final String GST_NAME

See Also:

Constant Field Values

GTYPE_NAME

public static final String GTYPE_NAME

See Also:

Constant Field Values

Constructor Detail

Pipeline

protected Pipeline(NativeObject.Initializer init)

Pipeline

public Pipeline()

Creates a new instance of Pipeline with a unique name.

Pipeline

public Pipeline(String name)

Creates a new instance of Pipeline with the given name.

Parameters:

name - The name used to identify this pipeline.

Method Detail

setAutoFlushBus

public void setAutoFlushBus(boolean flush)

Usually, when a pipeline goes from READY to NULL state, it automatically flushes all pending messages on the bus, which is done for refcounting purposes, to break circular references.

This means that applications that update state using (async) bus messages (e.g. do certain things when a pipeline goes from PAUSED to READY) might not get to see messages when the pipeline is shut down, because they might be flushed before they can be dispatched in the main thread. This behaviour can be disabled using this function.

It is important that all messages on the bus are handled when the automatic flushing is disabled else memory leaks will be introduced.

MT safe.

Parameters:

flush - whether or not to automatically flush the bus when the pipeline goes from READY to NULL state

getAutoFlushBus

public boolean getAutoFlushBus()

Checks if the pipeline will automatically flush messages when going to the NULL state.

MT safe.

Returns:

true if the pipeline automatically flushes messages.

setClock

public boolean setClock(Clock clock)

Set the clock for pipeline. The clock will be distributed to all the elements managed by the pipeline.

MT safe

Parameters:

clock - The Clock to use

Returns:

true if the clock could be set on the pipeline, false if some element did not accept the clock.

getClock

public Clock getClock()

Return the current Clock used by the pipeline.

Overrides:

getClock in class Element

Returns:

The Clock currently in use.

useClock

public void useClock(Clock clock)

Force the Pipeline to use the a specific clock. The pipeline will always use the given clock even if new clock providers are added to this pipeline.

MT safe

Parameters:

clock - The Clock to use. If clock is null, all clocking is disabled, and the pipeline will run as fast as possible.

getBus

public Bus getBus()

Gets the Bus this pipeline uses for messages.

Overrides:

getBus in class Element

Returns:

The Bus that this pipeline uses.

seek

public boolean seek(long time)

Sets the position in the media stream to time in nanoseconds.

Prefer use of Element.seekSimple(org.freedesktop.gstreamer.Format, java.util.Set, long).

Parameters:

time - The time to change the position to.

Returns:

true if seek is successful

seek

public boolean seek(long time,
                    TimeUnit unit)

Sets the current position in the media stream.

Prefer use of Element.seekSimple(org.freedesktop.gstreamer.Format, java.util.Set, long).

Parameters:

time - the time to change the position to.

unit - the TimeUnit the time is expressed in.

Returns:

true if seek is successful

seek

public boolean seek(double rate,
                    Format format,
                    EnumSet<SeekFlags> seekFlags,
                    SeekType startType,
                    long start,
                    SeekType stopType,
                    long stop)

Seeks to a new position in the media stream.

The start and stop values are expressed in format.

A rate of 1.0 means normal playback rate, 2.0 means double speed. Negative values means backwards playback. A value of 0.0 for the rate is not allowed and should be accomplished instead by PAUSING the pipeline.

A pipeline has a default playback segment configured with a start position of 0, a stop position of -1 and a rate of 1.0. The currently configured playback segment can be queried with #GST_QUERY_SEGMENT.

startType and stopType specify how to adjust the currently configured start and stop fields in segment. Adjustments can be made relative or absolute to the last configured values. A type of SeekType.NONE means that the position should not be updated.

When the rate is positive and start has been updated, playback will start from the newly configured start position.

For negative rates, playback will start from the newly configured stop position (if any). If the stop position if updated, it must be different from -1 for negative rates.

It is not possible to seek relative to the current playback position, to do this, PAUSE the pipeline, query the current playback position with queryPosition and update the playback segment current position with a SeekType.SET to the desired position.

Parameters:

rate - the new playback rate

format - the format of the seek values

seekFlags - the seek flags

startType - the type and flags for the new start position

start - the value of the new start position

stopType - the type and flags for the new stop position

stop - the value of the new stop position

Returns:

true if seek is successful

seek

public boolean seek(double rate,
                    Format format,
                    Set<SeekFlags> seekFlags,
                    SeekType startType,
                    long start,
                    SeekType stopType,
                    long stop)

Description copied from class: Element

Sends a seek event to an element. See SeekEvent for the details of the parameters. The seek event is sent to the element using the native equivalent of Element.sendEvent(org.freedesktop.gstreamer.event.Event).

Overrides:

seek in class Element

Parameters:

rate - the new playback rate

format - the format of the seek values

seekFlags - the seek flags

startType - the type and flags for the new start position

start - the value of the new start position

stopType - the type and flags for the new stop position

stop - the value of the new stop position

Returns:

true if seek operation succeeded. Flushing seeks will trigger a preroll, which will emit an ASYNC_DONE message

queryPosition

public long queryPosition(TimeUnit unit)

Gets the current position in the media stream.

Parameters:

unit - the TimeUnit to return the position in terms of.

Returns:

a time value representing the current position in units of unit.

queryPosition

public long queryPosition(Format format)

Description copied from class: Element

Queries an element (usually top-level pipeline or playbin element) for the stream position in nanoseconds. This will be a value between 0 and the stream duration (if the stream duration is known). This query will usually only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application will receive an ASYNC_DONE message on the pipeline bus when that is the case.

Overrides:

queryPosition in class Element

Parameters:

format - The Format to return the position in

Returns:

the current position or -1 if the query failed.

queryDuration

public long queryDuration(TimeUnit unit)

Gets the time duration of the current media stream.

Parameters:

unit - the TimeUnit to return the position in.

Returns:

The total duration of the current media stream.

queryDuration

public long queryDuration(Format format)

Description copied from class: Element

Queries an element (usually top-level pipeline or playbin element) for the total stream duration in nanoseconds. This query will only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application will receive an ASYNC_DONE message on the pipeline bus when that is the case.

If the duration changes for some reason, you will get a DURATION_CHANGED message on the pipeline bus, in which case you should re-query the duration using this function.

Overrides:

queryDuration in class Element

Parameters:

format - the Format to return the duration in

Returns:

the total duration of the current media stream, or -1 if the query failed

querySegment

public Segment querySegment()

Gets the Segment for the current media stream in terms of time.

Returns:

The information regarding the current Segment.

querySegment

public Segment querySegment(Format format)

Gets the Segment for the current media stream in terms of the specified Format.

Parameters:

format - the Format to return the segment in.

Returns:

The information regarding the current Segment.