gstreamer/docs/manual/appendix-programs.xml
Andy Wingo 70cfc6cb4d new parser that uses flex and bison
Original commit message from CVS:
* new parser that uses flex and bison
- doesn't do dynamic pipelines yet...
* added GErrors to the gst_parse_launch[v] api
* added --gst-mask-help command line option
* fixed -o option for gst-launch
* GstElement api change:
- gst_element_get_pad
- gst_element_get_request_pad, gst_element_get_static_pad
- gst_element_get_compatible_pad
- gst_element_get_compatible_static_pad, gst_element_get_compatible_request_pad
- gst_element_[dis]connect -> gst_element_[dis]connect_pads
- gst_element_[dis]connect_elements -> gst_element_[dis]connect
* manual update
* example, tool, and doc updates for the api changes
- no more plugin docs in the core docs, plugins require a more
extensive doc system
2002-04-07 23:32:16 +00:00

189 lines
4.9 KiB
XML

<chapter id="cha-programs">
<title>Programs</title>
<para>
</para>
<sect1>
<title><command>gst-register</command></title>
<para>
<command>gst-register</command> is used to rebuild the database of plugins.
It is used after a new plugin has been added to the system. The plugin database
can be found, by default, in <filename>/etc/gstreamer/reg.xml</filename>.
</para>
</sect1>
<sect1>
<title><command>gst-launch</command></title>
<para>
This is a tool that will construct pipelines based on a command-line
syntax. FIXME: need a more extensive grammar reference
</para>
<para>
A simple commandline looks like:
<screen>
gst-launch filesrc location=hello.mp3 ! mad ! osssink
</screen>
A more complex pipeline looks like:
<screen>
gst-launch filesrc location=redpill.vob ! mpegdemux name=demux \
demux.audio_00! { ac3parse ! a52dec ! osssink } \
demux.video_00! { mpeg2dec ! xvideosink }
</screen>
</para>
<para>
You can also use the the parser in you own code. <application>GStreamer</application>
provides a function gst_parse_launch () that you can use to construt a pipeline.
The following programs 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;
GError *error = NULL;
gst_init (&amp;argc, &amp;argv);
if (argc != 2) {
g_print ("usage: &percnt;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: &percnt;s\n", error->message);
exit (1);
}
filesrc = gst_bin_get_by_name (GST_BIN (pipeline), "my_filesrc");
g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
gst_element_set_state (pipeline, GST_STATE_PLAYING);
while (gst_bin_iterate (GST_BIN (pipeline)));
gst_element_set_state (pipeline, GST_STATE_NULL);
return 0;
}
</programlisting>
<para>
Note how we can retrieve the filesrc element from the constructed bin using the
element name.
</para>
</sect1>
<sect1>
<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>
<sect1>
<title><command>gst-play</command></title>
<para>
A sample media player.
</para>
</sect1>
</chapter>