Object Hierarchy:

Object hierarchy for Element


public abstract class Element : Object

GstElement is the abstract base class needed to construct an element that can be used in a GStreamer pipeline.

Please refer to the plugin writers guide for more information on creating Element subclasses.

The name of a Element can be get with gst_element_get_name and set with gst_element_set_name. For speed, GST_ELEMENT_NAME can be used in the core when using the appropriate locking. Do not use this in plug-ins or applications in order to retain ABI compatibility.

Elements can have pads (of the type Pad). These pads link to pads on other elements. Buffer flow between these linked pads. A Element has a List of Pad structures for all their input (or sink) and output (or source) pads. Core and plug-in writers can add and remove pads with add_pad and remove_pad.

An existing pad of an element can be retrieved by name with get_static_pad. A new dynamic pad can be created using request_pad with a PadTemplate. An iterator of all pads can be retrieved with iterate_pads.

Elements can be linked through their pads. If the link is straightforward, use the link convenience function to link two elements, or link_many for more elements in a row. Use link_filtered to link two elements constrained by a specified set of Caps. For finer control, use gst_element_link_pads and link_pads_filtered to specify the pads to link on each element by name.

Each element has a state (see State). You can get and set the state of an element with get_state and set_state. Setting a state triggers a StateChange. To get a string representation of a State, use state_get_name.

You can get and set a Clock on an element using get_clock and set_clock. Some elements can provide a clock for the pipeline if the PROVIDE_CLOCK flag is set. With the provide_clock method one can retrieve the clock provided by such an element. Not all elements require a clock to operate correctly. If the REQUIRE_CLOCK() flag is set, a clock should be set on the element with set_clock.

Note that clock selection and distribution is normally handled by the toplevel Pipeline so the clock functions are only to be used in very specific situations.

Example: Dynamic pipelines:

// See http://docs.gstreamer.com/x/aAAF
// for a detailed description

public class Main {
private Gst.Pipeline pipeline;
private Gst.Element source;
private Gst.Element convert;
private Gst.Element sink;

// Handler for the pad-added signal.
// This function will be called by the pad-added signal.
private void pad_added_handler (Gst.Element src, Gst.Pad new_pad) {
Gst.Pad sink_pad = this.convert.get_static_pad ("sink");
print ("Received new pad '%s' from '%s':\n", new_pad.name, src.name);

// If our converter is already linked, we have nothing to do here:
if (sink_pad.is_linked ()) {
print (" We are already linked. Ignoring.\n");
return ;

// Check the new pad's type:
Gst.Caps new_pad_caps = new_pad.query_caps (null);
weak Gst.Structure new_pad_struct = new_pad_caps.get_structure (0);
string new_pad_type = new_pad_struct.get_name ();
if (!new_pad_type.has_prefix ("audio/x-raw")) {
print (" It has type '%s' which is not raw audio. Ignoring.\n", new_pad_type);
return ;

// Attempt the link:
Gst.PadLinkReturn ret = new_pad.link (sink_pad);
if (ret != Gst.PadLinkReturn.OK) {
print (" Type is '%s' but link failed.\n", new_pad_type);
} else {
print (" Link succeeded (type '%s').\n", new_pad_type);

// Example runner
public int run () {
// Create the elements:
this.source = Gst.ElementFactory.make ("uridecodebin", "source");
this.convert = Gst.ElementFactory.make ("audioconvert", "convert");
this.sink = Gst.ElementFactory.make ("autoaudiosink", "sink");

// Create the empty pipeline:
this.pipeline = new Gst.Pipeline ("test-pipeline");

if (this.pipeline == null || this.source == null || this.convert == null || this.sink == null) {
print ("Not all elements could be created.\n");
return -1;

// Build the pipeline. Note that we are NOT linking the source at this
// point. We will do it later.

this.pipeline.add_many (this.source, this.convert , this.sink);
if (!this.convert.link (this.sink)) {
print ("Elements could not be linked.\n");
return -1;

// Set the URI to play:
this.source.set ("uri", "http://docs.gstreamer.com/media/sintel_trailer-480p.webm");

// Connect to the pad-added signal:
this.source.pad_added.connect (pad_added_handler);

// Start playing:
Gst.StateChangeReturn ret = this.pipeline.set_state (Gst.State.PLAYING);
if (ret == Gst.StateChangeReturn.FAILURE) {
stderr.puts ("Unable to set the pipeline to the playing state.\n");
return -1;

// Listen to the bus:
Gst.Bus bus = this.pipeline.get_bus ();
bool terminate = false;
do {
Gst.Message msg = bus.timed_pop_filtered (Gst.CLOCK_TIME_NONE,
Gst.MessageType.STATE_CHANGED | Gst.MessageType.ERROR | Gst.MessageType.EOS);

// Parse message:
if (msg != null) {
switch (msg.type) {
case Gst.MessageType.ERROR:
GLib.Error err;
string debug_info;

msg.parse_error (out err, out debug_info);
stderr.printf ("Error received from element %s: %s\n", msg.src.name, err.message);
stderr.printf ("Debugging information: %s\n", (debug_info != null)? debug_info : "none");
terminate = true;

case Gst.MessageType.EOS:
print ("End-Of-Stream reached.\n");
terminate = true;

case Gst.MessageType.STATE_CHANGED:
// We are only interested in state-changed messages from the pipeline:
if (msg.src == this.pipeline) {
Gst.State old_state;
Gst.State new_state;
Gst.State pending_state;

msg.parse_state_changed (out old_state, out new_state, out pending_state);
print ("Pipeline state changed from %s to %s:\n",
Gst.Element.state_get_name (old_state),
Gst.Element.state_get_name (new_state));

//We should not reach here:
assert_not_reached ();
} while (!terminate);

// Free resources:
bus = null;
this.pipeline.set_state (Gst.State.NULL);
this.pipeline = null;

return 0;

public static int main (string[] args) {
// Initialize GStreamer:
Gst.init (ref args);

// Run the example:
return new Main ().run ();

valac --pkg gstreamer-1.0 dynamic-pipelines.vala

All known sub-classes:
Required by:

Namespace: Gst
Package: gstreamer-1.0


Static methods:

Creation methods:




Inherited Members: