:right-sidebar: True Element =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Element(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gst.Object`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Gst.Bin` 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 :obj:`~gi.repository.Gst.Element` subclasses. The name of a :obj:`~gi.repository.Gst.Element` can be get with :func:`~gi.repository.Gst.element_get_name` and set with :func:`~gi.repository.Gst.element_set_name`. For speed, :func:`~gi.repository.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 :obj:`~gi.repository.Gst.Pad`\). These pads link to pads on other elements. :obj:`~gi.repository.Gst.Buffer` flow between these linked pads. A :obj:`~gi.repository.Gst.Element` has a ``GList`` of :obj:`~gi.repository.Gst.Pad` structures for all their input (or sink) and output (or source) pads. Core and plug-in writers can add and remove pads with :func:`~gi.repository.Gst.Element.add_pad` and :func:`~gi.repository.Gst.Element.remove_pad`. An existing pad of an element can be retrieved by name with :func:`~gi.repository.Gst.Element.get_static_pad`. A new dynamic pad can be created using :func:`~gi.repository.Gst.Element.request_pad` with a :obj:`~gi.repository.Gst.PadTemplate`\. An iterator of all pads can be retrieved with :func:`~gi.repository.Gst.Element.iterate_pads`. Elements can be linked through their pads. If the link is straightforward, use the :func:`~gi.repository.Gst.Element.link` convenience function to link two elements, or :func:`~gi.repository.Gst.Element.link_many` for more elements in a row. Use :func:`~gi.repository.Gst.Element.link_filtered` to link two elements constrained by a specified set of :obj:`~gi.repository.Gst.Caps`\. For finer control, use :func:`~gi.repository.Gst.Element.link_pads` and :func:`~gi.repository.Gst.Element.link_pads_filtered` to specify the pads to link on each element by name. Each element has a state (see :obj:`~gi.repository.Gst.State`\). You can get and set the state of an element with :func:`~gi.repository.Gst.Element.get_state` and :func:`~gi.repository.Gst.Element.set_state`. Setting a state triggers a :obj:`~gi.repository.Gst.StateChange`\. To get a string representation of a :obj:`~gi.repository.Gst.State`\, use :func:`~gi.repository.Gst.Element.state_get_name`. You can get and set a :obj:`~gi.repository.Gst.Clock` on an element using :func:`~gi.repository.Gst.Element.get_clock` and :func:`~gi.repository.Gst.Element.set_clock`. Some elements can provide a clock for the pipeline if the ``GST_ELEMENT_FLAG_PROVIDE_CLOCK`` flag is set. With the :func:`~gi.repository.Gst.Element.provide_clock` method one can retrieve the clock provided by such an element. Not all elements require a clock to operate correctly. If the #GST_ELEMENT_FLAG_REQUIRE_CLOCK() flag is set, a clock should be set on the element with :func:`~gi.repository.Gst.Element.set_clock`. Note that clock selection and distribution is normally handled by the toplevel :obj:`~gi.repository.Gst.Pipeline` so the clock functions are only to be used in very specific situations. Methods ------- .. rst-class:: interim-class .. class:: Element :no-index: .. method:: abort_state() -> None Abort the state change of the element. This function is used by elements that do asynchronous state changes and find out something is wrong. This function should be called with the STATE_LOCK held. MT safe. .. classmethod:: add_metadata(key: str, value: str) -> None :param key: :param value: .. method:: add_pad(pad: ~gi.repository.Gst.Pad) -> bool Adds a pad (link point) to ``element``\. ``pad``\'s parent will be set to ``element``\; see :func:`~gi.repository.Gst.Object.set_parent` for refcounting information. Pads are automatically activated when added in the PAUSED or PLAYING state. The pad and the element should be unlocked when calling this function. This function will emit the :obj:`~gi.repository.Gst.Element`\::pad-added signal on the element. :param pad: the :obj:`~gi.repository.Gst.Pad` to add to the element. .. classmethod:: add_pad_template(templ: ~gi.repository.Gst.PadTemplate) -> None :param templ: .. method:: add_property_deep_notify_watch(property_name: str | None, include_value: bool) -> int .. versionadded:: 1.10 :param property_name: name of property to watch for changes, or NULL to watch all properties :param include_value: whether to include the new property value in the message .. method:: add_property_notify_watch(property_name: str | None, include_value: bool) -> int .. versionadded:: 1.10 :param property_name: name of property to watch for changes, or NULL to watch all properties :param include_value: whether to include the new property value in the message .. classmethod:: add_static_metadata(key: str, value: str) -> None :param key: :param value: .. classmethod:: add_static_pad_template(static_templ: ~gi.repository.Gst.StaticPadTemplate) -> None :param static_templ: .. classmethod:: add_static_pad_template_with_gtype(static_templ: ~gi.repository.Gst.StaticPadTemplate, pad_type: ~gobject.GType) -> None :param static_templ: :param pad_type: .. method:: call_async(func: ~typing.Callable[[~gi.repository.Gst.Element, ~typing.Any], None], user_data: ~typing.Any = None) -> None Calls ``func`` from another thread and passes ``user_data`` to it. This is to be used for cases when a state change has to be performed from a streaming thread, directly via :func:`~gi.repository.Gst.Element.set_state` or indirectly e.g. via SEEK events. Calling those functions directly from the streaming thread will cause deadlocks in many situations, as they might involve waiting for the streaming thread to shut down from this very streaming thread. MT safe. .. versionadded:: 1.10 :param func: Function to call asynchronously from another thread :param user_data: Data to pass to ``func`` .. method:: change_state(transition: ~gi.repository.Gst.StateChange) -> ~gi.repository.Gst.StateChangeReturn Perform ``transition`` on ``element``\. This function must be called with STATE_LOCK held and is mainly used internally. :param transition: the requested transition .. method:: continue_state(ret: ~gi.repository.Gst.StateChangeReturn) -> ~gi.repository.Gst.StateChangeReturn Commit the state change of the element and proceed to the next pending state if any. This function is used by elements that do asynchronous state changes. The core will normally call this method automatically when an element returned :const:`~gi.repository.Gst.StateChangeReturn.SUCCESS` from the state change function. If after calling this method the element still has not reached the pending state, the next state change is performed. This method is used internally and should normally not be called by plugins or applications. This function must be called with STATE_LOCK held. :param ret: The previous state return value .. method:: create_all_pads() -> None Creates a pad for each pad template that is always available. This function is only useful during object initialization of subclasses of :obj:`~gi.repository.Gst.Element`\. .. method:: decorate_stream_id(stream_id: str) -> str Creates a stream-id for ``element`` by combining the upstream information with the ``stream_id``\. This function generates an unique stream-id by getting the upstream stream-start event stream ID and appending ``stream_id`` to it. If the element has no sinkpad it will generate an upstream stream-id by doing an URI query on the element and in the worst case just uses a random number. Source elements that don't implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead. Since stream IDs are sorted alphabetically, any numbers in the stream ID should be printed with a fixed number of characters, preceded by 0's, such as by using the format \%03u instead of \%u. .. versionadded:: 1.24 :param stream_id: The stream-id .. method:: do_change_state(self, transition: ~gi.repository.Gst.StateChange) -> ~gi.repository.Gst.StateChangeReturn :param transition: .. method:: do_get_state(self, timeout: int) -> ~typing.Tuple[~gi.repository.Gst.StateChangeReturn, ~gi.repository.Gst.State, ~gi.repository.Gst.State] :param timeout: .. method:: do_no_more_pads(self) -> None .. method:: do_pad_added(self, pad: ~gi.repository.Gst.Pad) -> None :param pad: .. method:: do_pad_removed(self, pad: ~gi.repository.Gst.Pad) -> None :param pad: .. method:: do_post_message(self, message: ~gi.repository.Gst.Message) -> bool :param message: .. method:: do_provide_clock(self) -> ~gi.repository.Gst.Clock | None .. method:: do_query(self, query: ~gi.repository.Gst.Query) -> bool :param query: .. method:: do_release_pad(self, pad: ~gi.repository.Gst.Pad) -> None :param pad: .. method:: do_request_new_pad(self, templ: ~gi.repository.Gst.PadTemplate, name: str | None = None, caps: ~gi.repository.Gst.Caps | None = None) -> ~gi.repository.Gst.Pad | None :param templ: :param name: :param caps: .. method:: do_send_event(self, event: ~gi.repository.Gst.Event) -> bool :param event: .. method:: do_set_bus(self, bus: ~gi.repository.Gst.Bus | None = None) -> None :param bus: .. method:: do_set_clock(self, clock: ~gi.repository.Gst.Clock | None = None) -> bool :param clock: .. method:: do_set_context(self, context: ~gi.repository.Gst.Context) -> None :param context: .. method:: do_set_state(self, state: ~gi.repository.Gst.State) -> ~gi.repository.Gst.StateChangeReturn :param state: .. method:: do_state_changed(self, oldstate: ~gi.repository.Gst.State, newstate: ~gi.repository.Gst.State, pending: ~gi.repository.Gst.State) -> None :param oldstate: :param newstate: :param pending: .. method:: foreach_pad(func: ~typing.Callable[[~gi.repository.Gst.Element, ~gi.repository.Gst.Pad, ~typing.Any], bool], user_data: ~typing.Any = None) -> bool Call ``func`` with ``user_data`` for each of ``element``\'s pads. ``func`` will be called exactly once for each pad that exists at the time of this call, unless one of the calls to ``func`` returns :const:`False` in which case we will stop iterating pads and return early. If new pads are added or pads are removed while pads are being iterated, this will not be taken into account until next time this function is used. .. versionadded:: 1.14 :param func: function to call for each pad :param user_data: user data passed to ``func`` .. method:: foreach_sink_pad(func: ~typing.Callable[[~gi.repository.Gst.Element, ~gi.repository.Gst.Pad, ~typing.Any], bool], user_data: ~typing.Any = None) -> bool Call ``func`` with ``user_data`` for each of ``element``\'s sink pads. ``func`` will be called exactly once for each sink pad that exists at the time of this call, unless one of the calls to ``func`` returns :const:`False` in which case we will stop iterating pads and return early. If new sink pads are added or sink pads are removed while the sink pads are being iterated, this will not be taken into account until next time this function is used. .. versionadded:: 1.14 :param func: function to call for each sink pad :param user_data: user data passed to ``func`` .. method:: foreach_src_pad(func: ~typing.Callable[[~gi.repository.Gst.Element, ~gi.repository.Gst.Pad, ~typing.Any], bool], user_data: ~typing.Any = None) -> bool Call ``func`` with ``user_data`` for each of ``element``\'s source pads. ``func`` will be called exactly once for each source pad that exists at the time of this call, unless one of the calls to ``func`` returns :const:`False` in which case we will stop iterating pads and return early. If new source pads are added or source pads are removed while the source pads are being iterated, this will not be taken into account until next time this function is used. .. versionadded:: 1.14 :param func: function to call for each source pad :param user_data: user data passed to ``func`` .. method:: get_base_time() -> int Returns the base time of the element. The base time is the absolute time of the clock when this element was last put to PLAYING. Subtracting the base time from the clock time gives the running time of the element. .. method:: get_bus() -> ~gi.repository.Gst.Bus | None Returns the bus of the element. Note that only a :obj:`~gi.repository.Gst.Pipeline` will provide a bus for the application. .. method:: get_clock() -> ~gi.repository.Gst.Clock | None Gets the currently configured clock of the element. This is the clock as was last set with :func:`~gi.repository.Gst.Element.set_clock`. Elements in a pipeline will only have their clock set when the pipeline is in the PLAYING state. .. method:: get_compatible_pad(pad: ~gi.repository.Gst.Pad, caps: ~gi.repository.Gst.Caps | None = None) -> ~gi.repository.Gst.Pad | None Looks for an unlinked pad to which the given pad can link. It is not guaranteed that linking the pads will work, though it should work in most cases. This function will first attempt to find a compatible unlinked ALWAYS pad, and if none can be found, it will request a compatible REQUEST pad by looking at the templates of ``element``\. :param pad: the :obj:`~gi.repository.Gst.Pad` to find a compatible one for. :param caps: the :obj:`~gi.repository.Gst.Caps` to use as a filter. .. method:: get_compatible_pad_template(compattempl: ~gi.repository.Gst.PadTemplate) -> ~gi.repository.Gst.PadTemplate | None Retrieves a pad template from ``element`` that is compatible with ``compattempl``\. Pads from compatible templates can be linked together. :param compattempl: the :obj:`~gi.repository.Gst.PadTemplate` to find a compatible template for .. method:: get_context(context_type: str) -> ~gi.repository.Gst.Context | None Gets the context with ``context_type`` set on the element or NULL. MT safe. .. versionadded:: 1.8 :param context_type: a name of a context to retrieve .. method:: get_context_unlocked(context_type: str) -> ~gi.repository.Gst.Context | None Gets the context with ``context_type`` set on the element or NULL. .. versionadded:: 1.8 :param context_type: a name of a context to retrieve .. method:: get_contexts() -> list[~gi.repository.Gst.Context] Gets the contexts set on the element. MT safe. .. versionadded:: 1.8 .. method:: get_current_clock_time() -> int 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. .. versionadded:: 1.18 .. method:: get_current_running_time() -> int Returns the running time of the element. The running time is the element's clock time minus its base time. Will return GST_CLOCK_TIME_NONE if the element has no clock, or if its base time has not been set. .. versionadded:: 1.18 .. method:: get_factory() -> ~gi.repository.Gst.ElementFactory | None Retrieves the factory that was used to create this element. .. method:: get_metadata(key: str) -> str Get metadata with ``key`` in ``klass``\. .. versionadded:: 1.14 :param key: the key to get .. method:: get_pad_template(name: str) -> ~gi.repository.Gst.PadTemplate | None Retrieves a padtemplate from ``element`` with the given name. .. versionadded:: 1.14 :param name: the name of the :obj:`~gi.repository.Gst.PadTemplate` to get. .. method:: get_pad_template_list() -> list[~gi.repository.Gst.PadTemplate] Retrieves a list of the pad templates associated with ``element``\. The list must not be modified by the calling code. .. versionadded:: 1.14 .. method:: get_request_pad(name: str) -> ~gi.repository.Gst.Pad | None The name of this function is confusing to people learning GStreamer. :func:`~gi.repository.Gst.Element.request_pad_simple` aims at making it more explicit it is a simplified :func:`~gi.repository.Gst.Element.request_pad`. .. deprecated:: 1.20 Prefer using :func:`~gi.repository.Gst.Element.request_pad_simple` which provides the exact same functionality. :param name: the name of the request :obj:`~gi.repository.Gst.Pad` to retrieve. .. method:: get_start_time() -> int Returns the start time of the element. The start time is the running time of the clock when this element was last put to PAUSED. Usually the start_time is managed by a toplevel element such as :obj:`~gi.repository.Gst.Pipeline`\. MT safe. .. method:: get_state(timeout: int) -> ~typing.Tuple[~gi.repository.Gst.StateChangeReturn, ~gi.repository.Gst.State, ~gi.repository.Gst.State] Gets the state of the element. For elements that performed an ASYNC state change, as reported by :func:`~gi.repository.Gst.Element.set_state`, this function will block up to the specified timeout value for the state change to complete. If the element completes the state change or goes into an error, this function returns immediately with a return value of :const:`~gi.repository.Gst.StateChangeReturn.SUCCESS` or :const:`~gi.repository.Gst.StateChangeReturn.FAILURE` respectively. For elements that did not return :const:`~gi.repository.Gst.StateChangeReturn.ASYNC`, this function returns the current and pending state immediately. This function returns :const:`~gi.repository.Gst.StateChangeReturn.NO_PREROLL` if the element successfully changed its state but is not able to provide data yet. This mostly happens for live sources that only produce data in :const:`~gi.repository.Gst.State.PLAYING`. While the state change return is equivalent to :const:`~gi.repository.Gst.StateChangeReturn.SUCCESS`, it is returned to the application to signal that some sink elements might not be able to complete their state change because an element is not producing data to complete the preroll. When setting the element to playing, the preroll will complete and playback will start. :param timeout: a :obj:`~gi.repository.Gst.ClockTime` to specify the timeout for an async state change or :const:`~gi.repository.Gst.CLOCK_TIME_NONE` for infinite timeout. .. method:: get_static_pad(name: str) -> ~gi.repository.Gst.Pad | None Retrieves a pad from ``element`` by name. This version only retrieves already-existing (i.e. 'static') pads. :param name: the name of the static :obj:`~gi.repository.Gst.Pad` to retrieve. .. method:: is_locked_state() -> bool Checks if the state of an element is locked. If the state of an element is locked, state changes of the parent don't affect the element. This way you can leave currently unused elements inside bins. Just lock their state before changing the state from ``GST_STATE_NULL``. MT safe. .. method:: iterate_pads() -> ~gi.repository.Gst.Iterator Retrieves an iterator of ``element``\'s pads. The iterator should be freed after usage. Also more specialized iterators exists such as :func:`~gi.repository.Gst.Element.iterate_src_pads` or :func:`~gi.repository.Gst.Element.iterate_sink_pads`. The order of pads returned by the iterator will be the order in which the pads were added to the element. .. method:: iterate_sink_pads() -> ~gi.repository.Gst.Iterator Retrieves an iterator of ``element``\'s sink pads. The order of pads returned by the iterator will be the order in which the pads were added to the element. .. method:: iterate_src_pads() -> ~gi.repository.Gst.Iterator Retrieves an iterator of ``element``\'s source pads. The order of pads returned by the iterator will be the order in which the pads were added to the element. .. method:: link(dest: ~gi.repository.Gst.Element) -> bool Links ``src`` to ``dest``\. The link must be from source to destination; the other direction will not be tried. The function looks for existing pads that aren't linked yet. It will request new pads if necessary. Such pads need to be released manually when unlinking. If multiple links are possible, only one is established. Make sure you have added your elements to a bin or pipeline with :func:`~gi.repository.Gst.Bin.add` before trying to link them. :param dest: the :obj:`~gi.repository.Gst.Element` containing the destination pad. .. method:: link_filtered(dest: ~gi.repository.Gst.Element, filter: ~gi.repository.Gst.Caps | None = None) -> bool Links ``src`` to ``dest`` using the given caps as filtercaps. The link must be from source to destination; the other direction will not be tried. The function looks for existing pads that aren't linked yet. It will request new pads if necessary. If multiple links are possible, only one is established. Make sure you have added your elements to a bin or pipeline with :func:`~gi.repository.Gst.Bin.add` before trying to link them. :param dest: the :obj:`~gi.repository.Gst.Element` containing the destination pad. :param filter: the :obj:`~gi.repository.Gst.Caps` to filter the link, or :const:`None` for no filter. .. method:: link_pads(srcpadname: str | None, dest: ~gi.repository.Gst.Element, destpadname: str | None = None) -> bool Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. :param srcpadname: the name of the :obj:`~gi.repository.Gst.Pad` in source element or :const:`None` for any pad. :param dest: the :obj:`~gi.repository.Gst.Element` containing the destination pad. :param destpadname: the name of the :obj:`~gi.repository.Gst.Pad` in destination element, or :const:`None` for any pad. .. method:: link_pads_filtered(srcpadname: str | None, dest: ~gi.repository.Gst.Element, destpadname: str | None = None, filter: ~gi.repository.Gst.Caps | None = None) -> bool Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. If ``caps`` is not :const:`None`, makes sure that the caps of the link is a subset of ``caps``\. :param srcpadname: the name of the :obj:`~gi.repository.Gst.Pad` in source element or :const:`None` for any pad. :param dest: the :obj:`~gi.repository.Gst.Element` containing the destination pad. :param destpadname: the name of the :obj:`~gi.repository.Gst.Pad` in destination element or :const:`None` for any pad. :param filter: the :obj:`~gi.repository.Gst.Caps` to filter the link, or :const:`None` for no filter. .. method:: link_pads_full(srcpadname: str | None, dest: ~gi.repository.Gst.Element, destpadname: str | None, flags: ~gi.repository.Gst.PadLinkCheck) -> bool Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. Calling :func:`~gi.repository.Gst.Element.link_pads_full` with ``flags`` == :const:`~gi.repository.Gst.PadLinkCheck.DEFAULT` is the same as calling :func:`~gi.repository.Gst.Element.link_pads` and the recommended way of linking pads with safety checks applied. This is a convenience function for :func:`~gi.repository.Gst.Pad.link_full`. :param srcpadname: the name of the :obj:`~gi.repository.Gst.Pad` in source element or :const:`None` for any pad. :param dest: the :obj:`~gi.repository.Gst.Element` containing the destination pad. :param destpadname: the name of the :obj:`~gi.repository.Gst.Pad` in destination element, or :const:`None` for any pad. :param flags: the :obj:`~gi.repository.Gst.PadLinkCheck` to be performed when linking pads. .. method:: lost_state() -> None Brings the element to the lost state. The current state of the element is copied to the pending state so that any call to :func:`~gi.repository.Gst.Element.get_state` will return :const:`~gi.repository.Gst.StateChangeReturn.ASYNC`. An ASYNC_START message is posted. If the element was PLAYING, it will go to PAUSED. The element will be restored to its PLAYING state by the parent pipeline when it prerolls again. This is mostly used for elements that lost their preroll buffer in the :const:`~gi.repository.Gst.State.PAUSED` or :const:`~gi.repository.Gst.State.PLAYING` state after a flush, they will go to their pending state again when a new preroll buffer is queued. This function can only be called when the element is currently not in error or an async state change. This function is used internally and should normally not be called from plugins or applications. .. classmethod:: make_from_uri(uri: str, elementname: str | None = None) -> ~gi.repository.Gst.Element Creates an element for handling the given URI. :param uri: URI to create an element for :param elementname: Name of created element, can be :const:`None`. .. method:: message_full(type: ~gi.repository.Gst.MessageType, domain: int, code: int, text: str | None, debug: str | None, file: str, function: str, line: int) -> None Post an error, warning or info message on the bus from inside an element. ``type`` must be of ``GST_MESSAGE_ERROR``, ``GST_MESSAGE_WARNING`` or ``GST_MESSAGE_INFO``. MT safe. :param type: the :obj:`~gi.repository.Gst.MessageType` :param domain: the GStreamer GError domain this message belongs to :param code: the GError code belonging to the domain :param text: an allocated text string to be used as a replacement for the default message connected to code, or :const:`None` :param debug: an allocated debug message to be used as a replacement for the default debugging information, or :const:`None` :param file: the source code file where the error was generated :param function: the source code function where the error was generated :param line: the source code line where the error was generated .. method:: message_full_with_details(type: ~gi.repository.Gst.MessageType, domain: int, code: int, text: str | None, debug: str | None, file: str, function: str, line: int, structure: ~gi.repository.Gst.Structure) -> None Post an error, warning or info message on the bus from inside an element. ``type`` must be of ``GST_MESSAGE_ERROR``, ``GST_MESSAGE_WARNING`` or ``GST_MESSAGE_INFO``. .. versionadded:: 1.10 :param type: the :obj:`~gi.repository.Gst.MessageType` :param domain: the GStreamer GError domain this message belongs to :param code: the GError code belonging to the domain :param text: an allocated text string to be used as a replacement for the default message connected to code, or :const:`None` :param debug: an allocated debug message to be used as a replacement for the default debugging information, or :const:`None` :param file: the source code file where the error was generated :param function: the source code function where the error was generated :param line: the source code line where the error was generated :param structure: optional details structure .. method:: no_more_pads() -> None Use this function to signal that the element does not expect any more pads to show up in the current pipeline. This function should be called whenever pads have been added by the element itself. Elements with ``GST_PAD_SOMETIMES`` pad templates use this in combination with autopluggers to figure out that the element is done initializing its pads. This function emits the :obj:`~gi.repository.Gst.Element`\::no-more-pads signal. MT safe. .. method:: post_message(message: ~gi.repository.Gst.Message) -> bool Post a message on the element's :obj:`~gi.repository.Gst.Bus`\. This function takes ownership of the message; if you want to access the message after this call, you should add an additional reference before calling. :param message: a :obj:`~gi.repository.Gst.Message` to post .. method:: provide_clock() -> ~gi.repository.Gst.Clock | None Get the clock provided by the given element. An element is only required to provide a clock in the PAUSED state. Some elements can provide a clock in other states. .. method:: query(query: ~gi.repository.Gst.Query) -> bool Performs a query on the given element. For elements that don't implement a query handler, this function forwards the query to a random srcpad or to the peer of a random linked sinkpad of this element. Please note that some queries might need a running pipeline to work. :param query: the :obj:`~gi.repository.Gst.Query`\. .. method:: query_convert(src_format: ~gi.repository.Gst.Format, src_val: int, dest_format: ~gi.repository.Gst.Format) -> ~typing.Tuple[bool, int] Queries an element to convert ``src_val`` in ``src_format`` to ``dest_format``\. :param src_format: a :obj:`~gi.repository.Gst.Format` to convert from. :param src_val: a value to convert. :param dest_format: the :obj:`~gi.repository.Gst.Format` to convert to. .. method:: query_duration(format: ~gi.repository.Gst.Format) -> ~typing.Tuple[bool, int] Queries an element (usually top-level pipeline or playbin element) for the total stream duration in nanoseconds. This query will only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application will receive an ASYNC_DONE message on the pipeline bus when that is the case. If the duration changes for some reason, you will get a DURATION_CHANGED message on the pipeline bus, in which case you should re-query the duration using this function. :param format: the :obj:`~gi.repository.Gst.Format` requested .. method:: query_position(format: ~gi.repository.Gst.Format) -> ~typing.Tuple[bool, int] Queries an element (usually top-level pipeline or playbin element) for the stream position in nanoseconds. This will be a value between 0 and the stream duration (if the stream duration is known). This query will usually only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application will receive an ASYNC_DONE message on the pipeline bus when that is the case. If one repeatedly calls this function one can also create a query and reuse it in :func:`~gi.repository.Gst.Element.query`. :param format: the :obj:`~gi.repository.Gst.Format` requested .. classmethod:: register(name: str, rank: int, type: ~gobject.GType) -> bool Create a new elementfactory capable of instantiating objects of the ``type`` and add the factory to ``plugin``\. :param name: name of elements of this type :param rank: rank of element (higher rank means more importance when autoplugging) :param type: GType of element to register .. method:: release_request_pad(pad: ~gi.repository.Gst.Pad) -> None Makes the element free the previously requested pad as obtained with :func:`~gi.repository.Gst.Element.request_pad`. This does not unref the pad. If the pad was created by using :func:`~gi.repository.Gst.Element.request_pad`, :func:`~gi.repository.Gst.Element.release_request_pad` needs to be followed by :func:`~gi.repository.Gst.Object.unref` to free the ``pad``\. MT safe. :param pad: the :obj:`~gi.repository.Gst.Pad` to release. .. method:: remove_pad(pad: ~gi.repository.Gst.Pad) -> bool Removes ``pad`` from ``element``\. ``pad`` will be destroyed if it has not been referenced elsewhere using :func:`~gi.repository.Gst.Object.unparent`. This function is used by plugin developers and should not be used by applications. Pads that were dynamically requested from elements with :func:`~gi.repository.Gst.Element.request_pad` should be released with the :func:`~gi.repository.Gst.Element.release_request_pad` function instead. Pads are not automatically deactivated so elements should perform the needed steps to deactivate the pad in case this pad is removed in the PAUSED or PLAYING state. See :func:`~gi.repository.Gst.Pad.set_active` for more information about deactivating pads. The pad and the element should be unlocked when calling this function. This function will emit the :obj:`~gi.repository.Gst.Element`\::pad-removed signal on the element. :param pad: the :obj:`~gi.repository.Gst.Pad` to remove from the element. .. method:: remove_property_notify_watch(watch_id: int) -> None .. versionadded:: 1.10 :param watch_id: watch id to remove .. method:: request_pad(templ: ~gi.repository.Gst.PadTemplate, name: str | None = None, caps: ~gi.repository.Gst.Caps | None = None) -> ~gi.repository.Gst.Pad | None Retrieves a request pad from the element according to the provided template. Pad templates can be looked up using :func:`~gi.repository.Gst.ElementFactory.get_static_pad_templates`. The pad should be released with :func:`~gi.repository.Gst.Element.release_request_pad`. :param templ: a :obj:`~gi.repository.Gst.PadTemplate` of which we want a pad of. :param name: the name of the request :obj:`~gi.repository.Gst.Pad` to retrieve. Can be :const:`None`. :param caps: the caps of the pad we want to request. Can be :const:`None`. .. method:: request_pad_simple(name: str) -> ~gi.repository.Gst.Pad | None Retrieves a pad from the element by name (e.g. "src_\%d"). This version only retrieves request pads. The pad should be released with :func:`~gi.repository.Gst.Element.release_request_pad`. This method is slower than manually getting the pad template and calling :func:`~gi.repository.Gst.Element.request_pad` if the pads should have a specific name (e.g. ``name`` is "src_1" instead of "src_\%u"). Note that this function was introduced in GStreamer 1.20 in order to provide a better name to :func:`~gi.repository.Gst.Element.get_request_pad`. Prior to 1.20, users should use :func:`~gi.repository.Gst.Element.get_request_pad` which provides the same functionality. .. versionadded:: 1.20 :param name: the name of the request :obj:`~gi.repository.Gst.Pad` to retrieve. .. method:: seek(rate: float, format: ~gi.repository.Gst.Format, flags: ~gi.repository.Gst.SeekFlags, start_type: ~gi.repository.Gst.SeekType, start: int, stop_type: ~gi.repository.Gst.SeekType, stop: int) -> bool Sends a seek event to an element. See :func:`~gi.repository.Gst.Event.new_seek` for the details of the parameters. The seek event is sent to the element using :func:`~gi.repository.Gst.Element.send_event`. MT safe. :param rate: The new playback rate :param format: The format of the seek values :param flags: The optional seek flags. :param start_type: The type and flags for the new start position :param start: The value of the new start position :param stop_type: The type and flags for the new stop position :param stop: The value of the new stop position .. method:: seek_simple(format: ~gi.repository.Gst.Format, seek_flags: ~gi.repository.Gst.SeekFlags, seek_pos: int) -> bool 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. For more complex operations like segment seeks (e.g. for looping) or changing the playback rate or seeking relative to the last configured playback segment you should use :func:`~gi.repository.Gst.Element.seek`. In a completely prerolled PAUSED or PLAYING pipeline, seeking is always guaranteed to return :const:`True` on a seekable media type or :const:`False` when the media type is certainly not seekable (such as a live stream). Some elements allow for seeking in the READY state, in this case they will store the seek event and execute it when they are put to PAUSED. If the element supports seek in READY, it will always return :const:`True` when it receives the event in the READY state. :param format: a :obj:`~gi.repository.Gst.Format` to execute the seek in, such as ``GST_FORMAT_TIME`` :param seek_flags: seek options; playback applications will usually want to use GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here :param seek_pos: position to seek to (relative to the start); if you are doing a seek in ``GST_FORMAT_TIME`` this value is in nanoseconds - multiply with ``GST_SECOND`` to convert seconds to nanoseconds or with ``GST_MSECOND`` to convert milliseconds to nanoseconds. .. method:: send_event(event: ~gi.repository.Gst.Event) -> bool Sends an event to an element. If the element doesn't implement an event handler, the event will be pushed on a random linked sink pad for downstream events or a random linked source pad for upstream events. This function takes ownership of the provided event so you should gst_event_ref() it if you want to reuse the event after this call. MT safe. :param event: the :obj:`~gi.repository.Gst.Event` to send to the element. .. method:: set_base_time(time: int) -> None Set the base time of an element. See :func:`~gi.repository.Gst.Element.get_base_time`. MT safe. :param time: the base time to set. .. method:: set_bus(bus: ~gi.repository.Gst.Bus | None = None) -> None Sets the bus of the element. Increases the refcount on the bus. For internal use only, unless you're testing elements. MT safe. :param bus: the :obj:`~gi.repository.Gst.Bus` to set. .. method:: set_clock(clock: ~gi.repository.Gst.Clock | None = None) -> bool Sets the clock for the element. This function increases the refcount on the clock. Any previously set clock on the object is unreffed. :param clock: the :obj:`~gi.repository.Gst.Clock` to set for the element. .. method:: set_context(context: ~gi.repository.Gst.Context) -> None Sets the context of the element. Increases the refcount of the context. MT safe. :param context: the :obj:`~gi.repository.Gst.Context` to set. .. method:: set_locked_state(locked_state: bool) -> bool Locks the state of an element, so state changes of the parent don't affect this element anymore. Note that this is racy if the state lock of the parent bin is not taken. The parent bin might've just checked the flag in another thread and as the next step proceed to change the child element's state. MT safe. :param locked_state: :const:`True` to lock the element's state .. classmethod:: set_metadata(longname: str, classification: str, description: str, author: str) -> None :param longname: :param classification: :param description: :param author: .. method:: set_start_time(time: int) -> None Set the start time of an element. The start time of the element is the running time of the element when it last went to the PAUSED state. In READY or after a flushing seek, it is set to 0. Toplevel elements like :obj:`~gi.repository.Gst.Pipeline` will manage the start_time and base_time on its children. Setting the start_time to ``GST_CLOCK_TIME_NONE`` on such a toplevel element will disable the distribution of the base_time to the children and can be useful if the application manages the base_time itself, for example if you want to synchronize capture from multiple pipelines, and you can also ensure that the pipelines have the same clock. MT safe. :param time: the base time to set. .. method:: set_state(state: ~gi.repository.Gst.State) -> ~gi.repository.Gst.StateChangeReturn Sets the state of the element. This function will try to set the requested state by going through all the intermediary states and calling the class's state change function for each. This function can return ``GST_STATE_CHANGE_ASYNC``, in which case the element will perform the remainder of the state change asynchronously in another thread. An application can use :func:`~gi.repository.Gst.Element.get_state` to wait for the completion of the state change or it can wait for a :const:`~gi.repository.Gst.MessageType.ASYNC_DONE` or :const:`~gi.repository.Gst.MessageType.STATE_CHANGED` on the bus. State changes to :const:`~gi.repository.Gst.State.READY` or :const:`~gi.repository.Gst.State.NULL` never return ``GST_STATE_CHANGE_ASYNC``. :param state: the element's new :obj:`~gi.repository.Gst.State`\. .. classmethod:: set_static_metadata(longname: str, classification: str, description: str, author: str) -> None :param longname: :param classification: :param description: :param author: .. classmethod:: state_change_return_get_name() -> str Gets a string representing the given state change result. .. classmethod:: state_get_name() -> str Gets a string representing the given state. .. method:: sync_state_with_parent() -> bool Tries to change the state of the element to the same as its parent. If this function returns :const:`False`, the state of element is undefined. .. classmethod:: type_set_skip_documentation() -> None Marks ``type`` as "documentation should be skipped". Can be useful for dynamically registered element to be excluded from plugin documentation system. Example: .. code-block:: c :dedent: GType my_type; GTypeInfo my_type_info; // Fill "my_type_info" ... my_type = g_type_register_static (GST_TYPE_MY_ELEMENT, "my-type-name", &my_type_info, 0); gst_element_type_set_skip_documentation (my_type); gst_element_register (plugin, "my-plugin-feature-name", rank, my_type); .. versionadded:: 1.20 .. method:: unlink(dest: ~gi.repository.Gst.Element) -> None Unlinks all source pads of the source element with all sink pads of the sink element to which they are linked. If the link has been made using :func:`~gi.repository.Gst.Element.link`, it could have created an requestpad, which has to be released using :func:`~gi.repository.Gst.Element.release_request_pad`. :param dest: the sink :obj:`~gi.repository.Gst.Element` to unlink. .. method:: unlink_pads(srcpadname: str, dest: ~gi.repository.Gst.Element, destpadname: str) -> None Unlinks the two named pads of the source and destination elements. This is a convenience function for :func:`~gi.repository.Gst.Pad.unlink`. :param srcpadname: the name of the :obj:`~gi.repository.Gst.Pad` in source element. :param dest: a :obj:`~gi.repository.Gst.Element` containing the destination pad. :param destpadname: the name of the :obj:`~gi.repository.Gst.Pad` in destination element. Signals ------- .. rst-class:: interim-class .. class:: Element.signals :no-index: .. method:: no_more_pads() -> None The type of the None singleton. .. method:: pad_added(new_pad: ~gi.repository.Gst.Pad) -> None The type of the None singleton. :param new_pad: the pad that has been added .. method:: pad_removed(old_pad: ~gi.repository.Gst.Pad) -> None The type of the None singleton. :param old_pad: the pad that has been removed Virtual Methods --------------- .. rst-class:: interim-class .. class:: Element :no-index: .. method:: do_change_state(transition: ~gi.repository.Gst.StateChange) -> ~gi.repository.Gst.StateChangeReturn Perform ``transition`` on ``element``\. This function must be called with STATE_LOCK held and is mainly used internally. :param transition: the requested transition .. method:: do_get_state(timeout: int) -> ~typing.Tuple[~gi.repository.Gst.StateChangeReturn, ~gi.repository.Gst.State, ~gi.repository.Gst.State] Gets the state of the element. For elements that performed an ASYNC state change, as reported by :func:`~gi.repository.Gst.Element.set_state`, this function will block up to the specified timeout value for the state change to complete. If the element completes the state change or goes into an error, this function returns immediately with a return value of :const:`~gi.repository.Gst.StateChangeReturn.SUCCESS` or :const:`~gi.repository.Gst.StateChangeReturn.FAILURE` respectively. For elements that did not return :const:`~gi.repository.Gst.StateChangeReturn.ASYNC`, this function returns the current and pending state immediately. This function returns :const:`~gi.repository.Gst.StateChangeReturn.NO_PREROLL` if the element successfully changed its state but is not able to provide data yet. This mostly happens for live sources that only produce data in :const:`~gi.repository.Gst.State.PLAYING`. While the state change return is equivalent to :const:`~gi.repository.Gst.StateChangeReturn.SUCCESS`, it is returned to the application to signal that some sink elements might not be able to complete their state change because an element is not producing data to complete the preroll. When setting the element to playing, the preroll will complete and playback will start. :param timeout: a :obj:`~gi.repository.Gst.ClockTime` to specify the timeout for an async state change or :const:`~gi.repository.Gst.CLOCK_TIME_NONE` for infinite timeout. .. method:: do_no_more_pads() -> None Use this function to signal that the element does not expect any more pads to show up in the current pipeline. This function should be called whenever pads have been added by the element itself. Elements with ``GST_PAD_SOMETIMES`` pad templates use this in combination with autopluggers to figure out that the element is done initializing its pads. This function emits the :obj:`~gi.repository.Gst.Element`\::no-more-pads signal. MT safe. .. method:: do_pad_added(pad: ~gi.repository.Gst.Pad) -> None The type of the None singleton. :param pad: .. method:: do_pad_removed(pad: ~gi.repository.Gst.Pad) -> None The type of the None singleton. :param pad: .. method:: do_post_message(message: ~gi.repository.Gst.Message) -> bool Post a message on the element's :obj:`~gi.repository.Gst.Bus`\. This function takes ownership of the message; if you want to access the message after this call, you should add an additional reference before calling. :param message: a :obj:`~gi.repository.Gst.Message` to post .. method:: do_provide_clock() -> ~gi.repository.Gst.Clock | None Get the clock provided by the given element. An element is only required to provide a clock in the PAUSED state. Some elements can provide a clock in other states. .. method:: do_query(query: ~gi.repository.Gst.Query) -> bool Performs a query on the given element. For elements that don't implement a query handler, this function forwards the query to a random srcpad or to the peer of a random linked sinkpad of this element. Please note that some queries might need a running pipeline to work. :param query: the :obj:`~gi.repository.Gst.Query`\. .. method:: do_release_pad(pad: ~gi.repository.Gst.Pad) -> None The type of the None singleton. :param pad: .. method:: do_request_new_pad(templ: ~gi.repository.Gst.PadTemplate, name: str | None = None, caps: ~gi.repository.Gst.Caps | None = None) -> ~gi.repository.Gst.Pad | None The type of the None singleton. :param templ: a :obj:`~gi.repository.Gst.PadTemplate` of which we want a pad of. :param name: the name of the request :obj:`~gi.repository.Gst.Pad` to retrieve. Can be :const:`None`. :param caps: the caps of the pad we want to request. Can be :const:`None`. .. method:: do_send_event(event: ~gi.repository.Gst.Event) -> bool Sends an event to an element. If the element doesn't implement an event handler, the event will be pushed on a random linked sink pad for downstream events or a random linked source pad for upstream events. This function takes ownership of the provided event so you should gst_event_ref() it if you want to reuse the event after this call. MT safe. :param event: the :obj:`~gi.repository.Gst.Event` to send to the element. .. method:: do_set_bus(bus: ~gi.repository.Gst.Bus | None = None) -> None Sets the bus of the element. Increases the refcount on the bus. For internal use only, unless you're testing elements. MT safe. :param bus: the :obj:`~gi.repository.Gst.Bus` to set. .. method:: do_set_clock(clock: ~gi.repository.Gst.Clock | None = None) -> bool Sets the clock for the element. This function increases the refcount on the clock. Any previously set clock on the object is unreffed. :param clock: the :obj:`~gi.repository.Gst.Clock` to set for the element. .. method:: do_set_context(context: ~gi.repository.Gst.Context) -> None Sets the context of the element. Increases the refcount of the context. MT safe. :param context: the :obj:`~gi.repository.Gst.Context` to set. .. method:: do_set_state(state: ~gi.repository.Gst.State) -> ~gi.repository.Gst.StateChangeReturn Sets the state of the element. This function will try to set the requested state by going through all the intermediary states and calling the class's state change function for each. This function can return ``GST_STATE_CHANGE_ASYNC``, in which case the element will perform the remainder of the state change asynchronously in another thread. An application can use :func:`~gi.repository.Gst.Element.get_state` to wait for the completion of the state change or it can wait for a :const:`~gi.repository.Gst.MessageType.ASYNC_DONE` or :const:`~gi.repository.Gst.MessageType.STATE_CHANGED` on the bus. State changes to :const:`~gi.repository.Gst.State.READY` or :const:`~gi.repository.Gst.State.NULL` never return ``GST_STATE_CHANGE_ASYNC``. :param state: the element's new :obj:`~gi.repository.Gst.State`\. .. method:: do_state_changed(oldstate: ~gi.repository.Gst.State, newstate: ~gi.repository.Gst.State, pending: ~gi.repository.Gst.State) -> None The type of the None singleton. :param oldstate: :param newstate: :param pending: Fields ------ .. rst-class:: interim-class .. class:: Element :no-index: .. attribute:: base_time The time of the clock right before the element is set to PLAYING. Subtracting ``base_time`` from the current clock time in the PLAYING state will yield the running_time against the clock. .. attribute:: bus The bus of the element. This bus is provided to the element by the parent element or the application. A :obj:`~gi.repository.Gst.Pipeline` has a bus of its own. .. attribute:: clock The clock of the element. This clock is usually provided to the element by the toplevel :obj:`~gi.repository.Gst.Pipeline`\. .. attribute:: contexts List of contexts .. attribute:: current_state The current state of an element .. attribute:: last_return The last return value of an element state change .. attribute:: next_state The next state of an element, can be ``GST_STATE_VOID_PENDING`` if the element is in the correct state. .. attribute:: numpads Number of pads of the element, includes both source and sink pads. .. attribute:: numsinkpads Number of sink pads of the element. .. attribute:: numsrcpads Number of source pads of the element. .. attribute:: object .. attribute:: pads List of pads .. attribute:: pads_cookie Updated whenever the a pad is added or removed .. attribute:: pending_state The final state the element should go to, can be ``GST_STATE_VOID_PENDING`` if the element is in the correct state .. attribute:: sinkpads List of sink pads .. attribute:: srcpads List of source pads .. attribute:: start_time The running_time of the last PAUSED state .. attribute:: state_cond Used to signal completion of a state change .. attribute:: state_cookie Used to detect concurrent execution of :func:`~gi.repository.Gst.Element.set_state` and :func:`~gi.repository.Gst.Element.get_state` .. attribute:: state_lock Used to serialize execution of :func:`~gi.repository.Gst.Element.set_state` .. attribute:: target_state The target state of an element as set by the application