2 title: Things to check when writing an element
5 # Things to check when writing an element
7 This chapter contains a fairly random selection of things to take care
8 of when writing an element. It's up to you how far you're going to stick
9 to those guidelines. However, keep in mind that when you're writing an
10 element and hope for it to be included in the mainstream GStreamer
11 distribution, it *has to* meet those requirements. As far as possible,
12 we will try to explain why those requirements are set.
16 - Make sure the state of an element gets reset when going to `NULL`.
17 Ideally, this should set all object properties to their original
18 state. This function should also be called from \_init.
20 - Make sure an element forgets *everything* about its contained stream
21 when going from `PAUSED` to `READY`. In `READY`, all stream states
22 are reset. An element that goes from `PAUSED` to `READY` and back to
23 `PAUSED` should start reading the stream from the start again.
25 - People that use `gst-launch` for testing have the tendency to not
26 care about cleaning up. This is *wrong*. An element should be tested
27 using various applications, where testing not only means to “make
28 sure it doesn't crash”, but also to test for memory leaks using
29 tools such as `valgrind`. Elements have to be reusable in a pipeline
30 after having been reset.
34 - Elements should *never* use their standard output for debugging
35 (using functions such as `printf
36 ()` or `g_print ()`). Instead, elements should use the logging
37 functions provided by GStreamer, named `GST_DEBUG ()`, `GST_LOG ()`,
38 `GST_INFO ()`, `GST_WARNING ()` and `GST_ERROR ()`. The various
39 logging levels can be turned on and off at runtime and can thus be
40 used for solving issues as they turn up. Instead of `GST_LOG ()` (as
41 an example), you can also use `GST_LOG_OBJECT
42 ()` to print the object that you're logging output for.
44 - Ideally, elements should use their own debugging category. Most
45 elements use the following code to do that:
48 GST_DEBUG_CATEGORY_STATIC (myelement_debug);
49 #define GST_CAT_DEFAULT myelement_debug
54 gst_myelement_class_init (GstMyelementClass *klass)
57 GST_DEBUG_CATEGORY_INIT (myelement_debug, "myelement",
63 At runtime, you can turn on debugging using the commandline option
64 `--gst-debug=myelement:5`.
66 - Elements should use GST\_DEBUG\_FUNCPTR when setting pad functions
67 or overriding element class methods, for example:
70 gst_pad_set_event_func (myelement->srcpad,
71 GST_DEBUG_FUNCPTR (my_element_src_event));
75 This makes debug output much easier to read later on.
77 - Elements that are aimed for inclusion into one of the GStreamer
78 modules should ensure consistent naming of the element name,
79 structures and function names. For example, if the element type is
80 GstYellowFooDec, functions should be prefixed with
81 gst\_yellow\_foo\_dec\_ and the element should be registered as
82 'yellowfoodec'. Separate words should be separate in this scheme, so
83 it should be GstFooDec and gst\_foo\_dec, and not GstFoodec and
86 ## Querying, events and the like
88 - All elements to which it applies (sources, sinks, demuxers) should
89 implement query functions on their pads, so that applications and
90 neighbour elements can request the current position, the stream
91 length (if known) and so on.
93 - Elements should make sure they forward events they do not handle
94 with gst\_pad\_event\_default (pad, parent, event) instead of just
95 dropping them. Events should never be dropped unless specifically
98 - Elements should make sure they forward queries they do not handle
99 with gst\_pad\_query\_default (pad, parent, query) instead of just
102 ## Testing your element
104 - `gst-launch` is *not* a good tool to show that your element is
105 finished. Applications such as Rhythmbox and Totem (for GNOME) or
106 AmaroK (for KDE) *are*. `gst-launch` will not test various things
107 such as proper clean-up on reset, event handling, querying and so
110 - Parsers and demuxers should make sure to check their input. Input
111 cannot be trusted. Prevent possible buffer overflows and the like.
112 Feel free to error out on unrecoverable stream errors. Test your
113 demuxer using stream corruption elements such as `breakmydata`
114 (included in gst-plugins). It will randomly insert, delete and
115 modify bytes in a stream, and is therefore a good test for
116 robustness. If your element crashes when adding this element, your
117 element needs fixing. If it errors out properly, it's good enough.
118 Ideally, it'd just continue to work and forward data as much as
121 - Demuxers should not assume that seeking works. Be prepared to work
122 with unseekable input streams (e.g. network sources) as well.
124 - Sources and sinks should be prepared to be assigned another clock
125 then the one they expose themselves. Always use the provided clock
126 for synchronization, else you'll get A/V sync issues.