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
|
---
title: Things to check when writing an application
...
# Things to check when writing an application
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.
## Good programming habits
- Always add a `GstBus` handler to your pipeline. Always report errors
in your application, and try to do something with warnings and
information messages, too.
- Always check return values of GStreamer functions. Especially, check
return values of `gst_element_link ()` and `gst_element_set_state
()`.
- Dereference return values of all functions returning a non-base
type, such as `gst_element_get_pad ()`. Also, always free non-const
string returns, such as `gst_object_get_name ()`.
- 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 “play”
button. Instead, listen for the “state-changed” message on the
`GstBus` and only update the user interface whenever this message is
received.
- Report all bugs that you find in GStreamer bugzilla at
[http://bugzilla.gnome.org/](http://bugzilla.gnome.org).
## Debugging
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.).
Most GStreamer-based applications accept the commandline option
`--gst-debug=LIST` 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,
`--gst-debug=oggdemux:5` 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:
- `--gst-debug-help` will print available debug categories and exit.
- `--gst-debug-level=LEVEL` will set the default debug level (which
can range from 0 (no output) to 9 (everything)).
- `--gst-debug=LIST` takes a comma-separated list of
category\_name:level pairs to set specific levels for the individual
categories. Example: `GST_AUTOPLUG:5,avidemux:3`. Alternatively, you
can also set the `GST_DEBUG` environment variable, which has the
same effect.
- `--gst-debug-no-color` 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 `less -R`.
- `--gst-debug-color-mode=MODE` will change debug log coloring mode.
MODE can be one of the following: `on`, `off`, `auto`, `disable`,
`unix`. 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 `less -R`.
- `--gst-debug-disable` disables debugging altogether.
- `--gst-plugin-spew` enables printout of errors while loading
GStreamer plugins.
## Conversion plugins
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.
## Utility applications provided with GStreamer
GStreamer comes with a default set of command-line utilities that can
help in application development. We will discuss only `gst-launch` and
`gst-inspect` here.
### `gst-launch`
`gst-launch` is a simple script-like commandline application that can be
used to test pipelines. For example, the command `gst-launch
audiotestsrc ! audioconvert !
audio/x-raw,channels=2 ! alsasink` will run a pipeline which generates a
sine-wave audio stream and plays it to your ALSA audio card.
`gst-launch` 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 “(” and “)”). You can use dots to imply padnames on
elements, or even omit the padname to automatically select a pad. Using
all this, the pipeline `gst-launch filesrc location=file.ogg ! oggdemux
name=d
d. ! queue ! theoradec ! videoconvert ! xvimagesink
d. ! queue ! vorbisdec ! audioconvert ! audioresample ! alsasink
` 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 `gst-launch` for more information.
### `gst-inspect`
`gst-inspect` 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 `GObject` properties or which signals (and using
what arguments) an element supports. Run `gst-inspect fakesrc` to get an
idea of what it does. See the manual page of `gst-inspect` for more
information.
|
