-.TH "GStreamer" "1" "March 2001"
+.TH "GStreamer" "1" "April 2003"
.SH "NAME"
gst\-launch \- build and run a GStreamer pipeline
.SH "SYNOPSIS"
\fIGStreamer\fP pipelines.
In simple form, a PIPELINE\-DESCRIPTION is a list of
-elements separated by exclamation marks (!). Options may be appended to
-elements, in the form "option=value". A group of elements
-surrounded by curly braces {, } will be executed in a separate thread.
+elements separated by exclamation marks (!). Properties may be appended to
+elements, in the form \fIproperty=value\fR.
-Connections between non-consecutive elements are created by specifying
-a element names and pad names immediately before and after the
-exclamation mark, in the form "element0.sinkpad!element1.srcpad".
-The default name given to an element is the name of its class followed by
-an index. If the element names are omitted, the previous and next
-elements in the PIPELINE-DESCRIPTION will be used. If the pad names
-are omitted, a default pad of the correct type (source or sink) is
-found on the given element, typically named "src" or "sink".
+For a complete description of possible PIPELINE-DESCRIPTIONS see above under
+\fIpipeline description\fR or the GStreamer documentation.
-See the GStreamer documentation for a complete description of a
-a PIPELINE\-DESCRIPTION.
-
-.SH "EXAMPLES"
+.
+.SH "OPTIONS"
+.l
+\fIgst\-launch\fP accepts the following options:
+.TP 8
+.B \-\-help
+Print help synopsis and available FLAGS
+.TP 8
+.B \-v, \-\-silent
+Output status information
+.TP 8
+.B \-XTYPE, \-\-exclude=TYPE,
+Do not output status information of TYPE
+.TP 8
+.B \-oFILE, \-\-output=FILE
+Save XML representation of pipeline to FILE and exit
+.TP 8
+.B \-f, \-\-no_fault
+Do not install a fault handler
+.TP 8
+.B \-t, \-\-trace
+Print memory allocation traces. The feature must be enabled at compile time to
+work.
+.TP 8
+.B \-\-gst\-info\-mask=FLAGS
+\fIGStreamer\fP info flags to set (list with \-\-gst\-mask\-help)
+.TP 8
+.B \-\-gst\-debug\-mask=FLAGS
+\fIGStreamer\fP debugging flags to set (list with \-\-gst\-mask\-help)
+.TP 8
+.B \-\-gst\-mask=FLAGS
+\fIGStreamer\fP info and debugging flags to set (list with \-\-gst\-mask\-help)
+.TP 8
+.B \-\-gst\-plugin\-spew
+\fIGStreamer\fP info flags to set
+Enable printout of errors while loading \fIGStreamer\fP plugins
+.TP 8
+.B \-\-gst\-plugin\-path=PATH
+Add directories separated with ':' to the plugin search path
+.TP 8
+.B \-\-gst\-plugin\-load=PLUGINS
+Preload plugins specified in a comma-separated list. Another way to specify
+plugins to preload is to use the environment variable GST_PLUGIN_PATH
+.TP 8
+.B \-\-gst\-scheduler=SCHEDULER
+Use SCHEDULER as the default scheduler
+.TP 8
+.B \-\-gst\-registry=REGISTRY
+Use the file REGISTRY as registry instead of the default
-The examples below assume that you have the correct plug-ins available.
-In general, "osssink" can be substituted with another audio output
-plug-in such as "esdsink", "alsasink", or "artsdsink". Likewise,
-"xvideosink" can be substituted with "sdlvideosink" or "aasink".
+.SH "PIPELINE DESCRIPTION"
-.B Audio playback
+A pipeline consists \fIelements\fR and \fIlinks\fR. \fIElements\fR can be put
+into \fIbins\fR of different sorts. \fIElements\fR, \fIlinks\fR and \fIbins\fR
+can be specified in a pipeline description in any order.
-Play the mp3 music file "music.mp3" using a libmad-based plug-in and
-output to an OSS device:
+.B Elements
- gst\-launch filesrc location=music.mp3 ! mad ! osssink
+ELEMENTTYPE \fI[PROPERTY1 ...]\fR
-Play an Ogg Vorbis format file:
+Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
- gst\-launch filesrc location=music.ogg ! vorbisfile ! osssink
+.B Properties
-Play an mp3 file or stream retrieved via http:
+PROPERTY=VALUE ...
- gst\-launch httpsrc location=http://domain.com/music.mp3 ! mad ! osssink
+Sets the property to the specified value. You can use \fBgst\-inspect\fR(1) to
+find out about properties and allowed values of different elements.
+.br
+Enumeration properties can be set by name, nick or value.
-Play an mp3 file or stream using GNOME\-VFS:
+.B Bins
- gst\-launch gnomevfssrc location=music.mp3 ! mad ! osssink
+\fI[BINTYPE.]\fR ( \fI[PROPERTY1 ...]\fR PIPELINE-DESCRIPTION )
+.br
+{ \fI[PROPERTY1 ...]\fR PIPELINE-DESCRIPTION }
- gst\-launch gnomevfssrc location=http://domain.com/music.mp3 ! mad ! osssink
+Specifies that a bin of type BINTYPE is created and the given properties are
+set. Every element between the braces is put into the bin. Using curly braces
+(second line) is a short cut for using the first line and "thread" as the
+BINTYPE.
+.br
+Please not the dot that has to be used after the BINTYPE.
-Use GNOME\-VFS to play an mp3 file located on an SMB server:
+.B Links
- gst\-launch gnomevfssrc location=smb://computer/music.mp3 ! mad ! osssink
+\fI[[SRCELEMENT].[PAD1,...]]\fR ! \fI[[SINKELEMENT].[PAD1,...]]\fR
-.B Format conversion
+Links the element with name SRCELEMENT to the element with name SINKELEMENT.
+Names can be set on elements with the name property. If the name is omitted, the
+element that was specified directly in front of or after the link is used. This
+works across bins. If a padname is given, the link is done with these pads. If
+no pad names are given all possibilities are tried and a matching pad is used.
+If multiple padnames are given, both sides must have the same number of pads
+specified and multiple links are done in the given order.
+.br
+So the simplest link is a simple exclamation mark, that links the element to
+the left of it to the element right of it.
+.br
+Note that when specifying either pads or element names you have to include the
+dot or your syntax will be misinterpreted. This is a change to the old syntax
+used up to version 0.6 that allowed omitting the dot when only specifying a
+padname.
-Convert an mp3 music file to an Ogg Vorbis file:
+.SH "PIPELINE EXAMPLES"
- gst\-launch filesrc location=music.mp3 ! mad ! vorbisenc ! filesink location=music.ogg
+The examples below assume that you have the correct plug-ins available.
+In general, "osssink" can be substituted with another audio output
+plug-in such as "esdsink", "alsasink", or "artsdsink". Likewise,
+"xvideosink" can be substituted with "sdlvideosink" or "aasink".
-Alternatively, to convert to the FLAC format, use the command line:
+.B Audio playback
- gst\-launch filesrc location=claptrap.mp3 ! mad ! flacenc ! filesink location=test.flac
+.B
+ gst\-launch filesrc location=music.mp3 ! mad ! osssink
+.br
+Play the mp3 music file "music.mp3" using a libmad-based plug-in and
+output to an OSS device
+
+.B
+ gst\-launch filesrc location=music.ogg ! vorbisfile ! osssink
+.br
+Play an Ogg Vorbis format file
+
+.B
+ gst\-launch gnomevfssrc location=music.mp3 ! mad ! osssink
+.br
+.B
+ gst\-launch gnomevfssrc location=http://domain.com/music.mp3 ! mad ! osssink
+.br
+Play an mp3 file or an http stream using GNOME\-VFS
+
+.B
+ gst\-launch gnomevfssrc location=smb://computer/music.mp3 ! mad ! osssink
+.br
+Use GNOME\-VFS to play an mp3 file located on an SMB server
-.B Other
+.B Format conversion
-Plays a .WAV file:
+.B
+ gst\-launch filesrc location=music.mp3 ! mad ! vorbisenc ! filesink location=music.ogg
+.br
+Convert an mp3 music file to an Ogg Vorbis file
- gst\-launch filesrc location=music.wav ! wavparse ! osssink
+.B
+ gst\-launch filesrc location=music.mp3 ! mad ! flacenc ! filesink location=test.flac
+.br
+Convert to the FLAC format
-Convert a .WAV file into Ogg Vorbis (or mp3) file:
+.B Other
- gst\-launch filesrc location=music.wav ! wavparse ! vorbisenc ! filesink location=music.ogg
+.B
+ gst\-launch filesrc location=music.wav ! wavparse ! osssink
+.br
+Plays a .WAV file
- gst\-launch filesrc location=music.wav ! wavparse ! mpegaudio ! filesink location=music.mp3
+.B
+ gst\-launch filesrc location=music.wav ! wavparse ! vorbisenc ! filesink location=music.ogg
+.br
+.B
+ gst\-launch filesrc location=music.wav ! wavparse ! mpegaudio ! filesink location=music.mp3
+.br
+Convert a .WAV file into Ogg Vorbis (or mp3) file
Alternatively, if you have lame installed (and have the lame plug-in),
you can substitute lame for mpegaudio in the previous example. It gives
better results than mpegaudio.
-Rip all tracks from compact disc and convert them into a single mp3 file:
+.B
+ gst\-launch cdparanoia ! mpegaudio ! filesink location=cd.mp3
+.br
+Rip all tracks from compact disc and convert them into a single mp3 file
- gst\-launch cdparanoia ! mpegaudio ! filesink location=cd.mp3
-
-Using gst\-inspect, it is possible to discover settings for cdparanoia
+Using \fBgst\-inspect\fR(1), 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:
-
- gst\-launch osssrc ! vorbisenc ! filesink location=input.ogg
+.B
+ gst\-launch osssrc ! vorbisenc ! filesink location=input.ogg
+.br
+Record sound from your audio input and encode it into an ogg file
.B Video
+.B
+ gst\-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! mpegdemux ! mpeg2dec ! xvideosink
+.br
Display only the video portion of an MPEG-1 video file, outputting to
-an X display window (The "queue" element is necessary to buffer data
-between the threads):
-
- gst\-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! mpegdemux video_%02d!src { queue ! mpeg2dec ! xvideosink }
+an X display window
+.B
+ gst\-launch filesrc location=/flflfj.vob ! mpegdemux ! mpeg2dec ! sdlvideosink
+.br
Display the video portion of a .vob file (used on DVDs), outputting to
-an SDL window:
-
- gst\-launch filesrc location=/flflfj.vob ! mpegdemux video_%02d!src { queue ! mpeg2dec ! sdlvideosink }
-
-Play both video and audio portions of an MPEG movie:
+an SDL window
- gst\-launch filesrc location=movie.mpg ! mpegdemux video_%02d!src { queue ! mpeg2dec ! sdlvideosink } mpegdemux0.audio_%02d!src { queue ! mad ! osssink }
+.B
+ gst\-launch filesrc location=movie.mpg ! mpegdemux name=demuxer ! mpeg2dec ! sdlvideosink demuxer. ! mad ! osssink
+.br
+Play both video and audio portions of an MPEG movie
-Play an AVI movie:
+.B
+ gst\-launch filesrc location=movie.mpg ! mpegdemux name=demuxer ! { queue ! mpeg2dec ! sdlvideosink } { demuxer. ! queue ! mad ! osssink }
+.br
+Use threaded output to improve synchronization and smoothness. Threads require
+queues for buffering on thread boundaries
- gst\-launch filesrc location=movie.avi ! avidemux video_%02d!src { queue ! windec ! sdlvideosink }
+.B
+ gst\-launch filesrc location=movie.avi ! avidemux name=demuxer ! { queue ! ffdecall ! sdlvideosink } { demuxer. ! queue ! mad ! osssink }
+.br
+Play an AVI movie
.B Network streaming
An MPEG\-1 system stream can be streamed via RTP from one machine to
-another. On the receiver, execute:
-
- gst\-launch rtprecv media_type=mpeg1_sys ! mpegdemux video_%02d!src { queue ! mpeg2dec ! xvideosink } mpegdemux0.audio_%02d!src { queue ! mad ! osssink }
+another.
-On the transmitter, execute:
+.B
+ gst\-launch rtprecv media_type=mpeg1_sys ! mpegdemux name=demuxer ! { queue ! mpeg2dec ! xvideosink } { demuxer. ! queue ! mad ! osssink }
+.br
+Use this command on the receiver
- gst\-launch filesrc location=mpeg1system.mpeg ! mpegparse ! rtpsend ip=IPorHostname
+.B
+ gst\-launch filesrc location=mpeg1system.mpeg ! mpegparse ! rtpsend ip=IPorHostname
+.br
+This command would be run on the transmitter
.B Diagnostic
-Generate a null stream and ignore it:
+.B
+ gst\-launch fakesrc ! fakesink
+.br
+Generate a null stream and ignore it
- gst\-launch fakesrc ! fakesink
+.B
+ gst\-launch sinesrc ! osssink
+.br
+Generate a pure tone to test the audio output
-Generate a pure tone to test the audio output:
+.B
+ gst\-launch videotestsrc ! xvideosink
+.br
+Generate a familiar test pattern to test the video output
- gst\-launch sinesrc ! osssink
+.B Automatic linking
-Generate a familiar test pattern to test the video output:
+You can use the spider element to automatically select the right elements to get
+a working pipeline.
- gst\-launch videotestsrc ! xvideosink
+.B
+ gst\-launch filesrc location=musicfile ! spider ! osssink
+.br
+Play any supported audio format
+
+.B
+ gst\-launch filesrc location=videofile ! spider name=spider ! osssink spider. ! xvideosink
+.br
+.B
+ gst\-launch filesrc location=videofile ! spider name=spider ! { queue ! osssink } { spider. ! queue ! xvideosink }
+.br
+Play any supported video format with video and audio output. The second pipeline
+uses threaded output.
.
-.SH "OPTIONS"
-.l
-\fIgst\-launch\fP accepts the following options:
-.TP 8
-.B \-\-help
-Print help synopsis and available FLAGS
-.TP 8
-.B \-\-silent
-Do not output status information
-.TP 8
-.B \-\-exclude=TYPE, \-XTYPE
-Do not output status information of TYPE
-.TP 8
-.B \-\-output=FILE, \-oFILE
-Save XML representation of pipeline to FILE and exit
-.TP 8
-.B \-\-gst\-info\-mask=FLAGS
-\fIGStreamer\fP info flags to set (list with \-\-help)
-.TP 8
-.B \-\-gst\-debug\-mask=FLAGS
-\fIGStreamer\fP debugging flags to set (list with \-\-help)
-.TP 8
-.B \-\-gst\-mask=FLAGS
-\fIGStreamer\fP info and debugging flags to set (list with \-\-help)
-.TP 8
-.B \-\-gst\-plugin\-spew
-\fIGStreamer\fP info flags to set
-Enable printout of errors while loading \fIGStreamer\fP plugins
-.TP 8
-.B \-\-gst\-plugin\-path=PATH
-Add directories separated with ':' to the plugin search path
.SH "SEE ALSO"
.BR gst\-complete (1),
.BR gst\-register (1),
projects / platform / upstream / gstreamer.git / commitdiff