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;
break;
case Gst.MessageType.EOS:
print ("End-Of-Stream reached.\n");
terminate = true;
break;
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));
}
break;
default:
//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
- public void abort_state ()
Abort the state change of the element.
- public class void add_metadata (string key, string value)
Set key with value as metadata in
this.
- public bool add_pad (Pad pad)
Adds a pad (link point) to this.
- public class void add_pad_template (PadTemplate templ)
Adds a padtemplate to an element class.
- public ulong add_property_deep_notify_watch (string? property_name, bool include_value)
- public ulong add_property_notify_watch (string? property_name, bool include_value)
- public class void add_static_metadata (string key, string value)
Set key with value as metadata in
this.
- public class void add_static_pad_template (StaticPadTemplate static_templ)
Adds a pad template to an element class based on the static pad template
templ.
- public class void add_static_pad_template_with_gtype (StaticPadTemplate static_templ, Type pad_type)
Adds a pad template to an element class based on the static pad template
templ.
- public void call_async (owned ElementCallAsyncFunc func)
Calls func from another thread and passes user_data
to it.
- public virtual StateChangeReturn change_state (StateChange transition)
Perform transition on this.
- public class unowned string class_get_metadata (string key)
Get metadata with key in this
.
- public class unowned PadTemplate? class_get_pad_template (string name)
Retrieves a padtemplate from this with the
given name.
- public class unowned List<PadTemplate> class_get_pad_template_list ()
Retrieves a list of the pad templates associated with
this.
- public StateChangeReturn continue_state (StateChangeReturn ret)
Commit the state change of the element and proceed to the next pending state
if any.
- public void create_all_pads ()
Creates a pad for each pad template that is always available.
- public string decorate_stream_id (string stream_id)
Creates a stream-id for this by combining
the upstream information with the stream_id.
- public string decorate_stream_id_printf_valist (string format, va_list var_args)
Creates a stream-id for this by combining
the upstream information with the format.
- public bool foreach_pad (ElementForeachPadFunc func)
Call func with user_data for each of
this's pads.
- public bool foreach_sink_pad (ElementForeachPadFunc func)
Call func with user_data for each of
this's sink pads.
- public bool foreach_src_pad (ElementForeachPadFunc func)
Call func with user_data for each of
this's source pads.
- public ClockTime get_base_time ()
Returns the base time of the element.
- public Bus? get_bus ()
Returns the bus of the element.
- public Clock? get_clock ()
Gets the currently configured clock of the element.
- public Pad? get_compatible_pad (Pad pad, Caps? caps)
Looks for an unlinked pad to which the given pad can link.
- public unowned PadTemplate? get_compatible_pad_template (PadTemplate compattempl)
Retrieves a pad template from this that is
compatible with compattempl.
- public Context? get_context (string context_type)
Gets the context with context_type set on the element or NULL.
- public Context? get_context_unlocked (string context_type)
Gets the context with context_type set on the element or NULL.
- public List<Context> get_contexts ()
Gets the contexts set on the element.
- public ClockTime get_current_clock_time ()
Returns the current clock time of the element, as in, the time of the
element's clock, or GST_CLOCK_TIME_NONE if there is no clock.
- public ClockTime get_current_running_time ()
Returns the running time of the element.
- public unowned ElementFactory? get_factory ()
Retrieves the factory that was used to create this element.
- public unowned string get_metadata (string key)
Get metadata with key in klass.
- public unowned PadTemplate? get_pad_template (string name)
Retrieves a padtemplate from this with the
given name.
- public unowned List<PadTemplate> get_pad_template_list ()
Retrieves a list of the pad templates associated with
this.
- public Pad? get_request_pad (string name)
The name of this function is confusing to people learning GStreamer.
- public ClockTime get_start_time ()
Returns the start time of the element.
- public virtual StateChangeReturn get_state (out State state, out State pending, ClockTime timeout)
Gets the state of the element.
- public Pad? get_static_pad (string name)
Retrieves a pad from this by name.
- public bool is_locked_state ()
Checks if the state of an element is locked.
- public Iterator iterate_pads ()
Retrieves an iterator of this's pads.
- public Iterator iterate_sink_pads ()
Retrieves an iterator of this's sink pads.
- public Iterator iterate_src_pads ()
Retrieves an iterator of this's source
pads.
- public bool link (Element dest)
Links this to dest.
- public bool link_filtered (Element dest, Caps? filter)
Links this to dest using the
given caps as filtercaps.
- public bool link_many (Element[] elements)
Chain together a series of elements.
- public bool link_pads (string? srcpadname, Element dest, string? destpadname, PadLinkCheck flags = DEFAULT)
Links the two named pads of the source and destination elements.
- public bool link_pads_filtered (string? srcpadname, Element dest, string? destpadname, Caps? filter)
Links the two named pads of the source and destination elements.
- public void lost_state ()
Brings the element to the lost state.
- public void message_full (MessageType type, Quark domain, int code, owned string? text, owned string? debug, string file, string function, int line)
Post an error, warning or info message on the bus from inside an element.
- public void message_full_with_details (MessageType type, Quark domain, int code, owned string? text, owned string? debug, string file, string function, int line, owned Structure structure)
Post an error, warning or info message on the bus from inside an element.
- public virtual bool post_message (owned Message message)
Post a message on the element's
Bus.
- public virtual Clock? provide_clock ()
Get the clock provided by the given element.
- public virtual bool query (Query query)
Performs a query on the given element.
- public bool query_convert (Format src_format, int64 src_val, Format dest_format, out int64 dest_val)
Queries an element to convert src_val in src_format
to dest_format.
- public bool query_duration (Format format, out int64 duration)
Queries an element (usually top-level pipeline or playbin element) for the
total stream duration in nanoseconds.
- public bool query_position (Format format, out int64 cur)
Queries an element (usually top-level pipeline or playbin element) for the
stream position in nanoseconds.
- public virtual void release_pad (Pad pad)
- public void release_request_pad (Pad pad)
Makes the element free the previously requested pad as obtained with
request_pad.
- public bool remove_pad (Pad pad)
Removes pad from this.
- public void remove_property_notify_watch (ulong watch_id)
- public virtual Pad? request_pad (PadTemplate templ, string? name, Caps? caps)
Retrieves a request pad from the element according to the provided template.
- public Pad? request_pad_simple (string name)
Retrieves a pad from the element by name (e.g. "src_\%d").
- public bool seek (double rate, Format format, SeekFlags flags, SeekType start_type, int64 start, SeekType stop_type, int64 stop)
Sends a seek event to an element.
- public bool seek_simple (Format format, SeekFlags seek_flags, int64 seek_pos)
Simple API to perform a seek on the given element, meaning it just seeks to
the given position relative to the start of the stream.
- public virtual bool send_event (owned Event event)
Sends an event to an element.
- public void set_base_time (ClockTime time)
Set the base time of an element.
- public virtual void set_bus (Bus? bus)
Sets the bus of the element.
- public virtual bool set_clock (Clock? clock)
Sets the clock for the element.
- public virtual void set_context (Context context)
Sets the context of the element.
- public bool set_locked_state (bool locked_state)
Locks the state of an element, so state changes of the parent don't affect
this element anymore.
- public class void set_metadata (string longname, string classification, string description, string author)
Sets the detailed information for a Element
.
- public void set_start_time (ClockTime time)
Set the start time of an element.
- public virtual StateChangeReturn set_state (State state)
Sets the state of the element.
- public class void set_static_metadata (string longname, string classification, string description, string author)
Sets the detailed information for a Element
.
- public virtual void state_changed (State oldstate, State newstate, State pending)
- public bool sync_state_with_parent ()
Tries to change the state of the element to the same as its parent.
- public void unlink (Element dest)
Unlinks all source pads of the source element with all sink pads of the sink
element to which they are linked.
- public void unlink_many (Element[] elements)
Unlinks a series of elements.
- public void unlink_pads (string srcpadname, Element dest, string destpadname)
Unlinks the two named pads of the source and destination elements.