mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-27 04:01:08 +00:00
7c24fc7450
MIME-type -> media types Fix up the manual in various places with the 1.0 way of doing things such as probes, static elements, scheduling, ... Add porting from 0.10 to 1.0 chapter. Add probe example to build. Remove some docs for remove components such as GstMixer and GstPropertyProbe, XML...
191 lines
8.3 KiB
XML
191 lines
8.3 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 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-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>
|