mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-25 17:50:36 +00:00
4cf6a6e086
Unreffing the objects returned by gst_bin_get_by_name() and gst_pipeline_get_use() were missing in several tests, so add these. Fixes https://bugzilla.gnome.org/show_bug.cgi?id=734345
342 lines
13 KiB
XML
342 lines
13 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 ! 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 <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);
|
|
g_object_unref (filesrc);
|
|
|
|
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>
|
|
<![CDATA[
|
|
Factory Details:
|
|
Rank: secondary (128)
|
|
Long-name: Audio Sink (OSS)
|
|
Klass: Sink/Audio
|
|
Description: Output to a sound card via OSS
|
|
Author: Erik Walthinsen <omega@cse.ogi.edu>, Wim Taymans <wim.taymans@chello.be>
|
|
|
|
Plugin Details:
|
|
Name: ossaudio
|
|
Description: OSS (Open Sound System) support for GStreamer
|
|
Filename: /home/wim/gst/head/gst-plugins-good/sys/oss/.libs/libgstossaudio.so
|
|
Version: 1.0.0.1
|
|
License: LGPL
|
|
Source module: gst-plugins-good
|
|
Source release date: 2012-09-25 12:52 (UTC)
|
|
Binary package: GStreamer Good Plug-ins git
|
|
Origin URL: Unknown package origin
|
|
|
|
GObject
|
|
+----GInitiallyUnowned
|
|
+----GstObject
|
|
+----GstElement
|
|
+----GstBaseSink
|
|
+----GstAudioBaseSink
|
|
+----GstAudioSink
|
|
+----GstOssSink
|
|
|
|
Pad Templates:
|
|
SINK template: 'sink'
|
|
Availability: Always
|
|
Capabilities:
|
|
audio/x-raw
|
|
format: { S16LE, U16LE, S8, U8 }
|
|
layout: interleaved
|
|
rate: [ 1, 2147483647 ]
|
|
channels: 1
|
|
audio/x-raw
|
|
format: { S16LE, U16LE, S8, U8 }
|
|
layout: interleaved
|
|
rate: [ 1, 2147483647 ]
|
|
channels: 2
|
|
channel-mask: 0x0000000000000003
|
|
|
|
|
|
Element Flags:
|
|
no flags set
|
|
|
|
Element Implementation:
|
|
Has change_state() function: gst_audio_base_sink_change_state
|
|
|
|
Clocking Interaction:
|
|
element is supposed to provide a clock but returned NULL
|
|
|
|
Element has no indexing capabilities.
|
|
Element has no URI handling capabilities.
|
|
|
|
Pads:
|
|
SINK: 'sink'
|
|
Implementation:
|
|
Has chainfunc(): gst_base_sink_chain
|
|
Has custom eventfunc(): gst_base_sink_event
|
|
Has custom queryfunc(): gst_base_sink_sink_query
|
|
Has custom iterintlinkfunc(): gst_pad_iterate_internal_links_default
|
|
Pad Template: 'sink'
|
|
|
|
Element Properties:
|
|
name : The name of the object
|
|
flags: readable, writable
|
|
String. Default: "osssink0"
|
|
parent : The parent of the object
|
|
flags: readable, writable
|
|
Object of type "GstObject"
|
|
sync : Sync on the clock
|
|
flags: readable, writable
|
|
Boolean. Default: true
|
|
max-lateness : Maximum number of nanoseconds that a buffer can be late before it is dropped (-1 unlimited)
|
|
flags: readable, writable
|
|
Integer64. Range: -1 - 9223372036854775807 Default: -1
|
|
qos : Generate Quality-of-Service events upstream
|
|
flags: readable, writable
|
|
Boolean. Default: false
|
|
async : Go asynchronously to PAUSED
|
|
flags: readable, writable
|
|
Boolean. Default: true
|
|
ts-offset : Timestamp offset in nanoseconds
|
|
flags: readable, writable
|
|
Integer64. Range: -9223372036854775808 - 9223372036854775807 Default: 0
|
|
enable-last-sample : Enable the last-sample property
|
|
flags: readable, writable
|
|
Boolean. Default: false
|
|
last-sample : The last sample received in the sink
|
|
flags: readable
|
|
Boxed pointer of type "GstSample"
|
|
blocksize : Size in bytes to pull per buffer (0 = default)
|
|
flags: readable, writable
|
|
Unsigned Integer. Range: 0 - 4294967295 Default: 4096
|
|
render-delay : Additional render delay of the sink in nanoseconds
|
|
flags: readable, writable
|
|
Unsigned Integer64. Range: 0 - 18446744073709551615 Default: 0
|
|
throttle-time : The time to keep between rendered buffers
|
|
flags: readable, writable
|
|
Unsigned Integer64. Range: 0 - 18446744073709551615 Default: 0
|
|
buffer-time : Size of audio buffer in microseconds, this is the minimum latency that the sink reports
|
|
flags: readable, writable
|
|
Integer64. Range: 1 - 9223372036854775807 Default: 200000
|
|
latency-time : The minimum amount of data to write in each iteration in microseconds
|
|
flags: readable, writable
|
|
Integer64. Range: 1 - 9223372036854775807 Default: 10000
|
|
provide-clock : Provide a clock to be used as the global pipeline clock
|
|
flags: readable, writable
|
|
Boolean. Default: true
|
|
slave-method : Algorithm to use to match the rate of the masterclock
|
|
flags: readable, writable
|
|
Enum "GstAudioBaseSinkSlaveMethod" Default: 1, "skew"
|
|
(0): resample - GST_AUDIO_BASE_SINK_SLAVE_RESAMPLE
|
|
(1): skew - GST_AUDIO_BASE_SINK_SLAVE_SKEW
|
|
(2): none - GST_AUDIO_BASE_SINK_SLAVE_NONE
|
|
can-activate-pull : Allow pull-based scheduling
|
|
flags: readable, writable
|
|
Boolean. Default: false
|
|
alignment-threshold : Timestamp alignment threshold in nanoseconds
|
|
flags: readable, writable
|
|
Unsigned Integer64. Range: 1 - 18446744073709551614 Default: 40000000
|
|
drift-tolerance : Tolerance for clock drift in microseconds
|
|
flags: readable, writable
|
|
Integer64. Range: 1 - 9223372036854775807 Default: 40000
|
|
discont-wait : Window of time in nanoseconds to wait before creating a discontinuity
|
|
flags: readable, writable
|
|
Unsigned Integer64. Range: 0 - 18446744073709551614 Default: 1000000000
|
|
device : OSS device (usually /dev/dspN)
|
|
flags: readable, writable
|
|
String. Default: "/dev/dsp"
|
|
]]>
|
|
</screen>
|
|
|
|
<para>
|
|
To query the information about a plugin, you would do:
|
|
</para>
|
|
|
|
<screen>
|
|
gst-inspect gstelements
|
|
</screen>
|
|
</sect1>
|
|
|
|
</chapter>
|