gstreamer/docs/manual/appendix-programs.xml

278 lines
8.9 KiB
XML
Raw Normal View History

<chapter id="chapter-programs">
<title>Programs</title>
<para>
</para>
<sect1 id="section-programs-gst-launch">
<title><command>gst-launch</command></title>
<para>
This is a tool that will construct pipelines based on a command-line
syntax.
</para>
<para>
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
A simple commandline looks like:
<screen>
gst-launch filesrc location=hello.mp3 ! mad ! audioresample ! osssink
</screen>
A more complex pipeline looks like:
<screen>
gst-launch filesrc location=redpill.vob ! dvddemux name=demux \
demux.audio_00 ! queue ! a52dec ! audioconvert ! audioresample ! osssink \
demux.video_00 ! queue ! mpeg2dec ! videoconvert ! xvimagesink
</screen>
</para>
<para>
You can also use the parser in you own
code. <application>GStreamer</application> provides a function
gst_parse_launch () that you can use to construct a pipeline.
The following program lets you create an MP3 pipeline using the
gst_parse_launch () function:
</para>
<programlisting>
#include &lt;gst/gst.h&gt;
int
main (int argc, char *argv[])
{
GstElement *pipeline;
GstElement *filesrc;
GstMessage *msg;
GstBus *bus;
GError *error = NULL;
gst_init (&amp;argc, &amp;argv);
if (argc != 2) {
g_print ("usage: %s &lt;filename&gt;\n", argv[0]);
return -1;
}
pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &amp;error);
if (!pipeline) {
g_print ("Parse error: %s\n", error->message);
exit (1);
}
filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc");
g_object_set (filesrc, "location", argv[1], NULL);
gst_element_set_state (pipeline, GST_STATE_PLAYING);
bus = gst_element_get_bus (pipeline);
/* wait until we either get an EOS or an ERROR message. Note that in a real
* program you would probably not use gst_bus_poll(), but rather set up an
* async signal watch on the bus and run a main loop and connect to the
* bus's signals to catch certain messages or all messages */
msg = gst_bus_poll (bus, GST_MESSAGE_EOS | GST_MESSAGE_ERROR, -1);
switch (GST_MESSAGE_TYPE (msg)) {
case GST_MESSAGE_EOS: {
g_print ("EOS\n");
break;
}
case GST_MESSAGE_ERROR: {
GError *err = NULL; /* error to show to users */
gchar *dbg = NULL; /* additional debug string for developers */
gst_message_parse_error (msg, &err, &dbg);
if (err) {
g_printerr ("ERROR: %s\n", err-&gt;message);
g_error_free (err);
}
if (dbg) {
g_printerr ("[Debug details: %s]\n", dbg);
g_free (dbg);
}
}
default:
g_printerr ("Unexpected message of type %d", GST_MESSAGE_TYPE (msg));
break;
}
gst_message_unref (msg);
gst_element_set_state (pipeline, GST_STATE_NULL);
gst_object_unref (pipeline);
gst_object_unref (bus);
return 0;
}
</programlisting>
<para>
Note how we can retrieve the filesrc element from the constructed bin using the
element name.
</para>
<sect2>
<title>Grammar Reference</title>
<para>
The <command>gst-launch</command> syntax is processed by a flex/bison parser. This section
is intended to provide a full specification of the grammar; any deviations from this
specification is considered a bug.
</para>
<sect3>
<title>Elements</title>
<screen>
... mad ...
</screen>
<para>
A bare identifier (a string beginning with a letter and containing
only letters, numbers, dashes, underscores, percent signs, or colons)
will create an element from a given element factory. In this example,
an instance of the "mad" MP3 decoding plugin will be created.
</para>
</sect3>
<sect3>
<title>Links</title>
<screen>
... !sink ...
</screen>
<para>
An exclamation point, optionally having a qualified pad name (an the name of the pad,
optionally preceded by the name of the element) on both sides, will link two pads. If
the source pad is not specified, a source pad from the immediately preceding element
will be automatically chosen. If the sink pad is not specified, a sink pad from the next
element to be constructed will be chosen. An attempt will be made to find compatible
pads. Pad names may be preceded by an element name, as in
<computeroutput>my_element_name.sink_pad</computeroutput>.
</para>
</sect3>
<sect3>
<title>Properties</title>
<screen>
... location="http://gstreamer.net" ...
</screen>
<para>
The name of a property, optionally qualified with an element name, and a value,
separated by an equals sign, will set a property on an element. If the element is not
specified, the previous element is assumed. Strings can optionally be enclosed in
quotation marks. Characters in strings may be escaped with the backtick
(<literal>\</literal>). If the right-hand side is all digits, it is considered to be an
integer. If it is all digits and a decimal point, it is a double. If it is "true",
"false", "TRUE", or "FALSE" it is considered to be boolean. Otherwise, it is parsed as a
string. The type of the property is determined later on in the parsing, and the value is
converted to the target type. This conversion is not guaranteed to work, it relies on
the g_value_convert routines. No error message will be displayed on an invalid
conversion, due to limitations in the value convert API.
</para>
</sect3>
<sect3>
<title>Bins, Threads, and Pipelines</title>
<screen>
( ... )
</screen>
<para>
A pipeline description between parentheses is placed into a bin. The open paren may be
preceded by a type name, as in <computeroutput>jackbin.( ... )</computeroutput> to make
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
a bin of a specified type. Square brackets make pipelines, and curly braces make
threads. The default toplevel bin type is a pipeline, although putting the whole
description within parentheses or braces can override this default.
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="section-programs-gst-inspect">
<title><command>gst-inspect</command></title>
<para>
This is a tool to query a plugin or an element about its properties.
</para>
<para>
To query the information about the element mad, you would specify:
</para>
<screen>
gst-inspect mad
</screen>
<para>
Below is the output of a query for the osssink element:
</para>
<screen>
Factory Details:
Long name: Audio Sink (OSS)
Class: Sink/Audio
Description: Output to a sound card via OSS
Version: 0.3.3.1
Author(s): Erik Walthinsen &lt;omega@cse.ogi.edu&gt;, Wim Taymans &lt;wim.taymans@chello.be&gt;
Copyright: (C) 1999
GObject
+----GstObject
+----GstElement
+----GstOssSink
Pad Templates:
SINK template: 'sink'
Availability: Always
Capabilities:
'osssink_sink':
MIME type: 'audio/raw':
format: String: int
endianness: Integer: 1234
width: List:
Integer: 8
Integer: 16
depth: List:
Integer: 8
Integer: 16
channels: Integer range: 1 - 2
law: Integer: 0
signed: List:
Boolean: FALSE
Boolean: TRUE
rate: Integer range: 1000 - 48000
Element Flags:
GST_ELEMENT_THREADSUGGESTED
Element Implementation:
No loopfunc(), must be chain-based or not configured yet
Has change_state() function: gst_osssink_change_state
Has custom save_thyself() function: gst_element_save_thyself
Has custom restore_thyself() function: gst_element_restore_thyself
Clocking Interaction:
element requires a clock
element provides a clock: GstOssClock
Pads:
SINK: 'sink'
Implementation:
Has chainfunc(): 0x40056fc0
Pad Template: 'sink'
Element Arguments:
name : String (Default "element")
device : String (Default "/dev/dsp")
mute : Boolean (Default false)
format : Integer (Default 16)
channels : Enum "GstAudiosinkChannels" (default 1)
(0): Silence
(1): Mono
(2): Stereo
frequency : Integer (Default 11025)
fragment : Integer (Default 6)
buffer-size : Integer (Default 4096)
Element Signals:
"handoff" : void user_function (GstOssSink* object,
gpointer user_data);
</screen>
<para>
To query the information about a plugin, you would do:
</para>
<screen>
gst-inspect gstelements
</screen>
</sect1>
</chapter>