-.TH "GStreamer" "1" "April 2003"
+.TH "GStreamer" "1" "May 2007"
.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 (!). Properties may be appended to
+elements separated by exclamation marks (!). Properties may be appended to
elements, in the form \fIproperty=value\fR.
-For a complete description of possible PIPELINE-DESCRIPTIONS see above under
-\fIpipeline description\fR or the GStreamer documentation.
+For a complete description of possible PIPELINE-DESCRIPTIONS see the section
+\fIpipeline description\fR below or consult the GStreamer documentation.
+Please note that \fIgst\-launch\fP is primarily a debugging tool for
+developers and users. You should not build applications on top of it. For
+applications, use the gst_parse_launch() function of the GStreamer API as an
+easy way to construct pipelines from pipeline descriptions.
.
.SH "OPTIONS"
.l
.B \-\-help
Print help synopsis and available FLAGS
.TP 8
-.B \-v, \-\-silent
+.B \-v, \-\-verbose
Output status information
.TP 8
-.B \-XTYPE, \-\-exclude=TYPE,
-Do not output status information of TYPE
+.B \-m, \-\-messages
+Output messages posted on the pipeline's bus
.TP 8
-.B \-oFILE, \-\-output=FILE
+.B \-t, \-\-tags
+Output tags (also known as metadata)
+.TP 8
+.B \-o FILE, \-\-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
+.B \-T, \-\-trace
Print memory allocation traces. The feature must be enabled at compile time to
work.
.TP 8
-.B \-i, \-\-iterations=N
-Stop processing after N iterations.
.
.SH "GSTREAMER OPTIONS"
Prints the version string of the \fIGStreamer\fP core library.
.TP 8
.B \-\-gst\-fatal\-warnings
-Causes \fIGStreamer\fP to abort if a warning message occurs.
+Causes \fIGStreamer\fP to abort if a warning message occurs. This is equivalent
+to setting the environment variable G_DEBUG to 'fatal_warnings' (see the
+section \fIenvironment variables\fR below for further information).
.TP 8
.B \-\-gst\-debug=STRING
-\fIGStreamer\fP debugging flags to set (list with \-\-gst\-mask\-help)
+A comma separated list of category_name:level pairs to specify debugging levels
+for each category. Level is in the range 0-5 where 0 will show no messages, and
+5 will show all messages. The wildcard * can be used to match category names.
+
+Use \-\-gst\-debug\-help to show category names
+
+Example:
+GST_CAT:5,GST_ELEMENT_*:3,oggdemux:5
+
.TP 8
.B \-\-gst\-debug\-level=LEVEL
Sets the threshold for printing debugging messages. A higher level
.B \-\-gst\-debug\-no\-color
\fIGStreamer\fP normally prints debugging messages so that the
messages are color-coded when printed to a terminal that handles
-ANSI escape sequences. Using this option causes \fIGstreamer\fP
-to print messages without color.
+ANSI escape sequences. Using this option causes \fIGStreamer\fP
+to print messages without color. Setting the \fBGST_DEBUG_NO_COLOR\fR
+environment variable will achieve the same thing.
.TP 8
.B \-\-gst\-disable\-debug
Disables debugging.
.B \-\-gst\-debug\-help
Prints a list of available debug categories and their default debugging level.
.TP 8
-.B \-\-gst\-disable\-cpu\-opt
-\fIGStreamer\fP normally automatically detects the capabilities of the
-current CPU and selects the optimal implementation for some functions.
-Using this flag disables detection, which is useful for debugging.
-.TP 8
.B \-\-gst\-plugin\-spew
\fIGStreamer\fP info flags to set
Enable printout of errors while loading \fIGStreamer\fP plugins
.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
.SH "PIPELINE DESCRIPTION"
\fI[BINTYPE.]\fR ( \fI[PROPERTY1 ...]\fR PIPELINE-DESCRIPTION )
.br
-{ \fI[PROPERTY1 ...]\fR PIPELINE-DESCRIPTION }
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.
+set. Every element between the braces is put into the bin. Please note the dot
+that has to be used after the BINTYPE. You will almost never need this
+functionality, it is only really useful for applications using the
+gst_launch_parse() API with 'bin' as bintype. That way it is possible to build
+partial pipelines instead of a full-fledged top-level pipeline.
.B Links
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.
.B Caps
.B Properties
-NAME\fI[:TYPE]\fR=VALUE
+NAME=\fI[(TYPE)]\fRVALUE
.br
-in lists and ranges: [TYPE=]VALUE
+in lists and ranges: \fI[(TYPE)]\fRVALUE
-Sets the requested property in capabilites. The name is an alphanumeric value
+Sets the requested property in capabilities. The name is an alphanumeric value
and the type can have the following case-insensitive values:
.br
- \fBi\fR or \fBint\fR for integer values or ranges
.br
- \fBs\fR, \fBstr\fR or \fBstring\fR for strings
.br
+- \fBfraction\fR for fractions (framerate, pixel-aspect-ratio)
+.br
- \fBl\fR or \fBlist\fR for lists
.br
If no type was given, the following order is tried: integer, float, boolean,
either be integers or strings. Boolean values are (case insensitive) \fIyes\fR,
\fIno\fR, \fItrue\fR or \fIfalse\fR and may like strings be escaped with " or '.
.br
-Ranges are in this format: [ PROPERTY, PROPERTY ]
+Ranges are in this format: [ VALUE, VALUE ]
.br
-Lists use this format: ( PROPERTY \fI[, PROPERTY ...]\fR )
+Lists use this format: ( VALUE \fI[, VALUE ...]\fR )
+
+.SH "PIPELINE CONTROL"
+
+A pipeline can be controlled by signals. SIGUSR2 will stop the pipeline
+(GST_STATE_NULL); SIGUSR1 will put it back to play (GST_STATE_PLAYING).
+By default, the pipeline will start in the playing state.
+.br
+There are currently no signals defined to go into the ready or pause
+(GST_STATE_READY and GST_STATE_PAUSED) state explicitely.
.SH "PIPELINE EXAMPLES"
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".
+plug-in such as "esdsink", "alsasink", "osxaudiosink", or "artsdsink".
+Likewise, "xvimagesink" can be substituted with "ximagesink", "sdlvideosink",
+"osxvideosink", or "aasink". Keep in mind though that different sinks might
+accept different formats and even the same sink might accept different formats
+on different machines, so you might need to add converter elements like
+audioconvert and audioresample (for audio) or ffmpegcolorspace (for video)
+in front of the sink to make things work.
.B Audio playback
.B
- gst\-launch filesrc location=music.mp3 ! mad ! osssink
+ gst\-launch filesrc location=music.mp3 ! mad ! audioconvert ! audioresample ! 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
+ gst\-launch filesrc location=music.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! osssink
.br
Play an Ogg Vorbis format file
gst\-launch gnomevfssrc location=music.mp3 ! mad ! osssink
.br
.B
- gst\-launch gnomevfssrc location=http://domain.com/music.mp3 ! mad ! osssink
+ gst\-launch gnomevfssrc location=http://domain.com/music.mp3 ! mad ! audioconvert ! audioresample ! osssink
.br
Play an mp3 file or an http stream using GNOME\-VFS
.B
- gst\-launch gnomevfssrc location=smb://computer/music.mp3 ! mad ! osssink
+ gst\-launch gnomevfssrc location=smb://computer/music.mp3 ! mad ! audioconvert ! audioresample ! osssink
.br
Use GNOME\-VFS to play an mp3 file located on an SMB server
.B Format conversion
.B
- gst\-launch filesrc location=music.mp3 ! mad ! vorbisenc ! filesink location=music.ogg
+ gst\-launch filesrc location=music.mp3 ! mad ! audioconvert ! vorbisenc ! oggmux ! filesink location=music.ogg
.br
Convert an mp3 music file to an Ogg Vorbis file
.B
- gst\-launch filesrc location=music.mp3 ! mad ! flacenc ! filesink location=test.flac
+ gst\-launch filesrc location=music.mp3 ! mad ! audioconvert ! flacenc ! filesink location=test.flac
.br
Convert to the FLAC format
.B Other
.B
- gst\-launch filesrc location=music.wav ! wavparse ! osssink
+ gst\-launch filesrc location=music.wav ! wavparse ! audioconvert ! audioresample ! osssink
.br
-Plays a .WAV file
+Plays a .WAV file that contains raw audio data (PCM).
.B
- gst\-launch filesrc location=music.wav ! wavparse ! vorbisenc ! filesink location=music.ogg
+ gst\-launch filesrc location=music.wav ! wavparse ! audioconvert ! vorbisenc ! oggmux ! filesink location=music.ogg
.br
.B
- gst\-launch filesrc location=music.wav ! wavparse ! mpegaudio ! filesink location=music.mp3
+ gst\-launch filesrc location=music.wav ! wavparse ! audioconvert ! lame ! 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.
+Convert a .WAV file containing raw audio data into an Ogg Vorbis or mp3 file
.B
- gst\-launch cdparanoia ! mpegaudio ! filesink location=cd.mp3
+ gst\-launch cdparanoia ! lame ! filesink location=cd.mp3
.br
-Rip all tracks from compact disc and convert them into a single mp3 file
+rips all tracks from compact disc and convert them into a single mp3 file
Using \fBgst\-inspect\fR(1), it is possible to discover settings for cdparanoia
-that will tell it to rip individual tracks.
+that will tell it to rip individual tracks. Alternatively, you can use an URI
+and gst-launch will find an element (such as cdparanoia) that supports that
+protocol for you, e.g.:
+.B
+ gst\-launch cdda://5 ! lame vbr=new vbr-quality=6 ! filesink location=track5.mp3
.B
- gst\-launch osssrc ! vorbisenc ! filesink location=input.ogg
+ gst\-launch osssrc ! audioconvert ! vorbisenc ! oggmux ! filesink location=input.ogg
.br
-Record sound from your audio input and encode it into an ogg file
+records sound from your audio input and encodes it into an ogg file
.B Video
.B
- gst\-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! mpegdemux ! mpeg2dec ! xvideosink
+ gst\-launch filesrc location=JB_FF9_TheGravityOfLove.mpg ! dvddemux ! mpeg2dec ! xvimagesink
.br
Display only the video portion of an MPEG-1 video file, outputting to
an X display window
.B
- gst\-launch filesrc location=/flflfj.vob ! mpegdemux ! mpeg2dec ! sdlvideosink
+ gst\-launch filesrc location=/flflfj.vob ! dvddemux ! mpeg2dec ! sdlvideosink
.br
Display the video portion of a .vob file (used on DVDs), outputting to
an SDL window
.B
- gst\-launch filesrc location=movie.mpg ! mpegdemux name=demuxer ! mpeg2dec ! sdlvideosink demuxer. ! mad ! osssink
+ gst\-launch filesrc location=movie.mpg ! dvddemux name=demuxer demuxer. ! queue ! mpeg2dec ! sdlvideosink demuxer. ! queue ! mad ! audioconvert ! audioresample ! osssink
.br
Play both video and audio portions of an MPEG 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
-
-.B
- gst\-launch filesrc location=movie.avi ! avidemux name=demuxer ! { queue ! ffdecall ! sdlvideosink } { demuxer. ! queue ! mad ! osssink }
+ gst\-launch filesrc location=movie.mpg ! mpegdemux name=demuxer demuxer. ! queue ! mpeg2dec ! ffmpegcolorspace ! sdlvideosink demuxer. ! queue ! mad ! audioconvert ! audioresample ! osssink
.br
Play an AVI movie
.B Network streaming
-An MPEG\-1 system stream can be streamed via RTP from one machine to
-another.
+Stream video using RTP and network elements.
.B
- gst\-launch rtprecv media_type=mpeg1_sys ! mpegdemux name=demuxer ! { queue ! mpeg2dec ! xvideosink } { demuxer. ! queue ! mad ! osssink }
+ gst\-launch v4l2src ! video/x-raw-yuv,width=128,height=96,format='(fourcc)'UYVY ! ffmpegcolorspace ! ffenc_h263 ! video/x-h263 ! rtph263ppay pt=96 ! udpsink host=192.168.1.1 port=5000 sync=false
.br
Use this command on the receiver
.B
- gst\-launch filesrc location=mpeg1system.mpeg ! mpegparse ! rtpsend ip=IPorHostname
+ gst\-launch udpsrc port=5000 ! application/x-rtp, clock-rate=90000,payload=96 ! rtph263pdepay queue-delay=0 ! ffdec_h263 ! xvimagesink
.br
This command would be run on the transmitter
.B Diagnostic
.B
- gst\-launch fakesrc ! fakesink
+ gst\-launch -v fakesrc num-buffers=16 ! fakesink
.br
-Generate a null stream and ignore it
+Generate a null stream and ignore it (and print out details).
.B
- gst\-launch sinesrc ! osssink
+ gst\-launch audiotestsrc ! audioconvert ! audioresample ! osssink
.br
-Generate a pure tone to test the audio output
+Generate a pure sine tone to test the audio output
.B
- gst\-launch videotestsrc ! xvideosink
+ gst\-launch videotestsrc ! xvimagesink
+.br
+.B
+ gst\-launch videotestsrc ! ximagesink
.br
Generate a familiar test pattern to test the video output
.B Automatic linking
-You can use the spider element to automatically select the right elements to get
-a working pipeline.
+You can use the decodebin element to automatically select the right elements
+to get a working pipeline.
.B
- gst\-launch filesrc location=musicfile ! spider ! osssink
+ gst\-launch filesrc location=musicfile ! decodebin ! audioconvert ! audioresample ! osssink
.br
Play any supported audio format
.B
- gst\-launch filesrc location=videofile ! spider name=spider ! osssink spider. ! xvideosink
+ gst\-launch filesrc location=videofile ! decodebin name=decoder decoder. ! queue ! audioconvert ! audioresample ! osssink decoder. ! ffmpegcolorspace ! xvimagesink
.br
+Play any supported video format with video and audio output. Threads are used
+automatically. To make this even easier, you can use the playbin element:
+
.B
- gst\-launch filesrc location=videofile ! spider name=spider ! { queue ! osssink } { spider. ! queue ! xvideosink }
+ gst\-launch playbin uri=file:///home/joe/foo.avi
.br
-Play any supported video format with video and audio output. The second pipeline
-uses threaded output.
+
.B Filtered connections
These examples show you how to use filtered caps.
.B
- gst\-launch videotestsrc ! video/raw, format:fourcc=YUY2; video/raw, format:fourcc=YV12 ! xvideosink
+ gst\-launch videotestsrc ! 'video/x-raw-yuv,format=(fourcc)YUY2;video/x-raw-yuv,format=(fourcc)YV12' ! xvimagesink
.br
Show a test image and use the YUY2 or YV12 video format for this.
.B
- gst\-launch osssrc ! "audio/raw", format=int, width=[16, 32], depth=(16, 24, 32), signed=TRUE ! osssink
-.br
-Playback currently recorded audio. Force usage of signed 16 to 32 bit samples.
-
-
-
-
+ gst\-launch osssrc ! 'audio/x-raw-int,rate=[32000,64000],width=[16,32],depth={16,24,32},signed=(boolean)true' ! wavenc ! filesink location=recording.wav
+.br
+record audio and write it to a .wav file. Force usage of signed 16 to 32 bit
+samples and a sample rate between 32kHz and 64KHz.
+
+
+.SH "ENVIRONMENT VARIABLES"
+.TP
+\fBGST_DEBUG\fR
+Comma-separated list of debug categories and levels, e.g.
+GST_DEBUG=totem:4,typefind:5
+.TP
+\fBGST_DEBUG_NO_COLOR\fR
+When this environment variable is set, coloured debug output is disabled.
+.TP
+\fBGST_DEBUG_DUMP_DOT_DIR\fR
+When set to a filesystem path, store dot files of pipeline graphs there.
+.TP
+\fBGST_REGISTRY\fR
+Path of the plugin registry file. Default is
+~/.gstreamer-GST_MAJORMINOR/registry-CPU.xml where CPU is the machine/cpu type
+GStreamer was compiled for, e.g. 'i486', 'i686', 'x86-64', 'ppc', etc. (check
+the output of "uname -i" and "uname -m" for details).
+.TP
+\fBGST_REGISTRY_UPDATE\fR
+Set to "no" to force GStreamer to assume that no plugins have changed,
+been added or been removed. This will make GStreamer skip the initial check
+whether a rebuild of the registry cache is required or not. This may be useful
+in embedded environments where the installed plugins never change. Do not
+use this option in any other setup.
+.TP
+\fBGST_PLUGIN_PATH\fR
+Specifies a list of directories to scan for additional plugins.
+These take precedence over the system plugins.
+.TP
+\fBGST_PLUGIN_SYSTEM_PATH\fR
+Specifies a list of plugins that are always loaded by default. If not set,
+this defaults to the system-installed path, and the plugins installed in the
+user's home directory
+.TP
+\fBOIL_CPU_FLAGS\fR
+Useful liboil environment variable. Set OIL_CPU_FLAGS=0 when valgrind or
+other debugging tools trip over liboil's CPU detection (quite a few important
+GStreamer plugins like videotestsrc, audioconvert or audioresample use liboil).
+.TP
+\fBG_DEBUG\fR
+Useful GLib environment variable. Set G_DEBUG=fatal_warnings to make
+GStreamer programs abort when a critical warning such as an assertion failure
+occurs. This is useful if you want to find out which part of the code caused
+that warning to be triggered and under what circumstances. Simply set G_DEBUG
+as mentioned above and run the program in gdb (or let it core dump). Then get
+a stack trace in the usual way.
+.
+.SH FILES
+.TP 8
+~/.gstreamer-GST_MAJORMINOR/registry-*.xml
+The xml plugin database; can be deleted at any time, will be re-created
+automatically when it does not exist yet or plugins change.
.
.SH "SEE ALSO"
-.BR gst\-complete (1),
-.BR gst\-register (1),
-.BR gst\-inspect (1)
+.BR gst\-feedback (1),
+.BR gst\-inspect (1),
+.BR gst\-typefind (1)
.SH "AUTHOR"
-The GStreamer team at http://gstreamer.net/
+The GStreamer team at http://gstreamer.freedesktop.org/
projects / platform / upstream / gstreamer.git / blobdiff