mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-23 08:46:40 +00:00
899f2f8244
Original commit message from CVS: * tools/Makefile.am: * tools/gst-launch.1.in: Add FILES section and correct entry about GST_REGISTRY_PATH environment variable (#133495; #133494).
428 lines
14 KiB
Groff
428 lines
14 KiB
Groff
.TH "GStreamer" "1" "December 2005"
|
|
.SH "NAME"
|
|
gst\-launch \- build and run a GStreamer pipeline
|
|
.SH "SYNOPSIS"
|
|
\fBgst\-launch\fR \fI[OPTION...]\fR PIPELINE\-DESCRIPTION
|
|
.SH "DESCRIPTION"
|
|
.LP
|
|
\fIgst\-launch\fP is a tool that builds and runs basic
|
|
\fIGStreamer\fP pipelines.
|
|
|
|
In simple form, a PIPELINE\-DESCRIPTION is a list of
|
|
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 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
|
|
\fIgst\-launch\fP accepts the following options:
|
|
.TP 8
|
|
.B \-\-help
|
|
Print help synopsis and available FLAGS
|
|
.TP 8
|
|
.B \-v, \-\-verbose
|
|
Output status information
|
|
.TP 8
|
|
.B \-m, \-\-messages
|
|
Output messages posted on the pipeline's bus
|
|
.TP 8
|
|
.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
|
|
Print memory allocation traces. The feature must be enabled at compile time to
|
|
work.
|
|
.TP 8
|
|
|
|
.
|
|
.SH "GSTREAMER OPTIONS"
|
|
.l
|
|
\fIgst\-launch\fP also accepts the following options that are common
|
|
to all GStreamer applications:
|
|
.TP 8
|
|
.B \-\-gst\-version
|
|
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. 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
|
|
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
|
|
will print more messages. The useful range is 0-5, with the default
|
|
being 0.
|
|
.TP 8
|
|
.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. Setting the \fBGST_DEBUG_NO_COLOR\fR
|
|
environment variable will achieve the same thing.
|
|
.TP 8
|
|
.B \-\-gst\-disable\-debug
|
|
Disables debugging.
|
|
.TP 8
|
|
.B \-\-gst\-debug\-help
|
|
Prints a list of available debug categories and their default debugging level.
|
|
.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
|
|
|
|
.SH "PIPELINE DESCRIPTION"
|
|
|
|
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.
|
|
|
|
.B Elements
|
|
|
|
ELEMENTTYPE \fI[PROPERTY1 ...]\fR
|
|
|
|
Creates an element of type ELEMENTTYPE and sets the PROPERTIES.
|
|
|
|
.B Properties
|
|
|
|
PROPERTY=VALUE ...
|
|
|
|
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.
|
|
|
|
.B Bins
|
|
|
|
\fI[BINTYPE.]\fR ( \fI[PROPERTY1 ...]\fR PIPELINE-DESCRIPTION )
|
|
.br
|
|
|
|
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. 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
|
|
|
|
\fI[[SRCELEMENT].[PAD1,...]]\fR ! \fI[[SINKELEMENT].[PAD1,...]]\fR
|
|
\fI[[SRCELEMENT].[PAD1,...]]\fR ! CAPS ! \fI[[SINKELEMENT].[PAD1,...]]\fR
|
|
|
|
Links the element with name SRCELEMENT to the element with name SINKELEMENT,
|
|
using the caps specified in CAPS as a filter.
|
|
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
|
|
|
|
.B Caps
|
|
|
|
MIMETYPE \fI[, PROPERTY[, PROPERTY ...]]]\fR \fI[; CAPS[; CAPS ...]]\fR
|
|
|
|
Creates a capability with the given mimetype and optionally with given
|
|
properties. The mimetype can be escaped using " or '.
|
|
If you want to chain caps, you can add more caps in the same format afterwards.
|
|
|
|
.B Properties
|
|
|
|
NAME\fI[:TYPE]\fR=VALUE
|
|
.br
|
|
in lists and ranges: [TYPE=]VALUE
|
|
|
|
Sets the requested property in capabilites. 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
|
|
- \fBf\fR or \fBfloat\fR for float values or ranges
|
|
.br
|
|
- \fB4\fR or \fBfourcc\fR for FOURCC values
|
|
.br
|
|
- \fBb\fR, \fBbool\fR or \fBboolean\fR for boolean values
|
|
.br
|
|
- \fBs\fR, \fBstr\fR or \fBstring\fR for strings
|
|
.br
|
|
- \ffraction\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,
|
|
string.
|
|
.br
|
|
Integer values must be parsable by \fBstrtol()\fP, floats by \fBstrtod()\fP. FOURCC values may
|
|
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 ]
|
|
.br
|
|
Lists use this format: ( PROPERTY \fI[, PROPERTY ...]\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", "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 ! 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 ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! 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 ! 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 ! 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 ! 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 ! audioconvert ! flacenc ! filesink location=test.flac
|
|
.br
|
|
Convert to the FLAC format
|
|
|
|
.B Other
|
|
|
|
.B
|
|
gst\-launch filesrc location=music.wav ! wavparse ! audioconvert ! audioresample ! osssink
|
|
.br
|
|
Plays a .WAV file that contains raw audio data (PCM).
|
|
|
|
.B
|
|
gst\-launch filesrc location=music.wav ! wavparse ! audioconvert ! vorbisenc ! oggmux ! filesink location=music.ogg
|
|
.br
|
|
.B
|
|
gst\-launch filesrc location=music.wav ! wavparse ! audioconvert ! lame ! filesink location=music.mp3
|
|
.br
|
|
Convert a .WAV file containing raw audio data into an Ogg Vorbis or mp3 file
|
|
|
|
.B
|
|
gst\-launch cdparanoia ! lame ! filesink location=cd.mp3
|
|
.br
|
|
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. 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 ! audioconvert ! vorbisenc ! oggmux ! filesink location=input.ogg
|
|
.br
|
|
records sound from your audio input and encodes it into an ogg file
|
|
|
|
.B Video
|
|
|
|
.B
|
|
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 ! 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 ! 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 demuxer. ! queue ! mpeg2dec ! ffmpegcolorspace ! sdlvideosink demuxer. ! queue ! mad ! audioconvert ! audioresample ! osssink
|
|
.br
|
|
Play an AVI movie
|
|
|
|
.B Network streaming
|
|
|
|
FIXME: give example pipelines using RTP and network elements.
|
|
|
|
.B
|
|
FIXME: pipeline to send file
|
|
.br
|
|
Use this command on the receiver
|
|
|
|
.B
|
|
FIXME: pipeline to receive file
|
|
.br
|
|
This command would be run on the transmitter
|
|
|
|
.B Diagnostic
|
|
|
|
.B
|
|
gst\-launch -v fakesrc num-buffers=16 ! fakesink
|
|
.br
|
|
Generate a null stream and ignore it (and print out details).
|
|
|
|
.B
|
|
gst\-launch audiotestsrc ! audioconvert ! audioresample ! osssink
|
|
.br
|
|
Generate a pure sine tone to test the audio output
|
|
|
|
.B
|
|
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 decodebin element to automatically select the right elements
|
|
to get a working pipeline.
|
|
|
|
.B
|
|
gst\-launch filesrc location=musicfile ! decodebin ! audioconvert ! audioresample ! osssink
|
|
.br
|
|
Play any supported audio format
|
|
|
|
.B
|
|
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 playbin uri=file:///home/joe/foo.avi
|
|
.br
|
|
|
|
|
|
.B Filtered connections
|
|
|
|
These examples show you how to use filtered caps.
|
|
|
|
.B
|
|
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/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_REGISTRY\fR
|
|
Path of the registry file. Default is ~/.gstreamer-GST_MAJORMINOR/registry-HOST_CPU.xml.
|
|
.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\-feedback (1),
|
|
.BR gst\-inspect (1),
|
|
.BR gst\-typefind (1)
|
|
.SH "AUTHOR"
|
|
The GStreamer team at http://gstreamer.freedesktop.org/
|