mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-25 11:11:08 +00:00
163 lines
7.1 KiB
XML
163 lines
7.1 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 connect to the <quote>error</quote> signal of your topmost
|
|
pipeline to be notified of errors in your pipeline.
|
|
</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>
|
|
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, connect to the
|
|
<quote>state-changed</quote> signal of your topmost pipeline and
|
|
update the user interface whenever this signal is triggered.
|
|
</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 5 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>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<option>--gst-debug-no-color</option> will disable color debugging.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<option>--gst-debug-disable</option> disables debugging alltogether.
|
|
</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 (ffmpegcolorspace), audio format
|
|
convertors and channel resamplers (audioconvert) and audio samplerate
|
|
convertors (audioscale). 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 sinesrc ! 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 (using curly brackets, so <quote>{</quote>
|
|
and <quote>}</quote>) 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. ! theoradec ! ffmpegcolorspace ! xvimagesink
|
|
} { d. ! vorbisdec ! 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>
|