gst-launch-0.8(1) User Commands gst-launch-0.8(1)
NAME
gst-launch-0.8, gst-launch - build and run a GStreamer pipeline
SYNOPSIS
gst-launch-0.8 [--exclude=type] [--iterations=int] [--no-fault] [-output-=file] [--tags] [--trace] [--verbose] [gst-std-options] pipeline-
description
gst-launch [--exclude=type] [--iterations=int] [--no-fault] [-output-=file] [--tags] [--trace] [--verbose] [gst-std-options] [--gst-list-
mm] [--gst-mm=string] [--print] pipeline-description
DESCRIPTION
gst-launch-0.8 builds and runs basic GStreamer pipelines.
In simple form, a pipeline-description is a list of elements separated by exclamation marks (!). Properties can be appended to elements, in
the form property=value.
For a complete description of possible values for pipeline-description, see the GStreamer documentation.
gst-launch is a wrapper script that runs the latest installed version of gst-launch-X.X. For example, if both gst-launch-0.7 and gst-
launch-0.8 are installed on your system, gst-launch runs gst-launch-0.8.
OPTIONS
The following options are supported by gst-launch-0.8 and gst-launch:
--exclude=type Do not output status information of specified type. You can also use -X to specify this option.
--iterations=int Stop processing after int iterations. You can also use -i to specify this option.
--no-fault Do not install a fault handler. You can also use -f to specify this option.
-output-=file Save XML representation of pipeline to file, then exit. You can also use -o to specify this option.
--tags Output tags, also known as metadata. You can also use -t to specify this option.
--trace Print alloc trace, if enabled at compile time. You can also use -T to specify this option.
--verbose Output status information and property notifications. You can also use -v to specify this option.
gst-std-options Standard options available for use with most GStreamer applications. See gst-std-options(5) for more
information.
The following options are supported by gst-launch only:
--gst-list-mm List found major/minor versions. This option displays the versions that are available.
--gst-mm=string Force major/minor version. This option enables you to specify a specific version to run, if you do not want to run the
default version.
--print Print wrapped command line. This option displays the command that will be run, and then runs the command.
EXTENDED DESCRIPTION
Pipeline Description
A pipeline consists of elements and links.
Elements can be put into bins of different sorts.
Elements, links, and bins can be specified in a pipeline description in any order.
Elements
To create an element of type elementtype and set the properties:
elementtype [property1 ...]
To set a property to a specified value:
property=value ...
Use gst-inspect to find out about properties and allowed values of different elements. Enumeration properties can be set by name, nick, or
value.
Bins
To create a bin of type bintype and set the properties:
[bintype.] ( [property1 ...] pipeline-description )
{ [property1 ...] pipeline-description }
Every element between the parentheses is put into the bin. Using curly braces (second line) is a shortcut for using the first line and
"thread" as the bintype.
Note the dot that must be included after the bintype.
Links
To link the element named srcelement to the element named sinkelement, using the capabilities specified in caps as a filter:
[[srcelement].[pad1,...]] ! [[sinkelement].[pad1,...]]
[[srcelement].[pad1,...]] ! caps !
[[srcelement].[pad1,...]]
Element names can be set using the name property. If the name is omitted, the element that was specified directly before or after the link
is used. This works across bins. If a pad name is given, the link is created with these pads. If no pad names are given, all possibilities
are tried and a matching pad is used. If multiple pad names are given, both sides must have the same number of pads specified and multiple
links are created in the given order. The simplest link is a simple exclamation mark, that links the element to the left of it to the ele-
ment to the right of it.
Note that when specifying either pads or element names, you must include the dot or your syntax will be misinterpreted. This is a change to
the old syntax used until version 0.6, which allowed you to omit the dot when only specifying a pad name.
Capabilities
To create a capability with the given mimetype and optionally with given properties:
mimetype [, property[, property ...]]] [; caps[; caps ...]]
The mimetype can be escaped using " or '. If you want to chain capabilities, you can add more caps in the same format afterwards.
To set the specified property in capabilities:
name[:type]=value
In lists and ranges:
[type]=value
name is an alphanumeric value and type can have the following case-insensitive values:
o i or int for integer values or ranges
o f or float for float values or ranges
o 4 or fourcc for FOURCC values
o b, bool, or boolean for boolean values
o s, str, or string for strings
o l or list for lists
If no type is given, the following order is tried: integer, float, boolean, string.
Integer values must be parsable by strtol(3C), floats by strtod().
FOURCC values can either be integers or strings.
Boolean values are (case insensitive) yes, no, true, or false, and can like strings be escaped with " or '.
Ranges are in the following format:
[ property, property ]
Lists use the following format:
( property [, property ...] )
Pipeline Control
A pipeline can be controlled by signals. SIGUSR2 stops the pipeline (GST_STATE_NULL); SIGUSR1 puts the pipeline back to play
(GST_STATE_PLAYING). By default, the pipeline starts in the playing state.
There are currently no signals defined to go into the ready or pause (GST_STATE_READY and GST_STATE_PAUSED) state explicitly.
EXAMPLES
The examples below assume that you have the correct plugins available. In general, "osssink" can be substituted with another audio output
plugin such as "esdsink", "alsasink", or "artsdsink". Likewise, "xvideosink" can be substituted with "sdlvideosink" or "aasink".
Example 1: Audio Playback
Play the mp3 music file "music.mp3" using a libmad-based plugin and output to an OSS device:
example% gst-launch filesrc location=music.mp3 ! mad ! osssink
Play an Ogg Vorbis format file:
example% gst-launch filesrc location=music.ogg ! oggdemux !
vorbisdec ! audioconvert ! osssink
Play an mp3 file or an http stream using GNOME-VFS:
example% gst-launch gnomevfssrc location=music.mp3 ! mad ! osssink
example% gst-launch gnomevfssrc
location=http://domain.com/music.mp3 ! mad ! osssink
Use GNOME-VFS to play an mp3 file located on an SMB server:
example% gst-launch gnomevfssrc
location=smb://computer/music.mp3 ! mad ! osssink
Example 2: Format Conversion
Convert an mp3 music file to an Ogg Vorbis file:
example% gst-launch filesrc location=music.mp3 ! mad !
vorbisenc ! filesink location=music.ogg
Convert to the FLAC format:
example% gst-launch filesrc location=music.mp3 ! mad !
flacenc ! filesink location=test.flac
Example 3: Other
Play a .WAV file:
example% gst-launch filesrc location=music.wav ! wavparse !
osssink
Convert a .WAV file into Ogg Vorbis (or mp3) file:
example% gst-launch filesrc location=music.wav ! wavparse !
vorbisenc ! filesink location=music.ogg
example% gst-launch filesrc location=music.wav ! wavparse !
mpegaudio ! filesink location=music.mp3
Alternatively, if you have lame installed and have the lame plugin, you can substitute lame for mpegaudio in the previous example. lame
gives better results than mpegaudio.
Rip all tracks from compact disc and convert them into a single mp3 file:
example% gst-launch cdparanoia ! mpegaudio ! filesink
location=cd.mp3
Using gst-inspect, it is possible to discover settings for cdparanoia that will tell it to rip individual tracks.
Record sound from your audio input and encode it into an ogg file:
example% gst-launch osssrc ! vorbisenc ! filesink
location=input.ogg
Example 4: Video
Display only the video portion of an MPEG-1 video file, outputting to an X display window:
example% gst-launch filesrc
location=JB_FF9_TheGravityOfLove.mpg ! mpegdemux ! mpeg2dec
! xvideosink
Display the video portion of a .vob file (used on DVDs), outputting to an SDL window:
example% gst-launch filesrc location=/flflfj.vob ! mpegdemux
! mpeg2dec ! sdlvideosink
Play both video and audio portions of an MPEG movie:
example% gst-launch filesrc location=movie.mpg ! mpegdemux
name=demuxer ! mpeg2dec ! sdlvideosink demuxer. ! mad !
osssink
Use threaded output to improve synchronization and smoothness (threads require queues for buffering on thread boundaries):
example% gst-launch filesrc location=movie.mpg ! mpegdemux
name=demuxer ! { queue ! mpeg2dec ! sdlvideosink } {
demuxer. ! queue ! mad ! osssink }
Play an AVI movie:
example% gst-launch filesrc location=movie.avi ! avidemux
name=demuxer ! { queue ! ffdecall ! sdlvideosink } {
demuxer. ! queue ! mad ! osssink }
Example 5: Network Streaming
An MPEG-1 system stream can be streamed via RTP from one machine to another.
Run the following command on the receiver:
example% gst-launch rtprecv media_type=mpeg1_sys ! mpegdemux
name=demuxer ! { queue ! mpeg2dec ! xvideosink } { demuxer.
! queue ! mad ! osssink }
Run the following command on the transmitter:
example% gst-launch filesrc location=mpeg1system.mpeg ! mpegparse
! rtpsend ip=IPorHostname
Example 6: Diagnostic
Generate a null stream and ignore it:
example% gst-launch fakesrc ! fakesink
Generate a pure tone to test the audio output:
example% gst-launch sinesrc ! osssink
Generate a familiar test pattern to test the video output:
example% gst-launch videotestsrc ! xvideosink
Example 7: Automatic Linking
You can use the spider element to automatically select the right elements to get a working pipeline.
Play any supported audio format:
example% gst-launch filesrc location=musicfile ! spider ! osssink
Play any supported video format with video and audio output:
example% gst-launch filesrc location=videofile ! spider
name=spider ! osssink spider. ! xvideosink
As previous example, but use threaded output:
example% gst-launch filesrc location=videofile ! spider
name=spider ! { queue ! osssink } { spider. ! queue ! xvideosink }
Example 8: Filtered Connections
These examples show how to use filtered capabilities.
Show a test image and use the YUY2 or YV12 video format for this:
example% gst-launch videotestsrc ! video/raw,
format:fourcc=YUY2; video/raw, format:fourcc=YV12 ! xvideosink
Playback currently recorded audio, and force usage of signed 16 to 32 bit samples:
example% gst-launch osssrc ! "audio/raw", format=int,
width=[16, 32], depth=(16, 24, 32), signed=TRUE ! osssink
Example 9: Running the Wrapper Script and Displaying the Command Name
example% gst-launch --print
/usr/bin/gst-launch-0.8
FILES
The following files are used by this application:
/usr/bin/gst-launch-0.8 Executable to build and run a GStreamer pipeline
/usr/bin/gst-launch Wrapper script that runs the latest installed version of gst-launch-X.X
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Availability |SUNWgnome-media |
+-----------------------------+-----------------------------+
|Interface stability |External |
+-----------------------------+-----------------------------+
SEE ALSO
gst-complete(1), gst-compprep(1), gst-feedback(1), gst-inspect(1), gst-launch-ext(1), gst-md5sum(1), gst-register(1), gst-thumbnail(1),
gst-typefind(1), gst-xmlinspect(1), gst-xmllaunch(1), gstreamer-properties(1), libgstreamer-0.8(3), libgstgetbits(3), gst-std-options(5)
NOTES
Original man page written by the GStreamer team at http://gstreamer.net/.
Updated by Brian Cameron, Sun Microsystems Inc., 2004.
SunOS 5.10 14 Oct 2004 gst-launch-0.8(1)