mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-08 13:18:52 +00:00
Remove GST_MAJORMINOR and replace it by GST_API_VERSION Also set GST_VERSION_{MAJOR,MINOR,MICRO,NANO} explicitely now. All versions are at 1.0.0 now for the release soon but API/ABI can still change until the 1.0.0 release. Next release versions until 1.0.0 will be 0.10.9X and these will be release candidates. GST_VERSION_* will nonetheless stay at 1.0.0.0.
460 lines
16 KiB
Groff
460 lines
16 KiB
Groff
.TH "GStreamer" "1" "May 2007"
|
|
.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 and property notifications
|
|
.TP 8
|
|
.B \-q, \-\-quiet
|
|
Do not print any progress 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 \-e, \-\-eos\-on\-shutdown
|
|
Force an EOS event on sources before shutting the pipeline down. This is
|
|
useful to make sure muxers create readable files when a muxing pipeline is
|
|
shut down forcefully via Control-C.
|
|
.TP 8
|
|
.B \-i, \-\-index
|
|
Gather and print index statistics. This is mostly useful for playback or
|
|
recording pipelines.
|
|
.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\-debug\-disable
|
|
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)]\fRVALUE
|
|
.br
|
|
in lists and ranges: \fI[(TYPE)]\fRVALUE
|
|
|
|
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
|
|
- \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
|
|
- \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,
|
|
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: [ VALUE, VALUE ]
|
|
.br
|
|
Lists use this format: ( VALUE \fI[, VALUE ...]\fR )
|
|
|
|
.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 cdparanoiasrc mode=continuous ! audioconvert ! lame ! id3v2mux ! filesink location=cd.mp3
|
|
.br
|
|
rips all tracks from compact disc and convert them into a single mp3 file
|
|
|
|
.B
|
|
gst\-launch cdparanoiasrc track=5 ! audioconvert ! lame ! id3v2mux ! filesink location=track5.mp3
|
|
.br
|
|
rips track 5 from the CD and converts it into a single mp3 file
|
|
|
|
Using \fBgst\-inspect\fR(1), it is possible to discover settings like the above
|
|
for cdparanoiasrc that will tell it to rip the entire cd or only tracks of it.
|
|
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 with an external text subtitle stream
|
|
|
|
This example also shows how to refer to specific pads by name if an element
|
|
(here: textoverlay) has multiple sink or source pads.
|
|
|
|
.B
|
|
gst\-launch textoverlay name=overlay ! ffmpegcolorspace ! videoscale ! autovideosink filesrc location=movie.avi ! decodebin2 ! ffmpegcolorspace ! overlay.video_sink filesrc location=movie.srt ! subparse ! overlay.text_sink
|
|
|
|
.br
|
|
Play an AVI movie with an external text subtitle stream using playbin2
|
|
|
|
.B
|
|
gst\-launch playbin2 uri=file:///path/to/movie.avi suburi=file:///path/to/movie.srt
|
|
|
|
.B Network streaming
|
|
|
|
Stream video using RTP and network elements.
|
|
|
|
.B
|
|
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
|
|
This command would be run on the transmitter
|
|
|
|
.B
|
|
gst\-launch udpsrc port=5000 ! application/x-rtp, clock-rate=90000,payload=96 ! rtph263pdepay queue-delay=0 ! ffdec_h263 ! xvimagesink
|
|
.br
|
|
Use this command on the receiver
|
|
|
|
.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_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_API_VERSION/registry-CPU.bin 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
|
|
\fBORC_CODE\fR
|
|
Useful Orc environment variable. Set ORC_CODE=debug to enable debuggers
|
|
such as gdb to create useful backtraces from Orc-generated code. Set
|
|
ORC_CODE=backup or ORC_CODE=emulate if you suspect Orc's SIMD code
|
|
generator is producing incorrect code. (Quite a few important
|
|
GStreamer plugins like videotestsrc, audioconvert or audioresample use Orc).
|
|
.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_API_VERSION/registry-*.bin
|
|
The plugin cache; 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/
|