mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-09 05:38:58 +00:00
Original commit message from CVS: * docs/manual/advanced-dataaccess.xml: * docs/manual/appendix-checklist.xml: * docs/manual/appendix-programs.xml: * docs/manual/basics-pads.xml: * docs/manual/highlevel-components.xml: * docs/manual/manual.xml: Update for 0.10: s/0.9/0.10/; s/audioscale/audiorsample/; add converters in front of pipelines; remove curly brackets for threads stuff, they no longer exist; use GST_TYPE_FRACTION for framerates; update some pieces of code to 0.10, but there's plenty more to do. * docs/manual/appendix-porting.xml: Expand on asynchroneous state changes; s/0.9/0.10/; mention disappearance of gst_init_get_popt_table() (fixes #322916).
277 lines
8.9 KiB
XML
277 lines
8.9 KiB
XML
<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>
|
|
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 ! ffmpegcolorspace ! 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 <gst/gst.h>
|
|
|
|
int
|
|
main (int argc, char *argv[])
|
|
{
|
|
GstElement *pipeline;
|
|
GstElement *filesrc;
|
|
GstMessage *msg;
|
|
GstBus *bus;
|
|
GError *error = NULL;
|
|
|
|
gst_init (&argc, &argv);
|
|
|
|
if (argc != 2) {
|
|
g_print ("usage: %s <filename>\n", argv[0]);
|
|
return -1;
|
|
}
|
|
|
|
pipeline = gst_parse_launch ("filesrc name=my_filesrc ! mad ! osssink", &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->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
|
|
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 <omega@cse.ogi.edu>, Wim Taymans <wim.taymans@chello.be>
|
|
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>
|