1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
<chapter id="chapter-checklist-element">
<title>Things to check when writing an application</title>
<para>
This chapter contains a fairly random selection of things that can be
useful to keep in mind when writing &GStreamer;-based applications. It's
up to you how much you're going to use the information provided here.
We will shortly discuss how to debug pipeline problems using &GStreamer;
applications. Also, we will touch upon how to acquire knowledge about
plugins and elements and how to test simple pipelines before building
applications around them.
</para>
<sect1 id="section-checklist-programming">
<title>Good programming habits</title>
<itemizedlist>
<listitem>
<para>
Always add a <classname>GstBus</classname> handler to your
pipeline. Always report errors in your application, and try
to do something with warnings and information messages, too.
</para>
</listitem>
<listitem>
<para>
Always check return values of &GStreamer; functions. Especially,
check return values of <function>gst_element_link ()</function>
and <function>gst_element_set_state ()</function>.
</para>
</listitem>
<listitem>
<para>
Dereference return values of all functions returning a non-base
type, such as <function>gst_element_get_pad ()</function>. Also,
always free non-const string returns, such as
<function>gst_object_get_name ()</function>.
</para>
</listitem>
<listitem>
<para>
Always use your pipeline object to keep track of the current state
of your pipeline. Don't keep private variables in your application.
Also, don't update your user interface if a user presses the
<quote>play</quote> button. Instead, listen for the
<quote>state-changed</quote> message on the
<classname>GstBus</classname> and only update the user interface
whenever this message is received.
</para>
</listitem>
<listitem>
<para>
Report all bugs that you find in &GStreamer; bugzilla at
<ulink type="http"
url="http://bugzilla.gnome.org">http://bugzilla.gnome.org/</ulink>.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="section-checklist-debug">
<title>Debugging</title>
<para>
Applications can make use of the extensive &GStreamer; debugging system
to debug pipeline problems. Elements will write output to this system
to log what they're doing. It's not used for error reporting, but it
is very useful for tracking what an element is doing exactly, which
can come in handy when debugging application issues (such as failing
seeks, out-of-sync media, etc.).
</para>
<para>
Most &GStreamer;-based applications accept the commandline option
<option>--gst-debug=LIST</option> and related family members. The
list consists of a comma-separated list of category/level pairs,
which can set the debugging level for a specific debugging category.
For example, <option>--gst-debug=oggdemux:5</option> would turn
on debugging for the Ogg demuxer element. You can use wildcards as
well. A debugging level of 0 will turn off all debugging, and a level
of 9 will turn on all debugging. Intermediate values only turn on
some debugging (based on message severity; 2, for example, will only
display errors and warnings). Here's a list of all available options:
</para>
<para>
<itemizedlist>
<listitem>
<para>
<option>--gst-debug-help</option> will print available debug
categories and exit.
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug-level=<replaceable>LEVEL</replaceable></option>
will set the default debug level (which can range from 0 (no
output) to 5 (everything)).
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug=<replaceable>LIST</replaceable></option>
takes a comma-separated list of category_name:level pairs to
set specific levels for the individual categories. Example:
<option>GST_AUTOPLUG:5,avidemux:3</option>. Alternatively, you
can also set the <classname>GST_DEBUG</classname> environment
variable, which has the same effect.
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug-no-color</option> will disable color debugging.
You can also set the GST_DEBUG_NO_COLOR environment variable to 1
if you want to disable colored debug output permanently. Note that
if you are disabling color purely to avoid messing up your pager
output, try using <command>less -R</command>.
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug-color-mode=<replaceable>MODE</replaceable></option>
will change debug log coloring mode. <replaceable>MODE</replaceable>
can be one of the following: <option>on</option>,
<option>off</option>, <option>auto</option>,
<option>disable</option>, <option>unix</option>.
You can also set the GST_DEBUG_COLOR_MODE environment variable
if you want to change colored debug output permanently. Note that
if you are disabling color purely to avoid messing up your pager
output, try using <command>less -R</command>.
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug-disable</option> disables debugging altogether.
</para>
</listitem>
<listitem>
<para>
<option>--gst-plugin-spew</option> enables printout of errors while
loading &GStreamer; plugins.
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="section-checklist-conversion">
<title>Conversion plugins</title>
<para>
&GStreamer; contains a bunch of conversion plugins that most
applications will find useful. Specifically, those are videoscalers
(videoscale), colorspace convertors (videoconvert), audio format
convertors and channel resamplers (audioconvert) and audio samplerate
convertors (audioresample). Those convertors don't do anything when not
required, they will act in passthrough mode. They will activate when
the hardware doesn't support a specific request, though. All
applications are recommended to use those elements.
</para>
</sect1>
<sect1 id="section-checklist-applications">
<title>Utility applications provided with &GStreamer;</title>
<para>
&GStreamer; comes with a default set of command-line utilities that
can help in application development. We will discuss only
<command>gst-launch</command> and <command>gst-inspect</command> here.
</para>
<sect2 id="section-applications-launch">
<title><command>gst-launch</command></title>
<para>
<command>gst-launch</command> is a simple script-like commandline
application that can be used to test pipelines. For example, the
command <command>gst-launch audiotestsrc ! audioconvert !
audio/x-raw,channels=2 ! alsasink</command> will run
a pipeline which generates a sine-wave audio stream and plays it
to your ALSA audio card. <command>gst-launch</command> also allows
the use of threads (will be used automatically as required or as queue
elements are inserted in the pipeline) and bins (using brackets, so
<quote>(</quote> and <quote>)</quote>). You can use dots to imply
padnames on elements,
or even omit the padname to automatically select a pad. Using
all this, the pipeline
<command>gst-launch filesrc location=file.ogg ! oggdemux name=d
d. ! queue ! theoradec ! videoconvert ! xvimagesink
d. ! queue ! vorbisdec ! audioconvert ! audioresample ! alsasink
</command> will play an Ogg file
containing a Theora video-stream and a Vorbis audio-stream. You can
also use autopluggers such as decodebin on the commandline. See the
manual page of <command>gst-launch</command> for more information.
</para>
</sect2>
<sect2 id="section-applications-inspect">
<title><command>gst-inspect</command></title>
<para>
<command>gst-inspect</command> can be used to inspect all properties,
signals, dynamic parameters and the object hierarchy of an element.
This can be very useful to see which <classname>GObject</classname>
properties or which signals (and using what arguments) an element
supports. Run <command>gst-inspect fakesrc</command> to get an idea
of what it does. See the manual page of <command>gst-inspect</command>
for more information.
</para>
</sect2>
</sect1>
</chapter>
|
