org.gstreamer
Class Pipeline

java.lang.Object
  extended by org.gstreamer.lowlevel.NativeValue
      extended by org.gstreamer.lowlevel.Handle
          extended by org.gstreamer.lowlevel.NativeObject
              extended by org.gstreamer.lowlevel.RefCountedObject
                  extended by org.gstreamer.GObject
                      extended by org.gstreamer.GstObject
                          extended by org.gstreamer.Element
                              extended by org.gstreamer.Bin
                                  extended by org.gstreamer.Pipeline
Direct Known Subclasses:
PlayBin

public class Pipeline
extends Bin

A Pipeline is a special Bin used as the toplevel 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 behavour for managing seek events (see seek).

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.gstreamer.Bin
Bin.ELEMENT_ADDED, Bin.ELEMENT_REMOVED
 
Nested classes/interfaces inherited from class org.gstreamer.Element
Element.HANDOFF, Element.NO_MORE_PADS, Element.PAD_ADDED, Element.PAD_REMOVED
 
Nested classes/interfaces inherited from class org.gstreamer.GObject
GObject.GCallback
 
Nested classes/interfaces inherited from class org.gstreamer.lowlevel.NativeObject
org.gstreamer.lowlevel.NativeObject.Initializer
 
Field Summary
 
Fields inherited from class org.gstreamer.lowlevel.NativeObject
defaultInit, ownsHandle
 
Constructor Summary
Pipeline()
          Creates a new instance of Pipeline with a unique name.
Pipeline(org.gstreamer.lowlevel.NativeObject.Initializer init)
           
Pipeline(java.lang.String name)
          Creates a new instance of Pipeline with the given name.
 
Method Summary
 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.
 boolean isPlaying()
          Tests if the Pipeline is currently playing.
static Pipeline launch(java.lang.String... pipelineDecription)
          Creates a pipeline from a text pipeline description.
static Pipeline launch(java.lang.String pipelineDecription)
          Creates a pipeline from a text pipeline description.
 void pause()
          Tells the Pipeline to pause playing the media stream.
 void play()
          Tells the Pipeline to start playing the media stream.
 ClockTime queryDuration()
          Gets the time duration of the current media stream.
 long queryDuration(java.util.concurrent.TimeUnit unit)
          Gets the time duration of the current media stream.
 ClockTime queryPosition()
          Gets the current position in the media stream in units of time.
 long queryPosition(Format format)
          Gets the current position in terms of the specified Format.
 long queryPosition(java.util.concurrent.TimeUnit unit)
          Gets the current position in the media stream.
 void seek(ClockTime time)
          Sets the position in the media stream to time.
 void seek(double rate, Format format, int flags, SeekType startType, long start, SeekType stopType, long stop)
          Seeks to a new position in the media stream.
 void seek(long time, java.util.concurrent.TimeUnit unit)
          Sets the current position in the media stream.
 void setAutoFlushBus(boolean flush)
          Sets this pipeline to automatically flush Bus messages or not.
 boolean setClock(Clock clock)
          Set the clock for pipeline.
 void stop()
          Tells the Pipeline to pause playing the media stream.
 void useClock(Clock clock)
          Force the Pipeline to use the a specific clock.
 
Methods inherited from class org.gstreamer.Bin
add, addMany, connect, connect, disconnect, disconnect, getElementByInterface, getElementByName, getElementByNameRecurseUp, getElements, getElementsRecursive, getElementsSorted, getSinks, getSources, remove, removeMany
 
Methods inherited from class org.gstreamer.Element
addPad, connect, connect, connect, connect, disconnect, disconnect, disconnect, disconnect, getBaseTime, getFactory, getPad, getPads, getRequestPad, getSinkPads, getSrcPads, getState, getState, getState, getState, getStaticPad, link, link, linkMany, linkPads, linkPadsFiltered, makeRawElement, postMessage, releaseRequestPad, removePad, sendEvent, setCaps, setState, unlink, unlinkMany, unlinkPads
 
Methods inherited from class org.gstreamer.GstObject
addListenerProxy, getName, initializer, initializer, objectFor, objectFor, ref, removeListenerProxy, setName, steal, toString, unref
 
Methods inherited from class org.gstreamer.GObject
addCallback, connect, connect, connect, disconnect, disconnect, disposeNativeHandle, g_signal_connect, get, invalidate, objectFor, removeCallback, set
 
Methods inherited from class org.gstreamer.lowlevel.NativeObject
classFor, disown, dispose, equals, finalize, getNativeAddress, handle, hashCode, initializer, instanceFor, isDisposed, nativeValue, objectFor, objectFor
 
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Pipeline

public Pipeline(org.gstreamer.lowlevel.NativeObject.Initializer init)

Pipeline

public Pipeline()
Creates a new instance of Pipeline with a unique name.


Pipeline

public Pipeline(java.lang.String name)
Creates a new instance of Pipeline with the given name.

Parameters:
name - The name used to identify this pipeline.
Method Detail

launch

public static Pipeline launch(java.lang.String pipelineDecription)
Creates a pipeline from a text pipeline description. This function allows creation of a pipeline based on the syntax used in the gst-launch utillity.

Parameters:
pipelineDecription - the command line describing the pipeline
Returns:
The new Pipeline.

launch

public static Pipeline launch(java.lang.String... pipelineDecription)
Creates a pipeline from a text pipeline description. This function allows creation of a pipeline based on the syntax used in the gst-launch utillity.

Parameters:
pipelineDecription - An array of strings containing the command line describing the pipeline.
Returns:
The new Pipeline.

setAutoFlushBus

public void setAutoFlushBus(boolean flush)
Sets this pipeline to automatically flush Bus messages or not.

Parameters:
flush - true if automatic flushing is desired, else false.

getAutoFlushBus

public boolean getAutoFlushBus()
Checks if the pipeline will automatically flush messages when going to the NULL state.

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 void seek(ClockTime time)
Sets the position in the media stream to time.

Parameters:
time - The time to change the position to.

seek

public void seek(long time,
                 java.util.concurrent.TimeUnit unit)
Sets the current position in the media stream.

Parameters:
time - the time to change the position to.
unit - the TimeUnit the time is expressed in.

seek

public void seek(double rate,
                 Format format,
                 int flags,
                 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.

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
flags - the optional 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

queryPosition

public ClockTime queryPosition()
Gets the current position in the media stream in units of time.

Returns:
the ClockTime representing the current position.

queryPosition

public long queryPosition(java.util.concurrent.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)
Gets the current position in terms of the specified Format.

Parameters:
format - The Format to return the position in.
Returns:
The current position.

queryDuration

public ClockTime queryDuration()
Gets the time duration of the current media stream.

Returns:
The total duration of the current media stream.

queryDuration

public long queryDuration(java.util.concurrent.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.

isPlaying

public boolean isPlaying()
Tests if the Pipeline is currently playing.

Returns:
true if the Pipeline is currently playing

play

public void play()
Tells the Pipeline to start playing the media stream.


pause

public void pause()
Tells the Pipeline to pause playing the media stream.


stop

public void stop()
Tells the Pipeline to pause playing the media stream.