mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-04 15:36:35 +00:00
9d63968830
In the docs and the autocompletion logic the maximum value jumped incongruently between 5 and 9.
204 lines
8.9 KiB
XML
204 lines
8.9 KiB
XML
<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 9 (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>
|