From: Benjamin Otte Date: Fri, 25 Apr 2003 20:15:54 +0000 (+0000) Subject: update man page to new pipeline parsing and make it more informational X-Git-Tag: BRANCH-ERROR-ROOT~269 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1f5fa9cf82186047779a6934aad522dbd6438fc3;p=platform%2Fupstream%2Fgstreamer.git update man page to new pipeline parsing and make it more informational Original commit message from CVS: update man page to new pipeline parsing and make it more informational --- diff --git a/tools/gst-launch.1 b/tools/gst-launch.1 index 4935f7e..7bd4c74 100644 --- a/tools/gst-launch.1 +++ b/tools/gst-launch.1 @@ -1,4 +1,4 @@ -.TH "GStreamer" "1" "March 2001" +.TH "GStreamer" "1" "April 2003" .SH "NAME" gst\-launch \- build and run a GStreamer pipeline .SH "SYNOPSIS" @@ -9,169 +9,275 @@ gst\-launch \- build and run a GStreamer pipeline \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),