mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-30 12:10:37 +00:00
166 lines
8 KiB
Text
166 lines
8 KiB
Text
GstParse
|
|
========
|
|
|
|
This document describes how GstParse works. GstParse is the infrastructure used
|
|
to describe pipelines \(or parts thereof) as a string. This powerful yet easy
|
|
language is for example by the gst-launch command-line utility or in the GConf
|
|
keys that are used by various applications, such as Rhythmbox or Gst-Player.
|
|
\(You can find these keys in /system/gstreamer/default in GConf)
|
|
|
|
The following examples will show commands for gst-launch. Please note that some
|
|
characters need to be escaped when the pipeline is written in the shell as
|
|
gst-launch command.
|
|
|
|
If you want to debug the GstParse part of an application, you can start it with
|
|
the --gst-mask=0x10000 command line option.
|
|
|
|
|
|
Basics
|
|
======
|
|
|
|
Elements
|
|
--------
|
|
The most basic thing you specify in a pipeline are elements. You add an element
|
|
by the name of its type, so "filesrc" will add a file source and "identity" will
|
|
add an identity element.
|
|
Gstparse will put all these elements into a toplevel pipeline element.
|
|
example:#> gst-launch filesrc identity
|
|
This adds a filesrc and an identity element to a pipeline. Of course this
|
|
pipeline will not run, because the elements are not yet connected.
|
|
|
|
Properties
|
|
----------
|
|
You can set element properties by specifying them directly after the element in
|
|
the form name=value \(you need to escape here) or name="value" \(you only need to
|
|
escape the " sign.
|
|
example:#> gst-launch filesrc name=source location="music.mp3"
|
|
This adds a filesrc element with the name "source" pointing to the location
|
|
music.mp3 to your pipeline. \(This pipeline doesn't work either.)
|
|
It's a good idea to set the name property on important elements, because if they
|
|
are referenced \(see below), they will be referenced by name and the name of an
|
|
element is unspecified if it wasn't set before.
|
|
Please note that not all properties can be set yet. You might get a warning like
|
|
property "myproperty" in element myelement cannot be set
|
|
In that case, please file a feature request. We can't guess all properties in
|
|
advance.
|
|
|
|
Bins
|
|
----
|
|
If you want to add bins to your pipeline, you can do so by specifying
|
|
<bintype> . ( <properties> <elements> )
|
|
in your pipeline. This adds a bin to your pipeline and puts all elements that
|
|
are specified between the brackets inside this bin. You can specify properties
|
|
of the bin directly after the opening bracket.
|
|
There are to special bins: if you don't specify a bintype and no dot either, the
|
|
type of the bin defaults to "bin". And you can use curly brackets { } to get a
|
|
bin of type "thread".
|
|
example:#> gst-launch \( { fakesrc pipeline . \( fakesink \) } \)
|
|
This will put a fakesrc element inside a thread inside a bin and a fakesink into
|
|
a pipeline element inside the thread inside the bin.
|
|
Please note that this pipeline would not work, even if the elements were
|
|
connected properly, because the pipeline only specifies one top level element,
|
|
the element is not put inside a pipeline but returned directly. So if you don't
|
|
want your elements be put into a pipeline, just add a bin of whatever type you
|
|
wish around the pipeline.
|
|
|
|
Links
|
|
-----
|
|
What would a pipeline be without the ability to link the elements?
|
|
Well it's very easy. Just put the link sign, an exclamation mark, between two
|
|
elements and they will be linked.
|
|
example:#> gst-launch fakesrc ! fakesink
|
|
This will put the two elements into a pipeline and connect the fakesrc to the
|
|
fakesink. This is the first pipeline that should run - and run it will until you
|
|
terminate it.
|
|
You can't however control which pads are linked, you can reference the pad\(s)
|
|
you want to connect by name with a dot before the name.
|
|
example:#> gst-launch fakesrc .src ! fakesink
|
|
example:#> gst-launch fakesrc ! .sink fakesink
|
|
example:#> gst-launch fakesrc .src ! .sink fakesink
|
|
These examples will all do the exact same thing as the example before. You have
|
|
however referenced the pads you wanted to connect in different ways.
|
|
Another way to reference is to reference the element you want to connect, too.
|
|
In this case you have to add the element name before the dot. You can even not
|
|
reference the pad and only the element name, to connect any pad.
|
|
example:#> gst-launch fakesrc name=src fakesink name=sink src.src ! sink.sink
|
|
example:#> gst-launch fakesrc name=src ! sink.sink fakesink name=sink
|
|
example:#> gst-launch fakesrc name=src src. ! fakesink name=sink
|
|
example:#> gst-launch fakesrc name=src fakesink name=sink src. ! sink.
|
|
These examples all do the same as the other ones. Please note that we specified
|
|
the element name property to be sure to reference the right element.
|
|
In these examples you may have noticed, that an omitted element name on a link
|
|
automatically means the element directly in front of / after the link is used
|
|
to create the link to save you some typing work and that not specifying a pad
|
|
name will automatically create 1 connection between the two elements. If more
|
|
than one connection was possible you might end up surprised.
|
|
You may even specify pad lists to connect elements. They are separated by
|
|
commas.
|
|
example:#> gst-launch fakesrc ! tee name=tee1 .src0,src1 ! .sink0, sink1 aggregator ! fakesink
|
|
example:#> gst-launch fakesrc ! tee name=tee aggregator name=aggregator ! fakesink tee.src0,src1 ! aggregator.sink0, sink1
|
|
example:#> gst-launch fakesrc ! tee name=tee .src0 ! .sink0 aggregator name=aggregator ! fakesink tee.src1 ! aggregator.sink1
|
|
These will all do the same. They will connect the tee twice to the aggregator.
|
|
|
|
|
|
Examples
|
|
========
|
|
|
|
Audio playback
|
|
--------------
|
|
The most common audio pipeline for playing back an mp3 file is this:
|
|
example:#> gst-launch filesrc location=/path/to/file.mp3 ! mad ! osssink
|
|
|
|
You can however improve on this by adding visualization:
|
|
example:#> gst-launch filesrc location=/path/to/file.mp3 ! mad ! tee name=tee ! osssink tee.src%d ! goom ! colorspace ! xvideosink
|
|
Note that the reference of the tee element has a pad named "src%d". This is as
|
|
used by printf and is a useful way to specify request pads where you don't know
|
|
how this pad is named. Yes, the pad name could have been omitted anyway.
|
|
|
|
If you have jerky playback you might want to use this pipeline threaded so audio
|
|
and video have less chance of problems and you have a little buffer:
|
|
example:#> gst-launch filesrc location=/path/to/file.mp3 ! mad ! tee name=tee ! { queue ! osssink } tee name=tee { ! queue ! osssink } { tee. ! queue ! goom ! colorspace ! xvideosink }
|
|
Remember to put queues at thread boundaries or it will not work.
|
|
|
|
Video playback
|
|
--------------
|
|
The basic pipeline to playback a standard mpeg video would be this:
|
|
example:#> gst-launch filesrc location=/path/to/file.mpeg ! mpegdemux name=demux ! mad ! osssink demux. ! mpeg2dec ! xvideosink
|
|
|
|
Or using threads for better playback:
|
|
example:#> gst-launch filesrc location=/path/to/file.mpeg ! mpegdemux name=demux ! { queue ! mad ! osssink } demux. ! { queue ! mpeg2dec ! xvideosink }
|
|
|
|
For a DivX avi, this might work:
|
|
example:#> gst-launch filesrc location=/path/to/file.avi ! avidemux name=demux ! { queue ! mad ! osssink } { demux. ! ffdec_msmpeg4 ! xvideosink }
|
|
|
|
|
|
If these don't work the video might need different treatment. You should skip to
|
|
the autoplugger part.
|
|
Please be aware of the fact that the mpegdemux element uses pads that are not
|
|
always available. GstParse will wait for them to become available and disable
|
|
the elements that need to be connected by disabling their state until the link
|
|
can be established.
|
|
|
|
Autoplugging
|
|
------------
|
|
You can also use the spider element for autoplugging. This will take care of
|
|
selecting the right elements for you. Just use this pipeline for all your needs:
|
|
example:#> gst-launch filesrc location=/path/to/anything ! spider name=spider ! { queue ! osssink } { spider. ! queue ! xvideosink }
|
|
|
|
To throw you out
|
|
----------------
|
|
Finally the current experimental pipeline that powers the gst-player specified
|
|
as a simple (ahem...) command line:
|
|
example:#> gst-launch pipeline. \( { filesrc location=/path/to/anything ! spider name=spider ! { queue ! volume ! \( tee name=tee ! { queue ! \( goom \) ! colorspace ! \( xvideosink \) } tee. ! { queue ! \( osssink \) } \) } spider. ! { queue ! colorspace \( xvideosink \) } } \)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|