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