mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer-rs.git synced 2024-11-26 19:41:09 +00:00

Sebastian Dröge 7a7984a6c6 Update documentation

2018-11-26 16:17:11 +01:00

469 KiB

Raw Blame History

Bin is an element that can contain other Element, allowing them to be managed as a group. Pads from the child elements can be ghosted to the bin, see GhostPad. This makes the bin look like any other elements and enables creation of higher-level abstraction elements.

A new Bin is created with Bin::new. Use a Pipeline instead if you want to create a toplevel bin because a normal bin doesn't have a bus or handle clock distribution of its own.

After the bin has been created you will typically add elements to it with BinExt::add. You can remove elements with BinExt::remove.

An element can be retrieved from a bin with BinExt::get_by_name, using the elements name. BinExt::get_by_name_recurse_up is mainly used for internal purposes and will query the parent bins when the element is not found in the current bin.

An iterator of elements in a bin can be retrieved with BinExt::iterate_elements. Various other iterators exist to retrieve the elements in a bin.

GstObjectExt::unref is used to drop your reference to the bin.

The Bin::element-added signal is fired whenever a new element is added to the bin. Likewise the Bin::element-removed signal is fired whenever an element is removed from the bin.

Notes

A Bin internally intercepts every Message posted by its children and implements the following default behaviour for each of them:

GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING state. If all sinks posted the EOS message, this bin will post and EOS message upwards.
GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards. The messages are used to decide when all elements have completed playback of their segment.
GST_MESSAGE_SEGMENT_DONE: Is posted by Bin when all elements that posted a SEGMENT_START have posted a SEGMENT_DONE.
GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change in the stream duration. The default bin behaviour is to clear any cached duration values so that the next duration query will perform a full duration recalculation. The duration change is posted to the application so that it can refetch the new duration with a duration query. Note that these messages can be posted before the bin is prerolled, in which case the duration query might fail.
GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it can no longer provide a clock. The default bin behaviour is to check if the lost clock was the one provided by the bin. If so and the bin is currently in the PLAYING state, the message is forwarded to the bin parent. This message is also generated when a clock provider is removed from the bin. If this message is received by the application, it should PAUSE the pipeline and set it back to PLAYING to force a new clock distribution.
GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element can provide a clock. This mostly happens when a new clock provider is added to the bin. The default behaviour of the bin is to mark the currently selected clock as dirty, which will perform a clock recalculation the next time the bin is asked to provide a clock. This message is never sent tot the application but is forwarded to the parent of the bin.
OTHERS: posted upwards.

A Bin implements the following default behaviour for answering to a Query:

GST_QUERY_DURATION:If the query has been asked before with the same format and the bin is a toplevel bin (ie. has no parent), use the cached previous value. If no previous value was cached, the query is sent to all sink elements in the bin and the MAXIMUM of all values is returned. If the bin is a toplevel bin the value is cached. If no sinks are available in the bin, the query fails.
GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the MAXIMUM of all values is returned. If no sinks are available in the bin, the query fails.
OTHERS:the query is forwarded to all sink elements, the result of the first sink that answers the query successfully is returned. If no sink is in the bin, the query fails.

A Bin will by default forward any event sent to it to all sink (EventTypeFlags::Downstream) or source (EventTypeFlags::Upstream) elements depending on the event type. If all the elements return true, the bin will also return true, else false is returned. If no elements of the required type are in the bin, the event handler will return true.

Implements

BinExt, ElementExt, GstObjectExt, glib::object::ObjectExt, ChildProxyExt

Trait containing all Bin methods.

Implementors

Bin, Pipeline

Creates a new bin with the given name.

`name`

the name of the new bin

Returns

a new Bin

Adds the given element to the bin. Sets the element's parent, and thus takes ownership of the element. An element can only be added to one bin.

If the element's pads are linked to other pads, the pads will be unlinked before the element is added to the bin.

When you add an element to an already-running pipeline, you will have to take care to set the state of the newly-added element to the desired state (usually PLAYING or PAUSED, same you set the pipeline to originally) with ElementExt::set_state, or use ElementExt::sync_state_with_parent. The bin or pipeline will not take care of this for you.

MT safe.

`element`

the Element to add

Returns

true if the element could be added, false if the bin does not want to accept the element.

Adds a None-terminated list of elements to a bin. This function is equivalent to calling BinExt::add for each member of the list. The return value of each BinExt::add is ignored.

`element_1`

the Element element to add to the bin

Recursively looks for elements with an unlinked pad of the given direction within the specified bin and returns an unlinked pad if one is found, or None otherwise. If a pad is found, the caller owns a reference to it and should use GstObjectExt::unref on the pad when it is not needed any longer.

`direction`

whether to look for an unlinked source or sink pad

Returns

unlinked pad of the given direction, None.

Looks for an element inside the bin that implements the given interface. If such an element is found, it returns the element. You can cast this element to the given interface afterwards. If you want all elements that implement the interface, use BinExt::iterate_all_by_interface. This function recurses into child bins.

MT safe. Caller owns returned reference.

`iface`

the glib::Type of an interface

Returns

A Element inside the bin implementing the interface

Gets the element with the given name from a bin. This function recurses into child bins.

Returns None if no element with the given name is found in the bin.

MT safe. Caller owns returned reference.

`name`

the element name to search for

Returns

the Element with the given name, or None

Gets the element with the given name from this bin. If the element is not found, a recursion is performed on the parent bin.

Returns None if:

no element with the given name is found in the bin

MT safe. Caller owns returned reference.

`name`

the element name to search for

Returns

the Element with the given name, or None

Return the suppressed flags of the bin.

MT safe.

Feature: v1_10

Returns

the bin's suppressed ElementFlags.

Looks for all elements inside the bin that implements the given interface. You can safely cast all returned elements to the given interface. The function recurses inside child bins. The iterator will yield a series of Element that should be unreffed after use.

a Iterator of Element, or None

Gets an iterator for the elements in this bin in topologically sorted order. This means that the elements are returned from the most downstream elements (sinks) to the sources.

This function is used internally to perform the state changes of the bin elements and for clock selection.

MT safe. Caller owns returned value.

the Element to remove

Returns

true if the element could be removed, false if the bin does not want to remove the element.

Remove a list of elements from a bin. This function is equivalent to calling BinExt::remove with each member of the list.

`element_1`

the first Element to remove from the bin

Suppress the given flags on the bin. ElementFlags of a child element are propagated when it is added to the bin. When suppressed flags are set, those specified flags will not be propagated to the bin.

MT safe.

Feature: v1_10

`flags`

the ElementFlags to suppress

Synchronizes the state of every child of self with the state of self. See also ElementExt::sync_state_with_parent.

Returns

true if syncing the state was successful for all children, otherwise false.

Will be emitted after the element was added to sub_bin.

Feature: v1_10

`sub_bin`

the Bin the element was added to

`element`

the Element that was added to sub_bin

Will be emitted after the element was removed from sub_bin.

Feature: v1_10

`sub_bin`

the Bin the element was removed from

`element`

the Element that was removed from sub_bin

Will be emitted when the bin needs to perform latency calculations. This signal is only emitted for toplevel bins or when async-handling is enabled.

Only one signal handler is invoked. If no signals are connected, the default handler is invoked, which will query and distribute the lowest possible latency to all sinks.

Connect to this signal if the default latency calculations are not sufficient, like when you need different latencies for different sinks in the same pipeline.

Will be emitted after the element was added to the bin.

`element`

the Element that was added to the bin

Will be emitted after the element was removed from the bin.

`element`

the Element that was removed from the bin

If set to true, the bin will handle asynchronous state changes. This should be used only if the bin subclass is modifying the state of its children on its own.

Forward all children messages, even those that would normally be filtered by the bin. This can be interesting when one wants to be notified of the EOS state of individual elements, for example.

The messages are converted to an ELEMENT message with the bin as the source. The structure of the message is named 'GstBinForwarded' and contains a field named 'message' of type GST_TYPE_MESSAGE that contains the original forwarded message.

Forward all children messages, even those that would normally be filtered by the bin. This can be interesting when one wants to be notified of the EOS state of individual elements, for example.

Buffers are the basic unit of data transfer in GStreamer. They contain the timing and offset along with other arbitrary metadata that is associated with the Memory blocks that the buffer contains.

Buffers are usually created with Buffer::new. After a buffer has been created one will typically allocate memory for it and add it to the buffer. The following example creates a buffer that can hold a given video frame with a given width, height and bits per plane.

  GstBuffer *buffer;
  GstMemory *memory;
  gint size, width, height, bpp;
  ...
  size = width * height * bpp;
  buffer = gst_buffer_new ();
  memory = gst_allocator_alloc (NULL, size, NULL);
  gst_buffer_insert_memory (buffer, -1, memory);
  ...

Alternatively, use Buffer::new_allocate to create a buffer with preallocated data of a given size.

Buffers can contain a list of Memory objects. You can retrieve how many memory objects with Buffer::n_memory and you can get a pointer to memory with Buffer::peek_memory

A buffer will usually have timestamps, and a duration, but neither of these are guaranteed (they may be set to GST_CLOCK_TIME_NONE). Whenever a meaningful value can be given for these, they should be set. The timestamps and duration are measured in nanoseconds (they are ClockTime values).

The buffer DTS refers to the timestamp when the buffer should be decoded and is usually monotonically increasing. The buffer PTS refers to the timestamp when the buffer content should be presented to the user and is not always monotonically increasing.

A buffer can also have one or both of a start and an end offset. These are media-type specific. For video buffers, the start offset will generally be the frame number. For audio buffers, it will be the number of samples produced so far. For compressed data, it could be the byte offset in a source or destination file. Likewise, the end offset will be the offset of the end of the buffer. These can only be meaningfully interpreted if you know the media type of the buffer (the preceding CAPS event). Either or both can be set to GST_BUFFER_OFFSET_NONE.

gst_buffer_ref is used to increase the refcount of a buffer. This must be done when you want to keep a handle to the buffer after pushing it to the next element. The buffer refcount determines the writability of the buffer, a buffer is only writable when the refcount is exactly 1, i.e. when the caller has the only reference to the buffer.

To efficiently create a smaller buffer out of an existing one, you can use Buffer::copy_region. This method tries to share the memory objects between the two buffers.

If a plug-in wants to modify the buffer data or metadata in-place, it should first obtain a buffer that is safe to modify by using gst_buffer_make_writable. This function is optimized so that a copy will only be made when it is necessary.

Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET() and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test if a certain BufferFlags flag is set.

Buffers can be efficiently merged into a larger buffer with Buffer::append. Copying of memory will only be done when absolutely needed.

Arbitrary extra metadata can be set on a buffer with Buffer::add_meta. Metadata can be retrieved with Buffer::get_meta. See also Meta

An element should either unref the buffer or push it out on a src pad using Pad::push (see Pad).

Buffers are usually freed by unreffing them with gst_buffer_unref. When the refcount drops to 0, any memory and metadata pointed to by the buffer is unreffed as well. Buffers allocated from a BufferPool will be returned to the pool when the refcount drops to 0.

The ParentBufferMeta is a meta which can be attached to a Buffer to hold a reference to another buffer that is only released when the child Buffer is released.

Typically, ParentBufferMeta is used when the child buffer is directly using the Memory of the parent buffer, and wants to prevent the parent buffer from being returned to a buffer pool until the Memory is available for re-use. (Since 1.6)

Creates a newly allocated buffer without any data.

MT safe.

Returns

the new Buffer.

Tries to create a newly allocated buffer with data of the given size and extra parameters from allocator. If the requested amount of memory can't be allocated, None will be returned. The allocated buffer memory is not cleared.

When allocator is None, the default memory allocator will be used.

Note that when size == 0, the buffer will not have memory associated with it.

MT safe.

`allocator`

the Allocator to use, or None to use the default allocator

`size`

the size in bytes of the new buffer's data.

`params`

optional parameters

Returns

a new Buffer, or None if the memory couldn't be allocated.

Creates a new buffer that wraps the given data. The memory will be freed with g_free and will be marked writable.

MT safe.

`data`

data to wrap

`size`

allocated size of data

Returns

a new Buffer

Allocate a new buffer that wraps the given memory. data must point to maxsize of memory, the wrapped buffer will have the region from offset and size visible.

When the buffer is destroyed, notify will be called with user_data.

The prefix/padding must be filled with 0 if flags contains MemoryFlags::ZeroPrefixed and MemoryFlags::ZeroPadded respectively.

`flags`

MemoryFlags

`data`

data to wrap

`maxsize`

allocated size of data

`offset`

offset in data

`size`

size of valid data

`user_data`

user_data

`notify`

called with user_data when the memory is freed

Returns

a new Buffer

Add metadata for info to self using the parameters in params.

a pointer to the added ProtectionMeta if successful; None if unsuccessful.

the new Buffer that contains the memory of the two source buffers.

Create a copy of the given buffer. This will make a newly allocated copy of the data the source buffer contains.

Returns

a new copy of self.

Copies the information from src into self.

If self already contains memory and flags contains GST_BUFFER_COPY_MEMORY, the memory from src will be appended to self.

flags indicate which fields will be copied.

`src`

a source Buffer

`flags`

flags indicating what metadata fields should be copied.

`offset`

offset to copy from

`size`

total size to copy. If -1, all data is copied.

Returns

true if the copying succeeded, false otherwise.

pointer to index

`length`

pointer to length

`skip`

pointer to skip

Returns

true when size bytes starting from offset could be found in self and idx, length and skip will be filled.

If length is -1, all memory starting from idx is merged.

number of metas of type api_type on self.

Find the first ReferenceTimestampMeta on self that conforms to reference. Conformance is tested by checking if the meta's reference is a subset of reference.

Buffers can contain multiple ReferenceTimestampMeta metadata items.

Feature: v1_14

`reference`

a reference Caps

Returns

the ReferenceTimestampMeta or None when there is no such metadata on self.

Get the total size of the memory blocks in self.

Returns

total size of the memory blocks in self.

Get the total size of the memory blocks in b.

When not None, offset will contain the offset of the data in the first memory block in self and maxsize will contain the sum of the size and offset and the amount of extra padding on the last memory block. offset and maxsize can be used to resize the buffer memory blocks with Buffer::resize.

`offset`

a pointer to the offset

`maxsize`

a pointer to the maxsize

Returns

total size of the memory blocks in self.

Get the total size of length memory blocks stating from idx in self.

When not None, offset will contain the offset of the data in the memory block in self at idx and maxsize will contain the sum of the size and offset and the amount of extra padding on the memory block at idx + length -1. offset and maxsize can be used to resize the buffer memory blocks with Buffer::resize_range.

`idx`

an index

`length`

a length

`offset`

a pointer to the offset

`maxsize`

a pointer to the maxsize

Returns

total size of length memory blocks starting at idx in self.

Insert the memory block mem to self at idx. This function takes ownership of mem and thus doesn't increase its refcount.

Only Buffer::get_max_memory can be added to a buffer. If more memory is added, existing memory blocks will automatically be merged to make room for the new memory.

`idx`

the index to add the memory at, or -1 to append it to the end

`mem`

a Memory.

Check if all memory blocks in self are writable.

Note that this function does not check if self is writable, use gst_buffer_is_writable to check that if needed.

Returns

true if all memory blocks in self are writable

Check if length memory blocks in self starting from idx are writable.

length can be -1 to check all the memory blocks after idx.

Note that this function does not check if self is writable, use gst_buffer_is_writable to check that if needed.

`idx`

an index

`length`

a length should not be 0

Returns

true if the memory range is writable

Retrieve the next Meta after current. If state points to None, the first metadata is returned.

state will be updated with an opaque state pointer

`state`

an opaque state pointer

The amount of bytes filled. This value can be lower than size when self did not contain enough data.

Get the amount of memory blocks that this buffer has. This amount is never larger than what Buffer::get_max_memory returns.

Returns

the number of memory blocks this buffer is made of.

Get the memory block at idx in self. The memory block stays valid until the memory block in self is removed, replaced or merged, typically with any call that modifies the memory in self.

`idx`

an index

Returns

the Memory at idx.

Prepend the memory block mem to self. This function takes ownership of mem and thus doesn't increase its refcount.

This function is identical to Buffer::insert_memory with an index of 0. See Buffer::insert_memory for more details.

`mem`

a Memory.

Remove all the memory blocks in self.

Remove the memory block in b at index i.

`idx`

an index

Remove length memory blocks in self starting from idx.

length can be -1, in which case all memory starting from idx is removed.

`idx`

an index

`length`

a length

Remove the metadata for meta on self.

`meta`

a Meta

Returns

true if the metadata existed and was removed, false if no such metadata was on self.

the new size or -1 to just adjust the offset

Set the total size of the length memory blocks starting at idx in self

`idx`

an index

`length`

a length

`offset`

the offset adjustment

`size`

the new size or -1 to just adjust the offset

Returns

true if resizing succeeded, false otherwise.

Sets one or more buffer flags on a buffer.

Feature: v1_10

`flags`

the BufferFlags to set.

Returns

true if flags were successfully set on buffer.

Set the total size of the memory blocks in self.

`size`

the new size

Release the memory previously mapped with Buffer::map.

`info`

a MapInfo

Clears one or more buffer flags.

Feature: v1_10

`flags`

the BufferFlags to clear

Returns

true if flags is successfully cleared from buffer.

Get the maximum amount of memory blocks that a buffer can hold. This is a compile time constant that can be queried with the function.

When more memory blocks are added, existing memory blocks will be merged together to make room for the new block.

Returns

the maximum amount of memory blocks that a buffer can hold.

Buffer lists are an object containing a list of buffers.

Buffer lists are created with BufferList::new and filled with data using a BufferList::insert.

Buffer lists can be pushed on a srcpad with Pad::push_list. This is interesting when multiple buffers need to be pushed in one go because it can reduce the amount of overhead for pushing each buffer individually.

Creates a new, empty BufferList. The caller is responsible for unreffing the returned BufferList.

Free-function: gst_buffer_list_unref

Returns

the new BufferList. gst_buffer_list_unref after usage.

Creates a new, empty BufferList. The caller is responsible for unreffing the returned BufferList. The list will have size space preallocated so that memory reallocations can be avoided.

Free-function: gst_buffer_list_unref

`size`

an initial reserved size

Returns

the new BufferList. gst_buffer_list_unref after usage.

Calculates the size of the data contained in buffer list by adding the size of all buffers.

Feature: v1_14

Returns

the size of the data contained in buffer list in bytes.

Create a copy of the given buffer list. This will make a newly allocated copy of the buffer that the source buffer list contains.

Returns

a new copy of self.

Call func with data for each buffer in self.

func can modify the passed buffer pointer or its contents. The return value of func define if this function returns or if the remaining buffers in the list should be skipped.

`func`

a GstBufferListFunc to call

`user_data`

user data passed to func

Returns

true when func returned true for each buffer in self or when self is empty.

Get the buffer at idx.

You must make sure that idx does not exceed the number of buffers available.

`idx`

the index

Returns

the buffer at idx in group or None when there is no buffer. The buffer remains valid as long as self is valid and buffer is not removed from the list.

Gets the buffer at idx, ensuring it is a writable buffer.

You must make sure that idx does not exceed the number of buffers available.

Feature: v1_14

`idx`

the index

Returns

the buffer at idx in group. The returned buffer remains valid as long as self is valid and the buffer is not removed from the list.

Insert buffer at idx in self. Other buffers are moved to make room for this new buffer.

A -1 value for idx will append the buffer at the end.

`idx`

the index

`buffer`

a Buffer

Returns the number of buffers in self.

Returns

the number of buffers in the buffer list

Remove length buffers starting from idx in self. The following buffers are moved to close the gap.

`idx`

the index

`length`

the amount to remove

A BufferPool is an object that can be used to pre-allocate and recycle buffers of the same size and with the same properties.

A BufferPool is created with BufferPool::new.

Once a pool is created, it needs to be configured. A call to BufferPool::get_config returns the current configuration structure from the pool. With BufferPool::config_set_params and BufferPool::config_set_allocator the bufferpool parameters and allocator can be configured. Other properties can be configured in the pool depending on the pool implementation.

A bufferpool can have extra options that can be enabled with BufferPool::config_add_option. The available options can be retrieved with BufferPoolExt::get_options. Some options allow for additional configuration properties to be set.

After the configuration structure has been configured, BufferPool::set_config updates the configuration in the pool. This can fail when the configuration structure is not accepted.

After the a pool has been configured, it can be activated with BufferPoolExt::set_active. This will preallocate the configured resources in the pool.

When the pool is active, BufferPool::acquire_buffer can be used to retrieve a buffer from the pool.

Buffers allocated from a bufferpool will automatically be returned to the pool with BufferPool::release_buffer when their refcount drops to 0.

The bufferpool can be deactivated again with BufferPoolExt::set_active. All further BufferPool::acquire_buffer calls will return an error. When all buffers are returned to the pool they will be freed.

Use GstObjectExt::unref to release the reference to a bufferpool. If the refcount of the pool reaches 0, the pool will be freed.

Implements

BufferPoolExt, GstObjectExt, glib::object::ObjectExt

Trait containing all BufferPool methods.

Implementors

BufferPool

Creates a new BufferPool instance.

Returns

`size`

`min_buffers`

the minimum amount of buffers to allocate.

`max_buffers`

the maximum amount of buffers to allocate or 0 for unlimited.

Validate that changes made to config are still valid in the context of the expected parameters. This function is a helper that can be used to validate changes made by a pool to a config when BufferPool::set_config returns false. This expects that caps haven't changed and that min_buffers aren't lower then what we initially expected. This does not check if options or allocator parameters are still valid, won't check if size have changed, since changing the size is valid to adapt padding.

`config`

a BufferPool configuration

`caps`

the excepted caps of buffers

`size`

the expected size of each buffer, not including prefix and padding

`min_buffers`

the expected minimum amount of buffers to allocate.

`max_buffers`

the expect maximum amount of buffers to allocate or 0 for unlimited.

Returns

true, if the parameters are valid in this context.

Acquire a buffer from self. buffer should point to a memory location that can hold a pointer to the new buffer.

params can be None or contain optional parameters to influence the allocation.

`buffer`

a location for a Buffer

`params`

parameters.

Returns

a FlowReturn such as FlowReturn::Flushing when the pool is inactive.

Get a copy of the current configuration of the pool. This configuration can either be modified and used for the BufferPool::set_config call or it must be freed after usage.

Returns

a copy of the current configuration of self. use Structure::free after usage or BufferPool::set_config.

Get a None terminated array of string with supported bufferpool options for self. An option would typically be enabled with BufferPool::config_add_option.

Returns

a None terminated array of strings.

Check if the bufferpool supports option.

`option`

an option

Returns

true if the buffer pool contains option.

Check if self is active. A pool can be activated with the BufferPoolExt::set_active call.

Returns

true when the pool is active.

Release buffer to self. buffer should have previously been allocated from self with BufferPool::acquire_buffer.

This function is usually called automatically when the last ref on buffer disappears.

`buffer`

a Buffer

Control the active state of self. When the pool is inactive, new calls to BufferPool::acquire_buffer will return with FlowReturn::Flushing.

Activating the bufferpool will preallocate all resources in the pool based on the configuration of the pool.

Deactivating will free the resources again when there are no outstanding buffers. When there are outstanding buffers, they will be freed as soon as they are all returned to the pool.

`active`

the new active state

Returns

false when the pool was not configured or when preallocation of the buffers failed.

Set the configuration of the pool. If the pool is already configured, and the configuration haven't change, this function will return true. If the pool is active, this method will return false and active configuration will remain. Buffers allocated form this pool must be returned or else this function will do nothing and return false.

config is a Structure that contains the configuration parameters for the pool. A default and mandatory set of parameters can be configured with BufferPool::config_set_params, BufferPool::config_set_allocator and BufferPool::config_add_option.

If the parameters in config can not be set exactly, this function returns false and will try to update as much state as possible. The new state can then be retrieved and refined with BufferPool::get_config.

This function takes ownership of config.

`config`

a Structure

Returns

true when the configuration could be set.

Enable or disable the flushing state of a self without freeing or allocating buffers.

`flushing`

whether to start or stop flushing

The different types of buffering methods.

a small amount of data is buffered

the stream is being downloaded

the stream is being downloaded in a ringbuffer

the stream is a live stream

The Bus is an object responsible for delivering Message packets in a first-in first-out way from the streaming threads (see Task) to the application.

Since the application typically only wants to deal with delivery of these messages from one thread, the GstBus will marshall the messages between different threads. This is important since the actual streaming of media is done in another thread than the application.

The GstBus provides support for glib::Source based notifications. This makes it possible to handle the delivery in the glib mainloop.

The glib::Source callback function Bus::async_signal_func can be used to convert all bus messages into signal emissions.

A message is posted on the bus with the Bus::post method. With the Bus::peek and Bus::pop methods one can look at or retrieve a previously posted message.

The bus can be polled with the Bus::poll method. This methods blocks up to the specified timeout value until one of the specified messages types is posted on the bus. The application can then Bus::pop the messages from the bus to handle them. Alternatively the application can register an asynchronous bus function using Bus::add_watch_full or Bus::add_watch. This function will install a glib::Source in the default glib main loop and will deliver messages a short while after they have been posted. Note that the main loop should be running for the asynchronous callbacks.

It is also possible to get messages from the bus without any thread marshalling with the Bus::set_sync_handler method. This makes it possible to react to a message in the same thread that posted the message on the bus. This should only be used if the application is able to deal with messages from different threads.

Every Pipeline has one bus.

Note that a Pipeline will set its bus into flushing state when changing from READY to NULL state.

Implements

GstObjectExt, glib::object::ObjectExt

Creates a new Bus instance.

Returns

a new Bus instance

Adds a bus signal watch to the default main context with the default priority (G_PRIORITY_DEFAULT). It is also possible to use a non-default main context set up using glib::MainContext::push_thread_default (before one had to create a bus watch source and attach it to the desired main context 'manually').

After calling this statement, the bus will emit the "message" signal for each message posted on the bus.

This function may be called multiple times. To clean up, the caller is responsible for calling Bus::remove_signal_watch as many times as this function is called.

MT safe.

Adds a bus signal watch to the default main context with the given priority (e.g. G_PRIORITY_DEFAULT). It is also possible to use a non-default main context set up using glib::MainContext::push_thread_default (before one had to create a bus watch source and attach it to the desired main context 'manually').

After calling this statement, the bus will emit the "message" signal for each message posted on the bus when the main loop is running.

This function may be called multiple times. To clean up, the caller is responsible for calling Bus::remove_signal_watch as many times as this function is called.

There can only be a single bus watch per bus, you must remove any signal watch before you can set another type of watch.

MT safe.

`priority`

The priority of the watch.

Adds a bus watch to the default main context with the default priority (G_PRIORITY_DEFAULT). It is also possible to use a non-default main context set up using glib::MainContext::push_thread_default (before one had to create a bus watch source and attach it to the desired main context 'manually').

This function is used to receive asynchronous messages in the main loop. There can only be a single bus watch per bus, you must remove it before you can set a new one.

The bus watch will only work if a GLib main loop is being run.

The watch can be removed using Bus::remove_watch or by returning false from func. If the watch was added to the default main context it is also possible to remove the watch using glib::Source::remove.

The bus watch will take its own reference to the self, so it is safe to unref self using GstObjectExt::unref after setting the bus watch.

MT safe.

`func`

A function to call when a message is received.

`user_data`

user data passed to func.

Returns

The event source id or 0 if self already got an event source.

Adds a bus watch to the default main context with the given priority (e.g. G_PRIORITY_DEFAULT). It is also possible to use a non-default main context set up using glib::MainContext::push_thread_default (before one had to create a bus watch source and attach it to the desired main context 'manually').

This function is used to receive asynchronous messages in the main loop. There can only be a single bus watch per bus, you must remove it before you can set a new one.

The bus watch will only work if a GLib main loop is being run.

When func is called, the message belongs to the caller; if you want to keep a copy of it, call gst_message_ref before leaving func.

The bus watch will take its own reference to the self, so it is safe to unref self using GstObjectExt::unref after setting the bus watch.

MT safe.

`priority`

The priority of the watch.

`func`

A function to call when a message is received.

`user_data`

user data passed to func.

In the event that multiple pieces of code have called Bus::enable_sync_message_emission, the sync-message emissions will only be stopped after all calls to Bus::enable_sync_message_emission were "cancelled" by calling this function. In this way the semantics are exactly the same as GstObjectExt::ref that which calls enable should also call disable.

MT safe.

Instructs GStreamer to emit the "sync-message" signal after running the bus's sync handler. This function is here so that code can ensure that they can synchronously receive messages without having to affect what the bin's sync handler is.

This function may be called multiple times. To clean up, the caller is responsible for calling Bus::disable_sync_message_emission as many times as this function is called.

While this function looks similar to Bus::add_signal_watch, it is not exactly the same -- this function enables <emphasis>synchronous</emphasis> emission of signals when messages arrive; Bus::add_signal_watch adds an idle callback to pop messages off the bus <emphasis>asynchronously</emphasis>. The sync-message signal comes from the thread of whatever object posted the message; the "message" signal is marshalled to the main thread via the main loop.

MT safe.

Gets the file descriptor from the bus which can be used to get notified about messages being available with functions like g_poll, and allows integration into other event loops based on file descriptors. Whenever a message is available, the POLLIN / glib::IOCondition::In event is set.

Warning: NEVER read or write anything to the returned fd but only use it for getting notifications via g_poll or similar and then use the normal GstBus API, e.g. Bus::pop.

Feature: v1_14

`fd`

A GPollFD to fill

Check if there are pending messages on the bus that should be handled.

Returns

true if there are messages on the bus to be handled, false otherwise.

MT safe.

Peek the message on the top of the bus' queue. The message will remain on the bus' message queue. A reference is returned, and needs to be unreffed by the caller.

Returns

the Message that is on the bus, or None if the bus is empty.

MT safe.

Poll the bus for messages. Will block while waiting for messages to come. You can specify a maximum time to poll with the timeout parameter. If timeout is negative, this function will block indefinitely.

All messages not in events will be popped off the bus and will be ignored. It is not possible to use message enums beyond MessageType::Extended in the events mask

Because poll is implemented using the "message" signal enabled by Bus::add_signal_watch, calling Bus::poll will cause the "message" signal to be emitted for every message that poll sees. Thus a "message" signal handler will see the same messages that this function sees -- neither will steal messages from the other.

This function will run a main loop from the default main context when polling.

You should never use this function, since it is pure evil. This is especially true for GUI applications based on Gtk+ or Qt, but also for any other non-trivial application that uses the GLib main loop. As this function runs a GLib main loop, any callback attached to the default GLib main context may be invoked. This could be timeouts, GUI events, I/O events etc.; even if Bus::poll is called with a 0 timeout. Any of these callbacks may do things you do not expect, e.g. destroy the main application window or some other resource; change other application state; display a dialog and run another main loop until the user clicks it away. In short, using this function may add a lot of complexity to your code through unexpected re-entrancy and unexpected changes to your application's state.

For 0 timeouts use Bus::pop_filtered instead of this function; for other short timeouts use Bus::timed_pop_filtered; everything else is better handled by setting up an asynchronous bus watch and doing things from there.

`events`

a mask of MessageType, representing the set of message types to poll for (note special handling of extended message types below)

`timeout`

the poll timeout, as a ClockTime, or GST_CLOCK_TIME_NONE to poll indefinitely.

Returns

the message that was received, or None if the poll timed out. The message is taken from the bus and needs to be unreffed with gst_message_unref after usage.

whether or not to flush the bus

Sets the synchronous handler on the bus. The function will be called every time a new message is posted on the bus. Note that the function will be called in the same thread context as the posting object. This function is usually only called by the creator of the bus. Applications should handle messages asynchronously using the gst_bus watch and poll functions.

You cannot replace an existing sync_handler. You can pass None to this function, which will clear the existing handler.

`func`

The handler function to install

`user_data`

User data that will be sent to the handler function.

`notify`

called when user_data becomes unused

A helper GstBusSyncHandler that can be used to convert all synchronous messages into signals.

`message`

the Message received

`data`

user data

Returns

GST_BUS_PASS

Get a message from the bus, waiting up to the specified timeout.

If timeout is 0, this function behaves like Bus::pop. If timeout is GST_CLOCK_TIME_NONE, this function will block forever until a message was posted on the bus.

`timeout`

a timeout

Returns

the Message that is on the bus after the specified timeout or None if the bus is empty after the timeout expired. The message is taken from the bus and needs to be unreffed with gst_message_unref after usage.

MT safe.

Get a message from the bus whose type matches the message type mask types, waiting up to the specified timeout (and discarding any messages that do not match the mask provided).

If timeout is 0, this function behaves like Bus::pop_filtered. If timeout is GST_CLOCK_TIME_NONE, this function will block forever until a matching message was posted on the bus.

`timeout`

a timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever

`types`

message types to take into account, GST_MESSAGE_ANY for any type

Returns

a Message matching the filter in types, or None if no matching message was found on the bus until the timeout expired. The message is taken from the bus and needs to be unreffed with gst_message_unref after usage.

MT safe.

A message has been posted on the bus. This signal is emitted from a GSource added to the mainloop. this signal will only be emitted when there is a mainloop running.

`message`

the message that has been posted asynchronously

A message has been posted on the bus. This signal is emitted from the thread that posted the message so one has to be careful with locking.

This signal will not be emitted by default, you have to call Bus::enable_sync_message_emission before.

`message`

the message that has been posted synchronously

The result values for a GstBusSyncHandler.

drop the message

pass the message to the async queue

pass message to async queue, continue if message is handled

Caps (capabilities) are lightweight refcounted objects describing media types. They are composed of an array of Structure.

Caps are exposed on PadTemplate to describe all possible types a given pad can handle. They are also stored in the Registry along with a description of the Element.

Caps are exposed on the element pads using the PadExt::query_caps pad function. This function describes the possible types that the pad can handle or produce at runtime.

A Caps can be constructed with the following code fragment:

  GstCaps *caps = gst_caps_new_simple ("video/x-raw",
     "format", G_TYPE_STRING, "I420",
     "framerate", GST_TYPE_FRACTION, 25, 1,
     "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1,
     "width", G_TYPE_INT, 320,
     "height", G_TYPE_INT, 240,
     NULL);

A Caps is fixed when it has no properties with ranges or lists. Use Caps::is_fixed to test for fixed caps. Fixed caps can be used in a caps event to notify downstream elements of the current media type.

Various methods exist to work with the media types such as subtracting or intersecting.

Be aware that the current Caps / Structure serialization into string has limited support for nested Caps / Structure fields. It can only support one level of nesting. Using more levels will lead to unexpected behavior when using serialization features, such as Caps::to_string or gst_value_serialize and their counterparts.

Creates a new Caps that indicates that it is compatible with any media format.

Returns

the new Caps

the first structure to add

`var_args`

additional structures to add

Returns

the new Caps

Creates a new Caps that contains one Structure. The structure is defined by the arguments, which have the same format as Structure::new. Caller is responsible for unreffing the returned caps.

`media_type`

the media type of the structure

`fieldname`

first field to set

Returns

the new Caps

Appends the structures contained in caps2 to self. The structures in caps2 are not copied -- they are transferred to self, and then caps2 is freed. If either caps is ANY, the resulting caps will be ANY.

`caps2`

the Caps to append

Appends structure to self. The structure is not copied; self becomes the owner of structure.

`structure`

the Structure to append

Appends structure with features to self. The structure is not copied; self becomes the owner of structure.

`structure`

the Structure to append

`features`

the CapsFeatures to append

Tries intersecting self and caps2 and reports whether the result would not be empty

`caps2`

a Caps to intersect

Returns

true if intersection would be not empty

Creates a new Caps and appends a copy of the nth structure contained in self.

`nth`

the nth structure to copy

Returns

the new Caps

Calls the provided function once for each structure and caps feature in the Caps. In contrast to Caps::foreach, the function may modify the structure and features. In contrast to Caps::filter_and_map_in_place, the structure and features are removed from the caps if false is returned from the function. The caps must be mutable.

`func`

a function to call for each field

`user_data`

private data

Modifies the given self into a representation with only fixed values. First the caps will be truncated and then the first structure will be fixated with Structure::fixate.

WARNING: This function takes a const GstCaps *, but returns a non-const GstStructure *. This is for programming convenience -- the caller should be aware that structures inside a constant Caps should not be modified. However, if you know the caps are writable, either because you have just copied them or made them writable with gst_caps_make_writable, you may modify the structure returned in the usual way, e.g. with functions like Structure::set.

You do not need to free or unref the structure returned, it belongs to the Caps.

`index`

the index of the structure

Returns

a pointer to the Structure corresponding to index

Creates a new Caps that contains all the formats that are common to both self and caps2. Defaults to CapsIntersectMode::ZigZag mode.

`caps2`

a Caps to intersect

Returns

the new Caps

Creates a new Caps that contains all the formats that are common to both self and caps2, the order is defined by the CapsIntersectMode used.

`caps2`

a Caps to intersect

`mode`

The intersection algorithm/mode to use

Returns

the new Caps

A given Caps structure is always compatible with another if every media format that is in the first is also contained in the second. That is, self is a subset of caps2.

`caps2`

the Caps to test

Returns

true if self is a subset of caps2.

Determines if self represents any media format.

Returns

true if self represents any format.

true if self is fixed

Checks if the given caps are exactly the same set of caps.

`caps2`

another Caps

Returns

true if both caps are strictly equal.

Checks if all caps represented by self are also represented by superset.

`superset`

a potentially greater Caps

Returns

`caps2`

the Caps to merge in

Returns

the merged caps.

Appends structure to self if its not already expressed by self.

`structure`

the Structure to merge

Returns

the merged caps.

Appends structure with features to self if its not already expressed by self.

`structure`

the Structure to merge

`features`

the CapsFeatures to merge

Returns

`value`

value to set the field to

Converts the given self into a representation that represents the same set of formats, but in a simpler form. Component structures that are identical are merged. Component structures that have values that can be merged are also merged.

This function takes ownership of self and will call gst_caps_make_writable on it if necessary, so you must not use self afterwards unless you keep an additional reference to it with gst_caps_ref.

This method does not preserve the original order of self.

Returns

The simplified caps.

Retrieves the structure with the given index from the list of structures contained in self. The caller becomes the owner of the returned structure.

`index`

Index of the structure to retrieve

Returns

a pointer to the Structure corresponding to index.

Subtracts the subtrahend from the self.

This function does not work reliably if optional properties for caps are included on one caps and omitted on the other.

`subtrahend`

Caps to subtract

Returns

the resulting caps

Converts self to a string representation. This string representation can be converted back to a Caps by Caps::from_string.

For debugging purposes its easier to do something like this:

GST_LOG ("caps are %" GST_PTR_FORMAT, caps);

This prints the caps in human readable form.

The current implementation of serialization will lead to unexpected results when there are nested Caps / Structure deeper than one level.

Returns

a newly allocated string representing self.

Discard all but the first structure from self. Useful when fixating.

Returns

truncated caps

Converts caps from a string representation.

The current implementation of serialization will lead to unexpected results when there are nested Caps / Structure deeper than one level.

`string`

a string to convert to Caps

Returns

a newly allocated Caps

Modes of caps intersection

CapsIntersectMode::ZigZag tries to preserve overall order of both caps by iterating on the caps' structures as the following matrix shows:

         caps1
      +-------------
      | 1  2  4  7
caps2 | 3  5  8 10
      | 6  9 11 12

Used when there is no explicit precedence of one caps over the other. e.g. tee's sink pad getcaps function, it will probe its src pad peers' for their caps and intersect them with this mode.

CapsIntersectMode::First is useful when an element wants to preserve another element's caps priority order when intersecting with its own caps. Example: If caps1 is [A, B, C] and caps2 is [E, B, D, A], the result would be [A, B], maintaining the first caps priority on the intersection.

Zig-zags over both caps.

Keeps the first caps order.

This interface abstracts handling of property sets for elements with children. Imagine elements such as mixers or polyphonic generators. They all have multiple Pad or some kind of voice objects. Another use case are container elements like Bin. The element implementing the interface acts as a parent for those child objects.

By implementing this interface the child properties can be accessed from the parent element by using ChildProxy::get and ChildProxy::set.

Property names are written as "child-name::property-name". The whole naming scheme is recursive. Thus "child1::child2::property" is valid too, if "child1" and "child2" implement the ChildProxy interface.

Implements

ChildProxyExt

Trait containing all ChildProxy methods.

Implementors

Bin, ChildProxy, Pipeline

Emits the "child-added" signal.

`child`

the newly added child

`name`

the name of the new child

Emits the "child-removed" signal.

`child`

the removed child

`name`

the name of the old child

Gets properties of the parent object and its children.

`first_property_name`

name of the first property to get

Fetches a child by its number.

`index`

the child's position in the child list

Returns

the child object or None if not found (index too high). Unref after usage.

MT safe.

Looks up a child element by the given name.

This virtual method has a default implementation that uses Object together with GstObjectExt::get_name. If the interface is to be used with GObjects, this methods needs to be overridden.

`name`

the child's name

Returns

the child object or None if not found. Unref after usage.

MT safe.

Gets the number of child objects this parent contains.

Returns

the number of child objects

MT safe.

Gets a single property using the GstChildProxy mechanism. You are responsible for freeing it by calling gobject::Value::unset

`name`

name of the property

`value`

a gobject::Value that should take the result.

Gets properties of the parent object and its children.

`first_property_name`

name of the first property to get

`var_args`

return location for the first property, followed optionally by more name/return location pairs, followed by None

Looks up which object and gobject::ParamSpec would be effected by the given name.

MT safe.

`name`

name of the property to look up

`target`

pointer to a gobject::Object that takes the real object to set property on

`pspec`

pointer to take the gobject::ParamSpec describing the property

Returns

true if target and pspec could be found. false otherwise. In that case the values for pspec and target are not modified. Unref target after usage. For plain GObjects target is the same as self.

Sets properties of the parent object and its children.

`first_property_name`

name of the first property to set

Sets a single property using the GstChildProxy mechanism.

`name`

name of the property to set

`value`

new gobject::Value for the property

Sets properties of the parent object and its children.

`first_property_name`

name of the first property to set

`var_args`

value for the first property, followed optionally by more name/value pairs, followed by None

Will be emitted after the object was added to the child_proxy.

`object`

the gobject::Object that was added

`name`

the name of the new child

Will be emitted after the object was removed from the child_proxy.

`object`

the gobject::Object that was removed

`name`

the name of the old child

GStreamer uses a global clock to synchronize the plugins in a pipeline. Different clock implementations are possible by implementing this abstract base class or, more conveniently, by subclassing SystemClock.

The Clock returns a monotonically increasing time with the method ClockExt::get_time. Its accuracy and base time depend on the specific clock implementation but time is always expressed in nanoseconds. Since the baseline of the clock is undefined, the clock time returned is not meaningful in itself, what matters are the deltas between two clock times. The time returned by a clock is called the absolute time.

The pipeline uses the clock to calculate the running time. Usually all renderers synchronize to the global clock using the buffer timestamps, the newsegment events and the element's base time, see Pipeline.

A clock implementation can support periodic and single shot clock notifications both synchronous and asynchronous.

One first needs to create a ClockID for the periodic or single shot notification using ClockExt::new_single_shot_id or ClockExt::new_periodic_id.

To perform a blocking wait for the specific time of the ClockID use the Clock::id_wait. To receive a callback when the specific time is reached in the clock use Clock::id_wait_async. Both these calls can be interrupted with the Clock::id_unschedule call. If the blocking wait is unscheduled a return value of ClockReturn::Unscheduled is returned.

Periodic callbacks scheduled async will be repeatedly called automatically until it is unscheduled. To schedule a sync periodic callback, Clock::id_wait should be called repeatedly.

The async callbacks can happen from any thread, either provided by the core or from a streaming thread. The application should be prepared for this.

A ClockID that has been unscheduled cannot be used again for any wait operation, a new ClockID should be created and the old unscheduled one should be destroyed with Clock::id_unref.

It is possible to perform a blocking wait on the same ClockID from multiple threads. However, registering the same ClockID for multiple async notifications is not possible, the callback will only be called for the thread registering the entry last.

None of the wait operations unref the ClockID, the owner is responsible for unreffing the ids itself. This holds for both periodic and single shot notifications. The reason being that the owner of the ClockID has to keep a handle to the ClockID to unblock the wait on FLUSHING events or state changes and if the entry would be unreffed automatically, the handle might become invalid without any notification.

These clock operations do not operate on the running time, so the callbacks will also occur when not in PLAYING state as if the clock just keeps on running. Some clocks however do not progress when the element that provided the clock is not PLAYING.

When a clock has the ClockFlags::CanSetMaster flag set, it can be slaved to another Clock with the ClockExt::set_master. The clock will then automatically be synchronized to this master clock by repeatedly sampling the master clock and the slave clock and recalibrating the slave clock with ClockExt::set_calibration. This feature is mostly useful for plugins that have an internal clock but must operate with another clock selected by the Pipeline. They can track the offset and rate difference of their internal clock relative to the master clock by using the ClockExt::get_calibration function.

The master/slave synchronisation can be tuned with the Clock:timeout, Clock:window-size and Clock:window-threshold properties. The Clock:timeout property defines the interval to sample the master clock and run the calibration functions. Clock:window-size defines the number of samples to use when calibrating and Clock:window-threshold defines the minimum number of samples before the calibration is performed.

Implements

ClockExt, GstObjectExt, glib::object::ObjectExt

Trait containing all Clock methods.

Implementors

Clock, SystemClock

The same ClockID with increased refcount.

MT safe.

Unref given id. When the refcount reaches 0 the ClockID will be freed.

MT safe.

`id`

The ClockID to unref

Cancel an outstanding request with id. This can either be an outstanding async notification or a pending sync notification. After this call, id cannot be used anymore to receive sync or async notifications, you need to create a new ClockID.

MT safe.

`id`

The id to unschedule

Perform a blocking wait on id. id should have been created with ClockExt::new_single_shot_id or ClockExt::new_periodic_id and should not have been unscheduled with a call to Clock::id_unschedule.

If the jitter argument is not None and this function returns ClockReturn::Ok or ClockReturn::Early, it will contain the difference against the clock and the time of id when this method was called. Positive values indicate how late id was relative to the clock (in which case this function will return ClockReturn::Early). Negative values indicate how much time was spent waiting on the clock before this function returned.

`id`

The ClockID to wait on

`jitter`

a pointer that will contain the jitter, can be None.

Returns

a location to store the rate numerator

`rate_denom`

a location to store the rate denominator

Converts the given internal clock time to the external time, adjusting for the rate and reference time set with ClockExt::set_calibration and making sure that the returned time is increasing. This function should be called with the clock's OBJECT_LOCK held and is mainly used by clock subclasses.

This function is the reverse of ClockExt::unadjust_unlocked.

`internal`

a clock time

Returns

the converted time of the clock.

Converts the given internal_target clock time to the external time, using the passed calibration parameters. This function performs the same calculation as ClockExt::adjust_unlocked when called using the current calibration parameters, but doesn't ensure a monotonically increasing result as ClockExt::adjust_unlocked does.

Note: The self parameter is unused and can be NULL

`internal_target`

a clock time

`cinternal`

a reference internal time

`cexternal`

a reference external time

`cnum`

the numerator of the rate of the clock relative to its internal time

`cdenom`

the denominator of the rate of the clock

Returns

the converted time of the clock.

Gets the internal rate and reference time of self. See ClockExt::set_calibration for more information.

internal, external, rate_num, and rate_denom can be left None if the caller is not interested in the values.

MT safe.

`internal`

a location to store the internal time

`external`

a location to store the external time

`rate_num`

a location to store the rate numerator

true if the clock is currently synced

Get an ID from self to trigger a periodic notification. The periodic notifications will start at time start_time and will then be fired with the given interval. id should be unreffed after usage.

Free-function: gst_clock_id_unref

`start_time`

the requested start time

`interval`

the requested interval

Returns

a ClockID that can be used to request the time notification.

MT safe.

Get a ClockID from self to trigger a single shot notification at the requested time. The single shot id should be unreffed after usage.

Free-function: gst_clock_id_unref

`time`

the requested time

Returns

a ClockID that can be used to request the time notification.

MT safe.

Reinitializes the provided periodic id to the provided start time and interval. Does not modify the reference count.

`id`

a ClockID

`start_time`

the requested start time

`interval`

the requested interval

Returns

true if the GstClockID could be reinitialized to the provided time, else false.

Adjusts the rate and time of self. A rate of 1/1 is the normal speed of the clock. Values bigger than 1/1 make the clock go faster.

internal and external are calibration parameters that arrange that ClockExt::get_time should have been external at internal time internal. This internal time should not be in the future; that is, it should be less than the value of ClockExt::get_internal_time when this function is called.

Subsequent calls to ClockExt::get_time will return clock times computed as follows:

  time = (internal_time - internal) * rate_num / rate_denom + external

This formula is implemented in ClockExt::adjust_unlocked. Of course, it tries to do the integer arithmetic as precisely as possible.

Note that ClockExt::get_time always returns increasing values so when you move the clock backwards, ClockExt::get_time will report the previous value until the clock catches up.

MT safe.

`internal`

a reference internal time

`external`

a reference external time

`rate_num`

the numerator of the rate of the clock relative to its internal time

`rate_denom`

the denominator of the rate of the clock

Set master as the master clock for self. self will be automatically calibrated so that ClockExt::get_time reports the same time as the master clock.

A clock provider that slaves its clock to a master can get the current calibration values with ClockExt::get_calibration.

master can be None in which case self will not be slaved anymore. It will however keep reporting its time adjusted with the last configured rate and time offsets.

`master`

a master Clock

Returns

true if the clock is capable of being slaved to a master clock. Trying to set a master on a clock without the ClockFlags::CanSetMaster flag will make this function return false.

MT safe.

Set the accuracy of the clock. Some clocks have the possibility to operate with different accuracy at the expense of more resource usage. There is normally no need to change the default resolution of a clock. The resolution of a clock can only be changed if the clock has the ClockFlags::CanSetResolution flag set.

`resolution`

The resolution to set

Returns

the new resolution of the clock.

Sets self to synced and emits the GstClock::synced signal, and wakes up any thread waiting in ClockExt::wait_for_sync.

This function must only be called if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is set on the clock, and is intended to be called by subclasses only.

`synced`

if the clock is synced

Set the amount of time, in nanoseconds, to sample master and slave clocks

`timeout`

a timeout

Reinitializes the provided single shot id to the provided time. Does not modify the reference count.

`id`

a ClockID

`time`

The requested time.

Returns

true if the GstClockID could be reinitialized to the provided time, else false.

Converts the given external clock time to the internal time of self, using the rate and reference time set with ClockExt::set_calibration. This function should be called with the clock's OBJECT_LOCK held and is mainly used by clock subclasses.

This function is the reverse of ClockExt::adjust_unlocked.

`external`

an external clock time

Returns

the internal time of the clock corresponding to external.

Converts the given external_target clock time to the internal time, using the passed calibration parameters. This function performs the same calculation as ClockExt::unadjust_unlocked when called using the current calibration parameters.

Note: The self parameter is unused and can be NULL

`external_target`

a clock time

`cinternal`

a reference internal time

`cexternal`

a reference external time

`cnum`

the numerator of the rate of the clock relative to its internal time

`cdenom`

the denominator of the rate of the clock

Returns

the converted time of the clock.

Waits until self is synced for reporting the current time. If timeout is GST_CLOCK_TIME_NONE it will wait forever, otherwise it will time out after timeout nanoseconds.

For asynchronous waiting, the GstClock::synced signal can be used.

This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock, or if the clock is already synced.

`timeout`

timeout for waiting or GST_CLOCK_TIME_NONE

Returns

true if waiting was successful, or false on timeout

Signaled on clocks with GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once the clock is synchronized, or when it completely lost synchronization. This signal will not be emitted on clocks without the flag.

This signal will be emitted from an arbitrary thread, most likely not the application's main thread.

`synced`

if the clock is synced now

The return value of a clock operation.

The operation succeeded.

The operation was scheduled too late.

The clockID was unscheduled

The ClockID is busy

A bad time was provided to a function.

An error occurred

Operation is not supported

The ClockID is done waiting

The different kind of clocks.

time since Epoch

monotonic time since some unspecified starting point

some other time source is used (Since 1.0.5)

Context is a container object used to store contexts like a device context, a display server connection and similar concepts that should be shared between multiple elements.

Applications can set a context on a complete pipeline by using ElementExt::set_context, which will then be propagated to all child elements. Elements can handle these in ElementClass.set_context() and merge them with the context information they already have.

When an element needs a context it will do the following actions in this order until one step succeeds:

Check if the element already has a context
Query downstream with GST_QUERY_CONTEXT for the context
Query upstream with GST_QUERY_CONTEXT for the context
Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required context types and afterwards check if a usable context was set now
Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message on the bus.

Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously known context on the element that asks for it if possible. Otherwise the application should provide one if it can.

Contexts can be persistent. A persistent Context is kept in elements when they reach State::Null, non-persistent ones will be removed. Also, a non-persistent context won't override a previous persistent context set to an element.

Create a new context.

`context_type`

Context type

`persistent`

Persistent context

Returns

The new context.

Get the type of self.

Returns

The type of the context.

Access the structure of the context.

Returns

The structure of the context. The structure is still owned by the context, which means that you should not modify it, free it and that the pointer becomes invalid when you free the context.

Checks if self has context_type.

`context_type`

Context type to check.

Returns

true if self has context_type.

Check if self is persistent.

Returns

true if the context is persistent.

Get a writable version of the structure.

Returns

The structure of the context. The structure is still owned by the context, which means that you should not free it and that the pointer becomes invalid when you free the context. This function checks if self is writable.

Core errors are errors inside the core GStreamer library.

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

do not use this except as a placeholder for deciding where to go while developing code.

use this when you do not want to implement this functionality yet.

used for state change errors.

used for pad-related errors.

used for thread-related errors.

used for negotiation-related errors.

used for event-related errors.

used for seek-related errors.

used for caps-related errors.

used for negotiation-related errors.

used if a plugin is missing.

used for clock related errors.

used if functionality has been disabled at compile time.

the number of core error types.

Struct to store date, time and timezone information altogether. DateTime is refcounted and immutable.

Date information is handled using the proleptic Gregorian calendar.

Provides basic creation functions and accessor functions to its fields.

Creates a new DateTime using the date and times in the gregorian calendar in the supplied timezone.

year should be from 1 to 9999, month should be from 1 to 12, day from 1 to 31, hour from 0 to 23, minutes and seconds from 0 to 59.

Note that tzoffset is a float and was chosen so for being able to handle some fractional timezones, while it still keeps the readability of representing it in hours for most timezones.

If value is -1 then all over value will be ignored. For example if month == -1, then DateTime will created only for year. If day == -1, then DateTime will created for year and month and so on.

Free-function: gst_date_time_unref

`tzoffset`

the newly created DateTime

Creates a new DateTime using the time since Jan 1, 1970 specified by secs. The DateTime is in the UTC timezone.

Free-function: gst_date_time_unref

`secs`

seconds from the Unix epoch

Returns

the newly created DateTime

Creates a new DateTime using the date and times in the gregorian calendar in the local timezone.

year should be from 1 to 9999, month should be from 1 to 12, day from 1 to 31, hour from 0 to 23, minutes and seconds from 0 to 59.

If month is -1, then the DateTime created will only contain year, and all other fields will be considered not set.

the newly created DateTime which should be freed with DateTime::unref.

Creates a new DateTime using the date and times in the gregorian calendar in the local timezone.

year should be from 1 to 9999.

Free-function: gst_date_time_unref

`year`

the gregorian year

Returns

the newly created DateTime

Creates a new DateTime using the date and times in the gregorian calendar in the local timezone.

year should be from 1 to 9999, month should be from 1 to 12.

If value is -1 then all over value will be ignored. For example if month == -1, then DateTime will created only for year.

Free-function: gst_date_time_unref

`year`

the gregorian year

`month`

the gregorian month

Returns

the newly created DateTime

Creates a new DateTime using the date and times in the gregorian calendar in the local timezone.

year should be from 1 to 9999, month should be from 1 to 12, day from 1 to 31.

Free-function: gst_date_time_unref

`year`

the gregorian year

`month`

the gregorian month

the offset from UTC in hours

true if self's year field is set (which should always be the case), otherwise false

Atomically increments the reference count of self by one.

Returns

the reference self

Creates a new glib::DateTime from a fully defined DateTime object.

Free-function: g_date_time_unref

Returns

a newly created glib::DateTime, or None on error

Create a minimal string compatible with ISO-8601. Possible output formats are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z, 2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100

Returns

a newly allocated string formatted according to ISO 8601 and only including the datetime fields that are valid, or None in case there was an error. The string should be freed with g_free.

Atomically decrements the reference count of self by one. When the reference count reaches zero, the structure is freed.

The level defines the importance of a debugging message. The more important a message is, the greater the probability that the debugging system outputs it.

No debugging level specified or desired. Used to deactivate debugging output.

Error messages are to be used only when an error occurred that stops the application from keeping working correctly. An examples is gst_element_error, which outputs a message with this priority. It does not mean that the application is terminating as with g_error.

Warning messages are to inform about abnormal behaviour that could lead to problems or weird behaviour later on. An example of this would be clocking issues ("your computer is pretty slow") or broken input data ("Can't synchronize to stream.")

Fixme messages are messages that indicate that something in the executed code path is not fully implemented or handled yet. Note that this does not replace proper error handling in any way, the purpose of this message is to make it easier to spot incomplete/unfinished pieces of code when reading the debug log.

Informational messages should be used to keep the developer updated about what is happening. Examples where this should be used are when a typefind function has successfully determined the type of the stream or when an mp3 plugin detects the format to be used. ("This file has mono sound.")

Debugging messages should be used when something common happens that is not the expected default behavior, or something that's useful to know but doesn't happen all the time (ie. per loop iteration or buffer processed or event handled). An example would be notifications about state changes or receiving/sending of events.

Log messages are messages that are very common but might be useful to know. As a rule of thumb a pipeline that is running as expected should never output anything else but LOG messages whilst processing data. Use this log level to log recurring information in chain functions and loop functions, for example.

Tracing-related messages. Examples for this are referencing/dereferencing of objects.

memory dump messages are used to log (small) chunks of data as memory dumps in the log. They will be displayed as hexdump with ASCII characters.

The number of defined debugging levels.

Device are objects representing a device, they contain relevant metadata about the device, such as its class and the Caps representing the media types it can produce or handle.

Device are created by DeviceProvider objects which can be aggregated by DeviceMonitor objects.

Implements

DeviceExt, GstObjectExt, glib::object::ObjectExt

Trait containing all Device methods.

Implementors

Device

Creates the element with all of the required parameters set to use this device.

`element`

a Element

Returns

true if the element could be reconfigured to use this device, false otherwise.

Applications should create a DeviceMonitor when they want to probe, list and monitor devices of a specific type. The DeviceMonitor will create the appropriate DeviceProvider objects and manage them. It will then post messages on its Bus for devices that have been added and removed.

The device monitor will monitor all devices matching the filters that the application has set.

The basic use pattern of a device monitor is as follows:

  static gboolean
  my_bus_func (GstBus * bus, GstMessage * message, gpointer user_data)
  {
     GstDevice *device;
     gchar *name;

     switch (GST_MESSAGE_TYPE (message)) {
       case GST_MESSAGE_DEVICE_ADDED:
         gst_message_parse_device_added (message, &device);
         name = gst_device_get_display_name (device);
         g_print("Device added: %s\n", name);
         g_free (name);
         gst_object_unref (device);
         break;
       case GST_MESSAGE_DEVICE_REMOVED:
         gst_message_parse_device_removed (message, &device);
         name = gst_device_get_display_name (device);
         g_print("Device removed: %s\n", name);
         g_free (name);
         gst_object_unref (device);
         break;
       default:
         break;
     }

     return G_SOURCE_CONTINUE;
  }

  GstDeviceMonitor *
  setup_raw_video_source_device_monitor (void) {
     GstDeviceMonitor *monitor;
     GstBus *bus;
     GstCaps *caps;

     monitor = gst_device_monitor_new ();

     bus = gst_device_monitor_get_bus (monitor);
     gst_bus_add_watch (bus, my_bus_func, NULL);
     gst_object_unref (bus);

     caps = gst_caps_new_empty_simple ("video/x-raw");
     gst_device_monitor_add_filter (monitor, "Video/Source", caps);
     gst_caps_unref (caps);

     gst_device_monitor_start (monitor);

     return monitor;
  }

Implements

DeviceMonitorExt, GstObjectExt, glib::object::ObjectExt

Trait containing all DeviceMonitor methods.

Implementors

DeviceMonitor

Create a new DeviceMonitor

Returns

a new device monitor.

Adds a filter for which Device will be monitored, any device that matches all these classes and the Caps will be returned.

If this function is called multiple times to add more filters, each will be matched independently. That is, adding more filters will not further restrict what devices are matched.

The Caps supported by the device as returned by DeviceExt::get_caps are not intersected with caps filters added using this function.

Filters must be added before the DeviceMonitor is started.

`classes`

device classes to use as filter or None for any class

`caps`

the Caps to filter or None for ANY

Returns

The id of the new filter or 0 if no provider matched the filter's classes.

Gets the Bus of this DeviceMonitor

Returns

a Bus

Gets a list of devices from all of the relevant monitors. This may actually probe the hardware if the monitor is not currently started.

Returns

a glib::List of Device

Get a list of the currently selected device provider factories.

This

Returns

A list of device provider factory names that are currently being monitored by self or None when nothing is being monitored.

Get if self is curretly showing all devices, even those from hidden providers.

Returns

true when all devices will be shown.

Removes a filter from the DeviceMonitor using the id that was returned by DeviceMonitorExt::add_filter.

`filter_id`

the id of the filter

Returns

true of the filter id was valid, false otherwise

Set if all devices should be visible, even those devices from hidden providers. Setting show_all to true might show some devices multiple times.

`show_all`

show all devices

Starts monitoring the devices, one this has succeeded, the MessageType::DeviceAdded and MessageType::DeviceRemoved messages will be emitted on the bus when the list of devices changes.

Returns

true if the device monitoring could be started

Stops monitoring the devices.

A DeviceProvider subclass is provided by a plugin that handles devices if there is a way to programatically list connected devices. It can also optionally provide updates to the list of connected devices.

Each DeviceProvider subclass is a singleton, a plugin should normally provide a single subclass for all devices.

Applications would normally use a DeviceMonitor to monitor devices from all relevant providers.

Implements

DeviceProviderExt, GstObjectExt, glib::object::ObjectExt

Trait containing all DeviceProvider methods.

Implementors

DeviceProvider

Create a new device providerfactory capable of instantiating objects of the type_ and add the factory to plugin.

`plugin`

Plugin to register the device provider with, or None for a static device provider.

`name`

name of device providers of this type

`rank`

rank of device provider (higher rank means more importance when autoplugging)

`type_`

GType of device provider to register

Returns

true, if the registering succeeded, false on error

Posts a message on the provider's Bus to inform applications that a new device has been added.

This is for use by subclasses.

device's reference count will be incremented, and any floating reference will be removed (see Object::ref_sink).

`device`

a Device that has been added

`key`

the key to get

Returns

the metadata for key.

Make self hide the devices from the factory with name.

This function is used when self will also provide the devices reported by provider factory name. A monitor should stop monitoring the device provider with name to avoid duplicate devices.

`name`

a provider factory name

Starts providering the devices. This will cause MessageType::DeviceAdded and MessageType::DeviceRemoved messages to be posted on the provider's bus when devices are added or removed from the system.

Since the DeviceProvider is a singleton, DeviceProviderExt::start may already have been called by another user of the object, DeviceProviderExt::stop needs to be called the same number of times.

Returns

true if the device providering could be started

Decreases the use-count by one. If the use count reaches zero, this DeviceProvider will stop providering the devices. This needs to be called the same number of times that DeviceProviderExt::start was called.

Make self unhide the devices from factory name.

This function is used when self will no longer provide the devices reported by provider factory name. A monitor should start monitoring the devices from provider factory name in order to see all devices again.

`name`

a provider factory name

DeviceProviderFactory is used to create instances of device providers. A GstDeviceProviderfactory can be added to a Plugin as it is also a PluginFeature.

the DeviceProvider or None if the device provider couldn't be created

Get the glib::Type for device providers managed by this factory. The type can only be retrieved if the device provider factory is loaded, which can be assured with PluginFeatureExt::load.

Returns

the glib::Type for device providers managed by this factory.

Get the metadata on self with key.

`key`

a key

Returns

the metadata with key on self or None when there was no metadata with the given key.

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 glib::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 ElementExt::add_pad and ElementExt::remove_pad.

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

Elements can be linked through their pads. If the link is straightforward, use the ElementExt::link convenience function to link two elements, or ElementExt::link_many for more elements in a row. Use ElementExt::link_filtered to link two elements constrained by a specified set of Caps. For finer control, use ElementExt::link_pads and ElementExt::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 ElementExt::get_state and ElementExt::set_state. Setting a state triggers a StateChange. To get a string representation of a State, use Element::state_get_name.

You can get and set a Clock on an element using ElementExt::get_clock and ElementExt::set_clock. Some elements can provide a clock for the pipeline if the ElementFlags::ProvideClock flag is set. With the ElementExt::provide_clock method one can retrieve the clock provided by such an element. Not all elements require a clock to operate correctly. If the ElementFlags::RequireClock() flag is set, a clock should be set on the element with ElementExt::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.

Implements

ElementExt, GstObjectExt, glib::object::ObjectExt

Trait containing all Element methods.

Implementors

Bin, Element, TagSetter, TocSetter

Creates an element for handling the given URI.

`type_`

Whether to create a source or a sink

`uri`

URI to create an element for

`elementname`

Name of created element, can be None.

Returns

a new element or None if none could be created

Create a new elementfactory capable of instantiating objects of the type_ and add the factory to plugin.

`plugin`

Plugin to register the element with, or None for a static element.

`name`

name of elements of this type

a string with the name of the state.

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.

Adds a pad (link point) to self. pad's parent will be set to self; see GstObjectExt::set_parent for refcounting information.

Pads are not automatically activated so elements should perform the needed steps to activate the pad in case this pad is added in the PAUSED or PLAYING state. See PadExt::set_active for more information about activating pads.

The pad and the element should be unlocked when calling this function.

This function will emit the Element::pad-added signal on the element.

`pad`

the Pad to add to the element.

Returns

true if the pad could be added. This function can fail when a pad with the same name already existed or the pad already had another parent.

MT safe.

Feature: v1_10

`property_name`

name of property to watch for changes, or NULL to watch all properties

`include_value`

whether to include the new property value in the message

Returns

a watch id, which can be used in connection with Element::remove_property_notify_watch to remove the watch again.

Feature: v1_10

`property_name`

name of property to watch for changes, or NULL to watch all properties

`include_value`

whether to include the new property value in the message

Returns

a watch id, which can be used in connection with Element::remove_property_notify_watch to remove the watch again.

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 ElementExt::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.

Feature: v1_10

`func`

Function to call asynchronously from another thread

`user_data`

Data to pass to func

`destroy_notify`

GDestroyNotify for user_data

Perform transition on self.

This function must be called with STATE_LOCK held and is mainly used internally.

`transition`

the requested transition

Returns

the StateChangeReturn of the state transition.

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 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.

`ret`

The previous state return value

Returns

The result of the commit state change.

MT safe.

Creates a pad for each pad template that is always available. This function is only useful during object initialization of subclasses of Element.

Call func with user_data for each of self'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 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.

Feature: v1_14

`func`

function to call for each pad

`user_data`

user data passed to func

Returns

false if self had no pads or if one of the calls to func returned false.

Call func with user_data for each of self'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 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.

Feature: v1_14

`func`

function to call for each sink pad

`user_data`

user data passed to func

Returns

false if self had no sink pads or if one of the calls to func returned false.

Call func with user_data for each of self'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 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.

Feature: v1_14

`func`

function to call for each source pad

`user_data`

user data passed to func

Returns

false if self had no source pads or if one of the calls to func returned false.

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.

the Pad to find a compatible one for.

`caps`

the Caps to use as a filter.

Returns

the Pad to which a link can be made, or None if one cannot be found. GstObjectExt::unref after usage.

Retrieves a pad template from self that is compatible with compattempl. Pads from compatible templates can be linked together.

`compattempl`

the PadTemplate to find a compatible template for

Returns

a compatible PadTemplate, or None if none was found. No unreferencing is necessary.

Gets the context with context_type set on the element or NULL.

MT safe.

`context_type`

a name of a context to retrieve

Returns

A Context or NULL

Gets the context with context_type set on the element or NULL.

`context_type`

a name of a context to retrieve

Returns

A Context or NULL

Gets the contexts set on the element.

MT safe.

Returns

List of Context

the glib::List of pad templates.

Retrieves a pad from the element by name (e.g. "src_%d"). This version only retrieves request pads. The pad should be released with ElementExt::release_request_pad.

This method is slower than manually getting the pad template and calling ElementExt::request_pad if the pads should have a specific name (e.g. name is "src_1" instead of "src_%u").

`name`

the name of the request Pad to retrieve.

Returns

requested Pad if found, otherwise None. Release after usage.

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 Pipeline.

MT safe.

Returns

the start time of the element.

Gets the state of the element.

For elements that performed an ASYNC state change, as reported by ElementExt::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 StateChangeReturn::Success or StateChangeReturn::Failure respectively.

For elements that did not return StateChangeReturn::Async, this function returns the current and pending state immediately.

This function returns StateChangeReturn::NoPreroll 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 State::Playing. While the state change return is equivalent to 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.

`state`

a pointer to State to hold the state. Can be None.

`pending`

a pointer to State to hold the pending state. Can be None.

`timeout`

a ClockTime to specify the timeout for an async state change or GST_CLOCK_TIME_NONE for infinite timeout.

Returns

StateChangeReturn::Success if the element has no more pending state and the last state change succeeded, StateChangeReturn::Async if the element is still performing a state change or StateChangeReturn::Failure if the last state change failed.

MT safe.

Retrieves a pad from self by name. This version only retrieves already-existing (i.e. 'static') pads.

`name`

the name of the static Pad to retrieve.

Returns

the requested Pad if found, otherwise None. unref after usage.

MT safe.

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 State::Null.

MT safe.

the Element containing the destination pad.

Returns

true if the elements could be linked, false otherwise.

Links self 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 BinExt::add before trying to link them.

`dest`

the Element containing the destination pad.

`filter`

the Caps to filter the link, or None for no filter.

Returns

true if the pads could be linked, false otherwise.

Chain together a series of elements. Uses ElementExt::link. Make sure you have added your elements to a bin or pipeline with BinExt::add before trying to link them.

`element_2`

the second Element in the link chain.

Returns

Returns

true if the pads could be linked, false otherwise.

Brings the element to the lost state. The current state of the element is copied to the pending state so that any call to ElementExt::get_state will return 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 State::Paused or 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.

Post an error, warning or info message on the bus from inside an element.

type_ must be of MessageType::Error, MessageType::Warning or MessageType::Info.

MT safe.

`type_`

the MessageType

`domain`

the GStreamer GError domain this message belongs to

`code`

the GError code belonging to the domain

`text`

an allocated text string to be used as a replacement for the default message connected to code, or None

`debug`

an allocated debug message to be used as a replacement for the default debugging information, or None

`file`

the source code file where the error was generated

`function`

the source code function where the error was generated

`line`

the source code line where the error was generated

Post an error, warning or info message on the bus from inside an element.

type_ must be of MessageType::Error, MessageType::Warning or MessageType::Info.

Feature: v1_10

`type_`

the MessageType

`domain`

the GStreamer GError domain this message belongs to

`code`

the GError code belonging to the domain

`text`

an allocated text string to be used as a replacement for the default message connected to code, or None

`debug`

an allocated debug message to be used as a replacement for the default debugging information, or None

`file`

the source code file where the error was generated

`function`

the source code function where the error was generated

`line`

the source code line where the error was generated

`structure`

optional details structure

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 PadPresence::Sometimes pad templates use this in combination with autopluggers to figure out that the element is done initializing its pads.

This function emits the Element::no-more-pads signal.

MT safe.

Post a message on the element's 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.

`message`

a Message to post

Returns

true if the message was successfully posted. The function returns false if the element did not have a bus.

MT safe.

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.

Returns

the GstClock provided by the element or None if no clock could be provided. Unref after usage.

MT safe.

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.

`query`

the Query.

Returns

true if the query could be performed.

MT safe.

Queries an element to convert src_val in src_format to dest_format.

`src_format`

a Format to convert from.

`src_val`

a value to convert.

`dest_format`

the Format to convert to.

`dest_val`

a pointer to the result.

Returns

true if the query could be performed.

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.

`format`

the Format requested

`duration`

A location in which to store the total duration, or None.

Returns

true if the query could be performed.

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 Element::query.

`format`

the Format requested

`cur`

a location in which to store the current position, or None.

Returns

true if the query could be performed.

Makes the element free the previously requested pad as obtained with ElementExt::request_pad.

This does not unref the pad. If the pad was created by using ElementExt::request_pad, ElementExt::release_request_pad needs to be followed by GstObjectExt::unref to free the pad.

MT safe.

`pad`

the Pad to release.

Removes pad from self. pad will be destroyed if it has not been referenced elsewhere using GstObjectExt::unparent.

This function is used by plugin developers and should not be used by applications. Pads that were dynamically requested from elements with ElementExt::request_pad should be released with the ElementExt::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 PadExt::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 Element::pad-removed signal on the element.

`pad`

the Pad to remove from the element.

Returns

true if the pad could be removed. Can return false if the pad does not belong to the provided element.

MT safe.

Feature: v1_10

`watch_id`

watch id to remove

Retrieves a request pad from the element according to the provided template. Pad templates can be looked up using ElementFactory::get_static_pad_templates.

The pad should be released with ElementExt::release_request_pad.

`templ`

a PadTemplate of which we want a pad of.

`name`

the name of the request Pad to retrieve. Can be None.

`caps`

the caps of the pad we want to request. Can be None.

Returns

requested Pad if found, otherwise None. Release after usage.

Sends a seek event to an element. See Event::new_seek for the details of the parameters. The seek event is sent to the element using Element::send_event.

MT safe.

`rate`

The new playback rate

`format`

The format of the seek values

`flags`

The optional seek flags.

`start_type`

The type and flags for the new start position

`start`

the Bus to set.

Sets the clock for the element. This function increases the refcount on the clock. Any previously set clock on the object is unreffed.

`clock`

the Clock to set for the element.

Returns

true if the element accepted the clock. An element can refuse a clock when it, for example, is not able to slave its internal clock to the clock or when it requires a specific clock to operate.

MT safe.

Sets the context of the element. Increases the refcount of the context.

MT safe.

`context`

the Context to set.

Locks the state of an element, so state changes of the parent don't affect this element anymore.

MT safe.

`locked_state`

true to lock the element's state

Returns

true if the state was changed, false if bad parameters were given or the elements state-locking needed no change.

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 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.

`time`

the base time to set.

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 StateChangeReturn::Async, in which case the element will perform the remainder of the state change asynchronously in another thread. An application can use ElementExt::get_state to wait for the completion of the state change or it can wait for a MessageType::AsyncDone or MessageType::StateChanged on the bus.

State changes to State::Ready or State::Null never return StateChangeReturn::Async.

`state`

the element's new State.

Returns

Result of the state change using StateChangeReturn.

MT safe.

Tries to change the state of the element to the same as its parent. If this function returns false, the state of element is undefined.

Returns

true, if the element's state could be synced to the parent's state.

MT safe.

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 ElementExt::link, it could have created an requestpad, which has to be released using ElementExt::release_request_pad.

`dest`

the sink Element to unlink.

Unlinks a series of elements. Uses ElementExt::unlink.

`element_2`

the second Element in the link chain.

Unlinks the two named pads of the source and destination elements.

This is a convenience function for PadExt::unlink.

`srcpadname`

the name of the Pad in source element.

`dest`

a Element containing the destination pad.

`destpadname`

the name of the Pad in destination element.

This signals that the element will not generate more dynamic pads. Note that this signal will usually be emitted from the context of the streaming thread.

a new Pad has been added to the element. Note that this signal will usually be emitted from the context of the streaming thread. Also keep in mind that if you add new elements to the pipeline in the signal handler you will need to set them to the desired target state with ElementExt::set_state or ElementExt::sync_state_with_parent.

`new_pad`

the pad that has been added

a Pad has been removed from the element

`old_pad`

the pad that has been removed

ElementFactory is used to create instances of elements. A GstElementFactory can be added to a Plugin as it is also a PluginFeature.

Use the ElementFactory::find and ElementFactory::create functions to create element instances or use ElementFactory::make as a convenient shortcut.

The following code example shows you how to create a GstFileSrc element.

Using an element factory

  #include &lt;gst/gst.h&gt;

  GstElement *src;
  GstElementFactory *srcfactory;

  gst_init (&amp;argc, &amp;argv);

  srcfactory = gst_element_factory_find ("filesrc");
  g_return_if_fail (srcfactory != NULL);
  src = gst_element_factory_create (srcfactory, "src");
  g_return_if_fail (src != NULL);
  ...

Implements

PluginFeatureExt, GstObjectExt, glib::object::ObjectExt

Search for an element factory of the given name. Refs the returned element factory; caller is responsible for unreffing.

`name`

name of factory to find

Returns

ElementFactory if found, None otherwise

Filter out all the elementfactories in list that can handle caps in the given direction.

If subsetonly is true, then only the elements whose pads templates are a complete superset of caps will be returned. Else any element whose pad templates caps can intersect with caps will be returned.

`list`

a glib::List of ElementFactory to filter

new Element or None if the element couldn't be created

Get the glib::Type for elements managed by this factory. The type can only be retrieved if the element factory is loaded, which can be assured with PluginFeatureExt::load.

Returns

the glib::Type for elements managed by this factory or 0 if the factory is not loaded.

Get the metadata on self with key.

Events that have been received can be parsed with their respective gst_event_parse_*() functions. It is valid to pass None for unwanted details.

Events are passed between elements in parallel to the data stream. Some events are serialized with buffers, others are not. Some events only travel downstream, others only upstream. Some events can travel both upstream and downstream.

The events are used to signal special conditions in the datastream such as EOS (end of stream) or the start of a new stream-segment. Events are also used to flush the pipeline of any pending data.

Most of the event API is used inside plugins. Applications usually only construct and use seek events. To do that Event::new_seek is used to create a seek event. It takes the needed parameters to specify seeking time and mode.

  GstEvent *event;
  gboolean result;
  ...
  // construct a seek event to play the media from second 2 to 5, flush
  // the pipeline to decrease latency.
  event = gst_event_new_seek (1.0,
     GST_FORMAT_TIME,
     GST_SEEK_FLAG_FLUSH,
     GST_SEEK_TYPE_SET, 2 * GST_SECOND,
     GST_SEEK_TYPE_SET, 5 * GST_SECOND);
  ...
  result = gst_element_send_event (pipeline, event);
  if (!result)
    g_warning ("seek failed");
  ...

Create a new buffersize event. The event is sent downstream and notifies elements that they should provide a buffer of the specified dimensions.

When the async flag is set, a thread boundary is preferred.

`format`

buffer format

`minsize`

Elements can process this event synchronized with the dataflow since the preceding FLUSH_START event stopped the dataflow.

This event is typically generated to complete a seek and to resume dataflow.

`reset_time`

if time should be reset

Returns

a new flush stop event.

Create a new GAP event. A gap event can be thought of as conceptually equivalent to a buffer to signal that there is no data for a certain amount of time. This is useful to signal a gap to downstream elements which may wait for data, such as muxers or mixers or overlays, especially for sparse streams such as subtitle streams.

`timestamp`

the start time (pts) of the gap

`duration`

the duration of the gap

Returns

the new GAP event.

Create a new latency event. The event is sent upstream from the sinks and notifies elements that they should add an additional latency to the running time before synchronising against the clock.

The latency is mostly used in live sinks and is always expressed in the time format.

`latency`

the new latency value

Returns

a new Event

Create a new navigation event from the given description.

`structure`

description of the event. The event will take ownership of the structure.

Returns

a new Event

Creates a new event containing information specific to a particular protection system (uniquely identified by system_id), by which that protection system can acquire key(s) to decrypt a protected stream.

In order for a decryption element to decrypt media protected using a specific system, it first needs all the protection system specific information necessary to acquire the decryption key(s) for that stream. The functions defined here enable this information to be passed in events from elements that extract it (e.g., ISOBMFF demuxers, MPEG DASH demuxers) to protection decrypter elements that use it.

Events containing protection system specific information are created using Event::new_protection, and they can be parsed by downstream elements using Event::parse_protection.

In Common Encryption, protection system specific information may be located within ISOBMFF files, both in movie (moov) boxes and movie fragment (moof) boxes; it may also be contained in ContentProtection elements within MPEG DASH MPDs. The events created by Event::new_protection contain data identifying from which of these locations the encapsulated protection system specific information originated. This origin information is required as some protection systems use different encodings depending upon where the information originates.

The events returned by Event::new_protection are implemented in such a way as to ensure that the most recently-pushed protection info event of a particular origin and system_id will be stuck to the output pad of the sending element.

`system_id`

a string holding a UUID that uniquely identifies a protection system.

`data`

a Buffer holding protection system specific information. The reference count of the buffer will be incremented by one.

`origin`

a string indicating where the protection information carried in the event was extracted from. The allowed values of this string will depend upon the protection scheme.

Returns

a EventType::Protection event, if successful; None if unsuccessful.

Allocate a new qos event with the given values. The QOS event is generated in an element that wants an upstream element to either reduce or increase its rate because of high/low CPU load or other resource usage such as network performance or throttling. Typically sinks generate these events for each buffer they receive.

type_ indicates the reason for the QoS event. QOSType::Overflow is used when a buffer arrived in time or when the sink cannot keep up with the upstream datarate. QOSType::Underflow is when the sink is not receiving buffers fast enough and thus has to drop late buffers. QOSType::Throttle is used when the datarate is artificially limited by the application, for example to reduce power consumption.

proportion indicates the real-time performance of the streaming in the element that generated the QoS event (usually the sink). The value is generally computed based on more long term statistics about the streams timestamps compared to the clock. A value < 1.0 indicates that the upstream element is producing data faster than real-time. A value > 1.0 indicates that the upstream element is not producing data fast enough. 1.0 is the ideal proportion value. The proportion value can safely be used to lower or increase the quality of the element.

diff is the difference against the clock in running time of the last buffer that caused the element to generate the QOS event. A negative value means that the buffer with timestamp arrived in time. A positive value indicates how late the buffer with timestamp was. When throttling is enabled, diff will be set to the requested throttling interval.

timestamp is the timestamp of the last buffer that cause the element to generate the QOS event. It is expressed in running time and thus an ever increasing value.

The upstream element can use the diff and timestamp values to decide whether to process more buffers. For positive diff, all buffers with timestamp <= timestamp + diff will certainly arrive late in the sink as well. A (negative) diff value so that timestamp + diff would yield a result smaller than 0 is not allowed.

The application can use general event probes to intercept the QoS event and implement custom application specific QoS handling.

`type_`

the QoS type

`proportion`

the proportion of the qos message

`diff`

The time difference of the last Clock sync

`timestamp`

The timestamp of the buffer

Returns

a new QOS event.

Create a new reconfigure event. The purpose of the reconfigure event is to travel upstream and make elements renegotiate their caps or reconfigure their buffer pools. This is useful when changing properties on elements or changing the topology of the pipeline.

Returns

a new Event

Allocate a new seek event with the given parameters.

The seek event configures playback of the pipeline between start to stop at the speed given in rate, also called a playback segment. The start and stop values are expressed in format.

A rate of 1.0 means normal playback rate, 2.0 means double speed. Negatives values means backwards playback. A value of 0.0 for the rate is not allowed and should be accomplished instead by PAUSING the pipeline.

A pipeline has a default playback segment configured with a start position of 0, a stop position of -1 and a rate of 1.0. The currently configured playback segment can be queried with QueryType::Segment.

start_type and stop_type specify how to adjust the currently configured start and stop fields in playback segment. Adjustments can be made relative or absolute to the last configured values. A type of SeekType::None means that the position should not be updated.

When the rate is positive and start has been updated, playback will start from the newly configured start position.

For negative rates, playback will start from the newly configured stop position (if any). If the stop position is updated, it must be different from -1 (GST_CLOCK_TIME_NONE) for negative rates.

It is not possible to seek relative to the current playback position, to do this, PAUSE the pipeline, query the current playback position with QueryType::Position and update the playback segment current position with a SeekType::Set to the desired position.

`rate`

The new playback rate

`format`

The format of the seek values

`flags`

The optional seek flags

`start_type`

The type and flags for the new start position

`start`

The value of the new start position

`stop_type`

The type and flags for the new stop position

`stop`

The value of the new stop position

Returns

a new seek event.

Create a new SEGMENT event for segment. The segment event can only travel downstream synchronized with the buffer flow and contains timing information and playback properties for the buffers that will follow.

The segment event marks the range of buffers to be processed. All data not within the segment range is not to be processed. This can be used intelligently by plugins to apply more efficient methods of skipping unneeded data. The valid range is expressed with the start and stop values.

The time value of the segment is used in conjunction with the start value to convert the buffer timestamps into the stream time. This is usually done in sinks to report the current stream_time. time represents the stream_time of a buffer carrying a timestamp of start. time cannot be -1.

start cannot be -1, stop can be -1. If there is a valid stop given, it must be greater or equal the start, including when the indicated playback rate is < 0.

The applied_rate value provides information about any rate adjustment that has already been made to the timestamps and content on the buffers of the stream. (rate * applied_rate) should always equal the rate that has been requested for playback. For example, if an element has an input segment with intended playback rate of 2.0 and applied_rate of 1.0, it can adjust incoming timestamps and buffer content by half and output a segment event with rate of 1.0 and applied_rate of 2.0

After a segment event, the buffer stream time is calculated with:

time + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate)

`segment`

a Segment

Returns

the new SEGMENT event.

Create a new segment-done event. This event is sent by elements that finish playback of a segment as a result of a segment seek.

`format`

The format of the position being done

`position`

The position of the segment being done

Returns

a new Event

Allocate a new select-streams event.

The select-streams event requests the specified streams to be activated.

The list of streams corresponds to the "Stream ID" of each stream to be activated. Those ID can be obtained via the Stream objects present in EventType::StreamStart, EventType::StreamCollection or MessageType::StreamCollection.

Note: The list of streams can not be empty.

Feature: v1_10

`streams`

the list of streams to activate

Returns

a new select-streams event or None in case of an error (like an empty streams list).

Create a new sink-message event. The purpose of the sink-message event is to instruct a sink to post the message contained in the event synchronized with the stream.

name is used to store multiple sticky events on one pad.

`name`

a name for the event

`msg`

the Message to be posted

Returns

a new Event

Create a new step event. The purpose of the step event is to instruct a sink to skip amount (expressed in format) of media. It can be used to implement stepping through the video frame by frame or for doing fast trick modes.

A rate of <= 0.0 is not allowed. Pause the pipeline, for the effect of rate = 0.0 or first reverse the direction of playback using a seek event to get the same effect as rate < 0.0.

The flush flag will clear any pending data in the pipeline before starting the step operation.

The intermediate flag instructs the pipeline that this step operation is part of a larger step operation.

`format`

the format of amount

`amount`

the amount of data to step

`rate`

Generates a metadata tag event from the given taglist.

The scope of the taglist specifies if the taglist applies to the complete medium or only to this specific stream. As the tag event is a sticky event, elements should merge tags received from upstream with a given scope with their own tags with the same scope and create a new tag event from it.

`taglist`

metadata list. The event will take ownership of the taglist.

Returns

a new Event

Generate a TOC event from the given toc. The purpose of the TOC event is to inform elements that some kind of the TOC was found.

`toc`

Toc structure.

`updated`

whether toc was updated or not.

Returns

a new Event.

Generate a TOC select event with the given uid. The purpose of the TOC select event is to start playback based on the TOC's entry with the given uid.

`uid`

UID in the TOC to start playback from.

Returns

a new Event.

Parses a segment self and copies the Segment into the location given by segment.

`segment`

a pointer to a Segment

Retrieve the accumulated running time offset of the event.

Events passing through GstPads that have a running time offset set via PadExt::set_offset will get their offset adjusted according to the pad's offset.

If the event contains any information that related to the running time, this information will need to be updated before usage with this offset.

Returns

The event's running time offset

MT safe.

Retrieve the sequence number of a event.

Events have ever-incrementing sequence numbers, which may also be set explicitly via Event::set_seqnum. Sequence numbers are typically used to indicate that a event corresponds to some other set of events or messages, for example an EOS event corresponding to a SEEK event. It is considered good practice to make this correspondence when possible, though it is not required.

Note that events and messages share the same sequence number incrementor; two events or messages will never have the same sequence number unless that correspondence was made explicitly.

Returns

The event's sequence number.

MT safe.

Access the structure of the event.

Returns

The structure of the event. The structure is still owned by the event, which means that you should not free it and that the pointer becomes invalid when you free the event.

MT safe.

Checks if self has the given name. This function is usually used to check the name of a custom event.

`name`

name to check

Returns

true if name matches the name of the event structure.

Get the format, minsize, maxsize and async-flag in the buffersize event.

`format`

A pointer to store the format in

`minsize`

A pointer to store the minsize in

`maxsize`

A pointer to store the maxsize in

`async`

A pointer to store the async-flag in

Get the caps from self. The caps remains valid as long as self remains valid.

`caps`

A pointer to the caps

Parse the FLUSH_STOP event and retrieve the reset_time member.

`reset_time`

if time should be reset

Extract timestamp and duration from a new GAP event.

`timestamp`

location where to store the start time (pts) of the gap, or None

`duration`

location where to store the duration of the gap, or None

`group_id`

address of variable where to store the group id

Returns

true if a group id was set on the event and could be parsed, false otherwise.

Get the latency in the latency event.

`latency`

A pointer to store the latency in.

Parses an event containing protection system specific information and stores the results in system_id, data and origin. The data stored in system_id, origin and data are valid until self is released.

`system_id`

pointer to store the UUID string uniquely identifying a content protection system.

`data`

pointer to store a Buffer holding protection system specific information.

`origin`

pointer to store a value that indicates where the protection information carried by self was extracted from.

Get the type, proportion, diff and timestamp in the qos event. See Event::new_qos for more information about the different QoS values.

timestamp will be adjusted for any pad offsets of pads it was passing through.

`type_`

A pointer to store the QoS type in

`proportion`

A pointer to store the proportion in

`diff`

A pointer to store the diff in

`timestamp`

A pointer to store the timestamp in

Parses a seek self and stores the results in the given result locations.

`rate`

result location for the rate

`format`

result location for the stream format

`flags`

result location for the SeekFlags

`start_type`

result location for the SeekType of the start position

`start`

result location for the start position expressed in format

`stop_type`

result location for the SeekType of the stop position

`stop`

result location for the stop position expressed in format

Parses a segment self and stores the result in the given segment location. segment remains valid only until the self is freed. Don't modify the segment and make a copy if you want to modify it or store it for later use.

`segment`

a pointer to a Segment

Extracts the position and format from the segment done message.

`format`

Result location for the format, or None

`position`

Result location for the position, or None

Parse the SELECT_STREAMS event and retrieve the contained streams.

Feature: v1_10

`streams`

the streams

Parse the sink-message event. Unref msg after usage.

`msg`

a pointer to store the Message in.

Parse the step event.

`format`

a pointer to store the format in

`amount`

a pointer to store the amount in

`rate`

a pointer to store the rate in

`flush`

a pointer to store the flush boolean in

`intermediate`

a pointer to store the intermediate boolean in

Parse a stream-start self and extract the Stream from it.

Feature: v1_10

`stream`

adress of variable to store the stream

Retrieve new StreamCollection from STREAM_COLLECTION event self.

Feature: v1_10

`collection`

pointer to store the collection

`flags`

address of variable where to store the stream flags

Parse a stream-group-done self and store the result in the given group_id location.

Feature: v1_10

`group_id`

address of variable to store the group id into

Parse a stream-id self and store the result in the given stream_id location. The string stored in stream_id must not be modified and will remain valid only until self gets freed. Make a copy if you want to modify it or store it for later use.

`stream_id`

pointer to store the stream-id

Parses a tag self and stores the results in the given taglist location. No reference to the taglist will be returned, it remains valid only until the self is freed. Don't modify or free the taglist, make a copy if you want to modify it or store it for later use.

`taglist`

pointer to metadata list

Parse a TOC self and store the results in the given toc and updated locations.

`toc`

pointer to Toc structure.

`updated`

pointer to store TOC updated flag.

Parse a TOC select self and store the results in the given uid location.

`uid`

storage for the selection UID.

Stop a flush operation. This event resets the running-time of the pipeline.

Event to mark the start of a new stream. Sent before any other serialized event and only sent at the start of a new stream, not after flushing seeks.

Caps event. Notify the pad of a new media type.

A new media segment follows in the dataflow. The segment events contains information for clipping buffers and converting buffer timestamps to running-time and stream-time.

A new StreamCollection is available (Since 1.10)

A new set of metadata tags has been found in the stream.

Notification of buffering requirements. Currently not used yet.

An event that sinks turn into a message. Used to send messages that should be emitted in sync with rendering.

Indicates that there is no more data for the stream group ID in the message. Sent before EOS in some instances and should be handled mostly the same. (Since 1.10)

End-Of-Stream. No more data is to be expected to follow without either a STREAM_START event, or a FLUSH_STOP and a SEGMENT event.

An event which indicates that a new table of contents (TOC) was found or updated.

An event which indicates that new or updated encryption information has been found in the stream.

Marks the end of a segment playback.

Marks a gap in the datastream.

A quality message. Used to indicate to upstream elements that the downstream elements should adjust their processing rate.

A request for a new playback position and rate.

Navigation events are usually used for communicating user requests, such as mouse or keyboard movements, to upstream elements.

Notification of new latency adjustment. Sinks will use the latency information to adjust their synchronisation.

A request for stepping through the media. Sinks will usually execute the step operation.

A request for upstream renegotiating caps and reconfiguring.

A request for a new playback position based on TOC entry's UID.

A request to select one or more streams (Since 1.10)

Upstream custom event

Downstream custom event that travels in the data flow.

Custom out-of-band downstream event.

Custom sticky downstream event.

Custom upstream or downstream event. In-band when travelling downstream.

Custom upstream or downstream out-of-band event.

The result of passing data to a pad.

Note that the custom return values should not be exposed outside of the element scope.

Pre-defined custom success code.

Pre-defined custom success code (define your custom success code to this to avoid compiler warnings).

Elements can use values starting from this (and higher) to define custom success codes.

Data passing was ok.

Pad is not linked.

Pad is flushing.

Pad is EOS.

Pad is not negotiated.

Some (fatal) error occurred. Element generating this error should post an error message with more details.

This operation is not supported.

Elements can use values starting from this (and lower) to define custom error codes.

Pre-defined custom error code (define your custom error code to this to avoid compiler warnings).

Pre-defined custom error code.

Standard predefined formats

undefined format

the default format of the pad/element. This can be samples for raw audio, frames/fields for raw video (some, but not all, elements support this; use Format::Time if you don't have a good reason to query for samples/frames)

bytes

time in nanoseconds

buffers (few, if any, elements implement this as of May 2009)

percentage of stream (few, if any, elements implement this as of May 2009)

GhostPads are useful when organizing pipelines with Bin like elements. The idea here is to create hierarchical element graphs. The bin element contains a sub-graph. Now one would like to treat the bin-element like any other Element. This is where GhostPads come into play. A GhostPad acts as a proxy for another pad. Thus the bin can have sink and source ghost-pads that are associated with sink and source pads of the child elements.

If the target pad is known at creation time, GhostPad::new is the function to use to get a ghost-pad. Otherwise one can use GhostPad::new_no_target to create the ghost-pad and use GhostPadExt::set_target to establish the association later on.

Note that GhostPads add overhead to the data processing of a pipeline.

Implements

GhostPadExt, ProxyPadExt, PadExt, GstObjectExt, glib::object::ObjectExt

Trait containing all GhostPad methods.

Implementors

GhostPad

Create a new ghostpad with target as the target. The direction will be taken from the target pad. target must be unlinked.

Will ref the target.

`name`

the name of the new pad, or None to assign a default name

`target`

the pad to ghost.

Returns

a new Pad, or None in case of an error.

Create a new ghostpad with target as the target. The direction will be taken from the target pad. The template used on the ghostpad will be template.

Will ref the target.

`name`

the name of the new pad, or None to assign a default name.

`target`

the pad to ghost.

`templ`

the PadTemplate to use on the ghostpad.

Returns

a new Pad, or None in case of an error.

Create a new ghostpad without a target with the given direction. A target can be set on the ghostpad later with the GhostPadExt::set_target function.

The created ghostpad will not have a padtemplate.

`name`

the name of the new pad, or None to assign a default name.

`dir`

the direction of the ghostpad

Returns

a new Pad, or None in case of an error.

Create a new ghostpad based on templ, without setting a target. The direction will be taken from the templ.

`name`

the name of the new pad, or None to assign a default name

`templ`

the PadTemplate to create the ghostpad from.

Returns

a new Pad, or None in case of an error.

Invoke the default activate mode function of a ghost pad.

`pad`

the Pad to activate or deactivate.

`parent`

the parent of pad or None

`mode`

the requested activation mode

`active`

whether the pad should be active or not.

Returns

true if the operation was successful.

Invoke the default activate mode function of a proxy pad that is owned by a ghost pad.

`pad`

the Pad to activate or deactivate.

`parent`

the parent of pad or None

`mode`

the requested activation mode

`active`

whether the pad should be active or not.

Returns

true if the operation was successful.

Finish initialization of a newly allocated ghost pad.

This function is most useful in language bindings and when subclassing GhostPad; plugin and application developers normally will not call this function. Call this function directly after a call to g_object_new (GST_TYPE_GHOST_PAD, "direction", dir, ..., NULL).

Returns

true if the construction succeeds, false otherwise.

Get the target pad of self. Unref target pad after usage.

Returns

the target Pad, can be None if the ghostpad has no target set. Unref target pad after usage.

Set the new target of the ghostpad self. Any existing target is unlinked and links to the new target are established. if newtarget is None the target will be cleared.

`newtarget`

the new pad target

Returns

true if the new target could be set. This function can return false when the internal pads could not be linked.

Library errors are for errors from the library being used by elements (initializing, finalizing, settings, ...)

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

do not use this except as a placeholder for deciding where to go while developing code.

used when the library could not be opened.

used when the library could not be closed.

used when the library doesn't accept settings.

used when the library generated an encoding error.

the number of library error types.

Messages are implemented as a subclass of MiniObject with a generic Structure as the content. This allows for writing custom messages without requiring an API change while allowing a wide range of different types of messages.

Messages are posted by objects in the pipeline and are passed to the application using the Bus.

The basic use pattern of posting a message on a Bus is as follows:

  gst_bus_post (bus, gst_message_new_eos());

MT safe.

Create a clock provide message. This message is posted whenever an element is ready to provide a clock or lost its ability to provide a clock (maybe because it paused or became EOS).

`details`

(allow-none): A GstStructure with details

Returns

the new error message.

This message is posted when an element has a new local Context.

`src`

The object originating the message.

`context`

the context

Returns

The new have-context message.

MT safe.

Create a new info message. The message will make copies of error and debug.

`src`

The object originating the message.

`error`

The GError for this message.

`debug`

A debugging string.

Returns

the new info message.

MT safe.

Create a new info message. The message will make copies of error and debug.

Feature: v1_10

`src`

The object originating the message.

`error`

The GError for this message.

`debug`

A debugging string.

`details`

(allow-none): A GstStructure with details

Returns

`duration`

the duration of the buffer that generated the message

Returns

The new qos message.

MT safe.

Creates a new redirect message and adds a new entry to it. Redirect messages are posted when an element detects that the actual data has to be retrieved from a different location. This is useful if such a redirection cannot be handled inside a source element, for example when HTTP 302/303 redirects return a non-HTTP URL.

The redirect message can hold multiple entries. The first one is added when the redirect message is created, with the given location, tag_list, entry_struct arguments. Use Message::add_redirect_entry to add more entries.

Each entry has a location, a tag list, and a structure. All of these are optional. The tag list and structure are useful for additional metadata, such as bitrate statistics for the given location.

By default, message recipients should treat entries in the order they are stored. The recipient should therefore try entry 0 first, and if this entry is not acceptable or working, try entry 1 etc. Senders must make sure that they add entries in this order. However, recipients are free to ignore the order and pick an entry that is "best" for them. One example would be a recipient that scans the entries for the one with the highest bitrate tag.

The specified location string is copied. However, ownership over the tag list and structure are transferred to the message.

Feature: v1_10

`src`

The Object whose property changed (may or may not be a Element)

`location`

location string for the new entry

`tag_list`

tag list for the new entry

`entry_struct`

structure for the new entry

The position of the segment being done

Returns

the new segment done message.

MT safe.

The object originating the message

Returns

the new state dirty message.

MT safe.

This message is posted by elements when they complete a part, when intermediate set to true, or a complete step operation.

duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped amount of media in format format.

`src`

The object originating the message.

`format`

the format of amount

`amount`

the amount of stepped data

`rate`

the rate of the stepped amount

`flush`

is this an flushing step

`intermediate`

is this an intermediate step

`duration`

the duration of the data

`eos`

the step caused EOS

Returns

the new step_done message.

MT safe.

This message is posted by elements when they accept or activate a new step event for amount in format.

active is set to false when the element accepted the new step event and has queued it for execution in the streaming threads.

active is set to true when the element has activated the step operation and is now ready to start executing the step in the streaming thread. After this message is emitted, the application can queue a new step operation in the element.

`src`

The object originating the message.

`active`

if the step is active or queued

`format`

the format of amount

`amount`

the amount of stepped data

`rate`

the rate of the stepped amount

`flush`

`src`

The object originating the message.

`type_`

The stream status type.

`owner`

the owner element of src.

Returns

the new stream status message.

Create a new warning message. The message will make copies of error and debug.

Feature: v1_10

`src`

The object originating the message.

`error`

The GError for this message.

`debug`

A debugging string.

`details`

(allow-none): A GstStructure with details

Returns

the new warning message.

Creates and appends a new entry.

The specified location string is copied. However, ownership over the tag list and structure are transferred to the message.

Feature: v1_10

`location`

location string for the new entry

`tag_list`

tag list for the new entry

`entry_struct`

structure for the new entry

Feature: v1_10

Returns

the number of entries stored in the message

Retrieve the sequence number of a message.

Messages have ever-incrementing sequence numbers, which may also be set explicitly via Message::set_seqnum. Sequence numbers are typically used to indicate that a message corresponds to some other set of messages or events, for example a SEGMENT_DONE message corresponding to a SEEK event. It is considered good practice to make this correspondence when possible, though it is not required.

Note that events and messages share the same sequence number incrementor; two events or messages will never have the same sequence number unless that correspondence was made explicitly.

Returns

The message's sequence number.

MT safe.

Extracts the object managing the streaming thread from self.

Returns

a GValue containing the object that manages the streaming thread. This object is usually of type GstTask but other types can be added in the future. The object remains valid as long as self is valid.

Access the structure of the message.

Returns

The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message.

MT safe.

Checks if self has the given name. This function is usually used to check the name of a custom message.

`name`

name to check

Returns

true if name matches the name of the message structure.

Extract the running_time from the async_done message.

MT safe.

`running_time`

Result location for the running_time or None

Extracts the buffering percent from the GstMessage. see also Message::new_buffering.

MT safe.

`percent`

Return location for the percent.

Extracts the buffering stats values from self.

`mode`

a buffering mode, or None

`avg_in`

the average input rate, or None

`avg_out`

the average output rate, or None

`buffering_left`

amount of buffering time left in milliseconds, or None

Extracts the lost clock from the GstMessage. The clock object returned remains valid until the message is freed.

MT safe.

`clock`

a pointer to hold the lost clock

Extracts the clock and ready flag from the GstMessage. The clock object returned remains valid until the message is freed.

MT safe.

`clock`

a pointer to hold a clock object, or None

`ready`

a pointer to hold the ready flag, or None

Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message.

`context_type`

the context type, or None

Returns

a gboolean indicating if the parsing succeeded.

Parses a device-added message. The device-added message is produced by DeviceProvider or a DeviceMonitor. It announces the appearance of monitored devices.

`device`

A location where to store a pointer to the new Device, or None

Parses a device-removed message. The device-removed message is produced by DeviceProvider or a DeviceMonitor. It announces the disappearance of monitored devices.

`device`

A location where to store a pointer to the removed Device, or None

Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done.

Typical usage of this function might be:

  ...
  switch (GST_MESSAGE_TYPE (msg)) {
    case GST_MESSAGE_ERROR: {
      GError *err = NULL;
      gchar *dbg_info = NULL;

      gst_message_parse_error (msg, &amp;err, &amp;dbg_info);
      g_printerr ("ERROR from element %s: %s\n",
          GST_OBJECT_NAME (msg->src), err->message);
      g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none");
      g_error_free (err);
      g_free (dbg_info);
      break;
    }
    ...
  }
  ...

MT safe.

`gerror`

location for the GError

`debug`

location for the debug message, or None

Returns the optional details structure, may be NULL if none. The returned structure must not be freed.

`gerror`

location for the GError

`debug`

location for the debug message, or None

Returns the optional details structure, may be NULL if none The returned structure must not be freed.

Feature: v1_10

`structure`

A pointer to the returned details structure

Extracts the new clock from the GstMessage. The clock object returned remains valid until the message is freed.

MT safe.

`clock`

a pointer to hold the selected new clock

Parses the progress type_, code and text.

`type_`

location for the type

`code`

location for the code

`text`

location for the text

Parses a property-notify message. These will be posted on the bus only when set up with Element::add_property_notify_watch or Element::add_property_deep_notify_watch.

Feature: v1_10

`object`

location where to store a pointer to the object whose property got changed, or None

`property_name`

return location for the name of the property that got changed, or None

`property_value`

return location for the new value of the property that got changed, or None. This will only be set if the property notify watch was told to include the value when it was set up

Extract the timestamps and live status from the QoS message.

The returned values give the running_time, stream_time, timestamp and duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown values.

MT safe.

`live`

if the message was generated by a live element

`running_time`

the running time of the buffer that generated the message

`stream_time`

the stream time of the buffer that generated the message

`timestamp`

the timestamps of the buffer that generated the message

`duration`

the duration of the buffer that generated the message

Extract the QoS stats representing the history of the current continuous pipeline playback period.

When format is Format::Undefined both dropped and processed are invalid. Values of -1 for either processed or dropped mean unknown values.

MT safe.

`format`

Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples).

`processed`

Total number of units correctly processed since the last state change to READY or a flushing operation.

`dropped`

Total number of units dropped since the last state change to READY or a flushing operation.

Extract the QoS values that have been calculated/analysed from the QoS data

MT safe.

`jitter`

The difference of the running-time against the deadline.

`proportion`

Long term prediction of the ideal rate relative to normal rate to get optimal quality.

`quality`

An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000.

Parses the location and/or structure from the entry with the given index. The index must be between 0 and Message::get_num_redirect_entries - 1. Returned pointers are valid for as long as this message exists.

Feature: v1_10

`entry_index`

index of the entry to parse

`location`

return location for the pointer to the entry's location string, or None

`tag_list`

return location for the pointer to the entry's tag list, or None

`entry_struct`

return location for the pointer to the entry's structure, or None

Extract the requested state from the request_state message.

MT safe.

`state`

Result location for the requested state or None

Extract the running-time from the RESET_TIME message.

the pending (target) state, or None

Extract the values the step_done message.

MT safe.

`format`

result location for the format

`amount`

result location for the amount

`rate`

The owner element of the message source

`busy`

a pointer to hold whether the change is in progress or has been completed

Extracts the tag list from the GstMessage. The tag list returned in the output argument is a copy; the caller must free it when done.

Typical usage of this function might be:

  ...
  switch (GST_MESSAGE_TYPE (msg)) {
    case GST_MESSAGE_TAG: {
      GstTagList *tags = NULL;

      gst_message_parse_tag (msg, &amp;tags);
      g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src));
      handle_tags (tags);
      gst_tag_list_unref (tags);
      break;
    }
    ...
  }
  ...

A pointer to the returned details structure

Configures the buffering stats values in self.

`mode`

a buffering mode

`avg_in`

the average input rate

`avg_out`

the average output rate

`buffering_left`

amount of buffering time left in milliseconds

Sets the group id on the stream-start message.

MT safe.

`group_id`

the group id

Set the QoS stats representing the history of the current continuous pipeline playback period.

When format is Format::Undefined both dropped and processed are invalid. Values of -1 for either processed or dropped mean unknown values.

MT safe.

`format`

Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples).

`processed`

Total number of units correctly processed since the last state change to READY or a flushing operation.

`dropped`

Total number of units dropped since the last state change to READY or a flushing operation.

Set the QoS values that have been calculated/analysed from the QoS data

MT safe.

`jitter`

The difference of the running-time against the deadline.

`proportion`

Long term prediction of the ideal rate relative to normal rate to get optimal quality.

`quality`

An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000.

Set the sequence number of a message.

This function might be called by the creator of a message to indicate that the message relates to other messages or events. See Message::get_seqnum for more information.

MT safe.

`seqnum`

A sequence number.

Configures the object handling the streaming thread. This is usually a GstTask object but other objects might be added in the future.

`object`

the object controlling the streaming

Adds the stream to the self.

Feature: v1_10

`stream`

a Stream to add to self

Returns the number of streams contained in the self.

Feature: v1_10

Returns

The number of streams contained within.

Retrieves the Stream with index index from the self.

Feature: v1_10

`idx`

Index of the stream to retrieve

Returns

A Stream

Get a writable version of the structure.

Feature: v1_14

Returns

The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message. This function checks if self is writable and will never return None.

MT safe.

Object provides a root for the object hierarchy tree filed in by the GStreamer library. It is currently a thin wrapper on top of gobject::InitiallyUnowned. It is an abstract class that is not very usable on its own.

Object gives us basic refcounting, parenting functionality and locking. Most of the functions are just extended for special GStreamer needs and can be found under the same name in the base class of Object which is gobject::Object (e.g. gobject::ObjectExt::ref becomes GstObjectExt::ref).

Since Object derives from gobject::InitiallyUnowned, it also inherits the floating reference. Be aware that functions such as BinExt::add and ElementExt::add_pad take ownership of the floating reference.

In contrast to gobject::Object instances, Object adds a name property. The functions GstObjectExt::set_name and GstObjectExt::get_name are used to set/get the name of the object.

controlled properties

Controlled properties offers a lightweight way to adjust gobject properties over stream-time. It works by using time-stamped value pairs that are queued for element-properties. At run-time the elements continuously pull value changes for the current stream-time.

What needs to be changed in a Element? Very little - it is just two steps to make a plugin controllable!

mark gobject-properties paramspecs that make sense to be controlled, by GST_PARAM_CONTROLLABLE.
when processing data (get, chain, loop function) at the beginning call gst_object_sync_values(element,timestamp). This will make the controller update all GObject properties that are under its control with the current values based on the timestamp.

What needs to be done in applications? Again it's not a lot to change.

create a ControlSource. csource = gst_interpolation_control_source_new (); g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
Attach the ControlSource on the controller to a property. gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
Set the control values gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2);
start your pipeline

Implements

GstObjectExt, glib::object::ObjectExt

Trait containing all Object methods.

Implementors

BufferPool, Bus, Clock, DeviceMonitor, DeviceProvider, Device, Element, Object, PadTemplate, Pad, PluginFeature, Plugin, Registry, StreamCollection, Stream

Checks to see if there is any object named name in list. This function does not do any locking of any kind. You might want to protect the provided list with the lock of the owner of the list. This function will lock each Object in the list to compare the name, so be careful when passing a list with a locked object.

`list`

a list of Object to check through

`name`

the name to search for

Returns

true if a Object named name does not appear in list, false if it does.

MT safe. Grabs and releases the LOCK of each object in the list.

A default deep_notify signal callback for an object. The user data should contain a pointer to an array of strings that should be excluded from the notify. The default handler will print the new value of the property using g_print.

MT safe. This function grabs and releases object's LOCK for getting its path string.

`object`

the gobject::Object that signalled the notify.

`orig`

a Object that initiated the notify.

`pspec`

a gobject::ParamSpec of the property.

`excluded_props`

a set of user-specified properties to exclude or None to show all changes.

Increase the reference count of object, and possibly remove the floating reference, if object has a floating reference.

In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

For more background on "floating references" please see the gobject::Object documentation.

`object`

a Object to sink

Atomically modifies a pointer to point to a new object. The reference count of oldobj is decreased and the reference count of newobj is increased.

Either newobj and the value pointed to by oldobj may be None.

`oldobj`

pointer to a place of a Object to replace

`newobj`

a new Object

Returns

true if newobj was different from oldobj

Attach the ControlBinding to the object. If there already was a ControlBinding for this property it will be replaced.

The object's reference count will be incremented, and any floating reference will be removed (see Object::ref_sink)

`binding`

the ControlBinding that should be used

Returns

false if the given binding has not been setup for this object or has been setup for a non suitable property, true otherwise.

A default error function that uses g_printerr to display the error message and the optional debug sting..

The default handler will simply print the error string using g_print.

`error`

the GError.

`debug`

an additional debug information string, or None

Gets the corresponding ControlBinding for the property. This should be unreferenced again after use.

`property_name`

name of the property

Returns

the ControlBinding for property_name or None if the property is not controlled.

Obtain the control-rate for this self. Audio processing Element objects will use this rate to sub-divide their processing loop and call GstObjectExt::sync_values inbetween. The length of the processing segment should be up to control-rate nanoseconds.

If the self is not under property control, this will return GST_CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing.

The control-rate is not expected to change if the element is in State::Paused or State::Playing.

Returns

the control rate in nanoseconds

Gets a number of GValues for the given controlled property starting at the requested time. The array values need to hold enough space for n_values of gobject::Value.

This function is useful if one wants to e.g. draw a graph of the control curve or apply a control curve sample by sample.

`property_name`

parent of self, this can be None if self has no parent. unref after usage.

MT safe. Grabs and releases self's LOCK.

Generates a string describing the path of self in the object hierarchy. Only useful (or used) for debugging.

Free-function: g_free

Returns

a string describing the path of self. You must g_free the string after usage.

MT safe. Grabs and releases the Object's LOCK for all objects in the hierarchy.

Gets the value for the given controlled property at the requested time.

`property_name`

the name of the property to get

`timestamp`

the time the control-change should be read from

Returns

the GValue of the property at the given time, or None if the property isn't controlled.

Gets a number of values for the given controlled property starting at the requested time. The array values need to hold enough space for n_values of the same type as the objects property's type.

This function is useful if one wants to e.g. draw a graph of the control curve or apply a control curve sample by sample.

The values are unboxed and ready to be used. The similar function GstObjectExt::get_g_value_array returns the array as GValues and is better suites for bindings.

`property_name`

the name of the property to get

`timestamp`

the time that should be processed

`interval`

the time spacing between subsequent values

`n_values`

the number of values

`values`

array to put control-values in

Returns

true if the given array could be filled, false otherwise

Check if the self has active controlled properties.

Returns

true if the object has active controlled properties

Check if self has an ancestor ancestor somewhere up in the hierarchy. One can e.g. check if a Element is inside a Pipeline.

Deprecated

Use GstObjectExt::has_as_ancestor instead.

MT safe. Grabs and releases self's locks.

`ancestor`

a Object to check as ancestor

Returns

true if ancestor is an ancestor of self.

Check if self has an ancestor ancestor somewhere up in the hierarchy. One can e.g. check if a Element is inside a Pipeline.

`ancestor`

a Object to check as ancestor

Returns

true if ancestor is an ancestor of self.

MT safe. Grabs and releases self's locks.

Check if parent is the parent of self. E.g. a Element can check if it owns a given Pad.

`parent`

a Object to check as parent

Returns

false if either self or parent is None. true if parent is the parent of self. Otherwise false.

MT safe. Grabs and releases self's locks.

Increments the reference count on self. This function does not take the lock on self because it relies on atomic refcounting.

This object returns the input parameter to ease writing constructs like : result = gst_object_ref (object->parent);

Returns

A pointer to self

Removes the corresponding ControlBinding. If it was the last ref of the binding, it will be disposed.

`binding`

the binding

Returns

true if the binding could be removed.

This function is used to disable the control bindings on a property for some time, i.e. GstObjectExt::sync_values will do nothing for the property.

`property_name`

property to disable

`disabled`

boolean that specifies whether to disable the controller or not.

This function is used to disable all controlled properties of the self for some time, i.e. GstObjectExt::sync_values will do nothing.

`disabled`

boolean that specifies whether to disable the controller or not.

Change the control-rate for this self. Audio processing Element objects will use this rate to sub-divide their processing loop and call GstObjectExt::sync_values inbetween. The length of the processing segment should be up to control-rate nanoseconds.

The control-rate should not change if the element is in State::Paused or State::Playing.

`control_rate`

`timestamp`

the time that should be processed

Returns

true if the controller values could be applied to the object properties, false otherwise

Clear the parent of self, removing the associated reference. This function decreases the refcount of self.

MT safe. Grabs and releases self's lock.

Decrements the reference count on self. If reference count hits zero, destroy self. This function does not take the lock on self as it relies on atomic refcounting.

The unref method should never be called with the LOCK held since this might deadlock the dispose function.

The deep notify signal is used to be notified of property changes. It is typically attached to the toplevel bin to receive notifications from all the elements contained in that bin.

`prop_object`

the object that originated the signal

`prop`

the property that changed

The parent of the object. Please note, that when changing the 'parent' property, we don't emit gobject::Object::notify and Object::deep-notify signals due to locking issues. In some cases one can use Bin::element-added or Bin::element-removed signals on the parent to achieve a similar effect.

A Element is linked to other elements via "pads", which are extremely light-weight generic link points.

Pads have a PadDirection, source pads produce data, sink pads consume data.

Pads are typically created from a PadTemplate with Pad::new_from_template and are then added to a Element. This usually happens when the element is created but it can also happen dynamically based on the data that the element is processing or based on the pads that the application requests.

Pads without pad templates can be created with Pad::new, which takes a direction and a name as an argument. If the name is None, then a guaranteed unique name will be assigned to it.

A Element creating a pad will typically use the various gst_pad_set_*_function calls to register callbacks for events, queries or dataflow on the pads.

gst_pad_get_parent will retrieve the Element that owns the pad.

After two pads are retrieved from an element by ElementExt::get_static_pad, the pads can be linked with PadExt::link. (For quick links, you can also use ElementExt::link, which will make the obvious link for you if it's straightforward.). Pads can be unlinked again with PadExt::unlink. PadExt::get_peer can be used to check what the pad is linked to.

Before dataflow is possible on the pads, they need to be activated with PadExt::set_active.

Pad::query and Pad::peer_query can be used to query various properties of the pad and the stream.

To send a Event on a pad, use Pad::send_event and Pad::push_event. Some events will be sticky on the pad, meaning that after they pass on the pad they can be queried later with PadExt::get_sticky_event and PadExt::sticky_events_foreach. PadExt::get_current_caps and PadExt::has_current_caps are convenience functions to query the current sticky CAPS event on a pad.

GstElements will use Pad::push and Pad::pull_range to push out or pull in a buffer.

The dataflow, events and queries that happen on a pad can be monitored with probes that can be installed with PadExt::add_probe. PadExt::is_blocked can be used to check if a block probe is installed on the pad. PadExt::is_blocking checks if the blocking probe is currently blocking the pad. Pad::remove_probe is used to remove a previously installed probe and unblock blocking probes if any.

Pad have an offset that can be retrieved with PadExt::get_offset. This offset will be applied to the running_time of all data passing over the pad. PadExt::set_offset can be used to change the offset.

Convenience functions exist to start, pause and stop the task on a pad with PadExt::start_task, PadExt::pause_task and PadExt::stop_task respectively.

Implements

PadExt, GstObjectExt, glib::object::ObjectExt

Trait containing all Pad methods.

Implementors

Pad, ProxyPad

Creates a new pad with the given name in the given direction. If name is None, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name.

`name`

the name of the new pad.

`direction`

the PadDirection of the pad.

Returns

Activates or deactivates the given pad in mode via dispatching to the pad's activatemodefunc. For use from within pad activation functions only.

If you don't know what this is, you probably don't want to call it.

`mode`

the requested activation mode

`active`

whether or not the pad should be active.

Returns

true if the operation was successful.

MT safe.

Be notified of different states of pads. The provided callback is called for every state that matches mask.

Probes are called in groups: First GST_PAD_PROBE_TYPE_BLOCK probes are called, then others, then finally GST_PAD_PROBE_TYPE_IDLE. The only exception here are GST_PAD_PROBE_TYPE_IDLE probes that are called immediately if the pad is already idle while calling PadExt::add_probe. In each of the groups, probes are called in the order in which they were added.

`mask`

the probe mask

`callback`

GstPadProbeCallback that will be called with notifications of the pad state

`user_data`

user data passed to the callback

`destroy_data`

GDestroyNotify for user_data

Returns

an id or 0 if no probe is pending. The id can be used to remove the probe with Pad::remove_probe. When using GST_PAD_PROBE_TYPE_IDLE it can happen that the probe can be run immediately and if the probe returns GST_PAD_PROBE_REMOVE this functions returns 0.

MT safe.

Checks if the source pad and the sink pad are compatible so they can be linked.

`sinkpad`

the sink Pad.

Returns

true if the pads can be linked.

Chain a buffer to self.

The function returns FlowReturn::Flushing if the pad was flushing.

If the buffer type is not acceptable for self (as negotiated with a preceding GST_EVENT_CAPS event), this function returns FlowReturn::NotNegotiated.

The function proceeds calling the chain function installed on self (see gst_pad_set_chain_function) and the return value of that function is returned to the caller. FlowReturn::NotSupported is returned if self has no chain function.

In all cases, success or failure, the caller loses its reference to buffer after calling this function.

`buffer`

the Buffer to send, return GST_FLOW_ERROR if not.

Returns

a FlowReturn from the pad.

MT safe.

Chain a bufferlist to self.

The function returns FlowReturn::Flushing if the pad was flushing.

If self was not negotiated properly with a CAPS event, this function returns FlowReturn::NotNegotiated.

The function proceeds calling the chainlist function installed on self (see gst_pad_set_chain_list_function) and the return value of that function is returned to the caller. FlowReturn::NotSupported is returned if self has no chainlist function.

In all cases, success or failure, the caller loses its reference to list after calling this function.

MT safe.

`list`

the BufferList to send, return GST_FLOW_ERROR if not.

Returns

a FlowReturn from the pad.

Check and clear the PadFlags::NeedReconfigure flag on self and return true if the flag was set.

Returns

true is the GST_PAD_FLAG_NEED_RECONFIGURE flag was set on self.

The stream-id

`var_args`

parameters for the stream_id format string

Returns

A stream-id for self. g_free after usage.

Invokes the default event handler for the given pad.

The EOS event will pause the task associated with self before it is forwarded to all internally linked pads,

the Caps of this pad template. Unref after usage.

Gets the parent of self, cast to a Element. If a self has no parent or its parent is not an element, return None.

Returns

the parent of the pad. The caller has a reference on the parent, so unref when you're finished with it.

MT safe.

Gets the peer of self. This function refs the peer pad so you need to unref it after use.

Returns

the peer Pad. Unref after usage.

MT safe.

When self is flushing this function returns FlowReturn::Flushing immediately and buffer is None.

Calls the getrange function of self, see GstPadGetRangeFunction for a description of a getrange function. If self has no getrange function installed (see gst_pad_set_getrange_function) this function returns FlowReturn::NotSupported.

If buffer points to a variable holding None, a valid new Buffer will be placed in buffer when this function returns FlowReturn::Ok. The new buffer must be freed with gst_buffer_unref after usage.

When buffer points to a variable that points to a valid Buffer, the buffer will be filled with the result data when this function returns FlowReturn::Ok. If the provided buffer is larger than size, only size bytes will be filled in the result buffer and its size will be updated accordingly.

Note that less than size bytes can be returned in buffer when, for example, an EOS condition is near or when buffer is not large enough to hold size bytes. The caller should check the result buffer size to get the result size.

When this function returns any other result value than FlowReturn::Ok, buffer will be unchanged.

This is a lowlevel function. Usually Pad::pull_range is used.

`offset`

The start offset of the buffer

`size`

The length of the buffer

`buffer`

a pointer to hold the Buffer, returns FlowReturn::Error if None.

Returns

a FlowReturn from the pad.

MT safe.

Returns a new reference of the sticky event of type event_type from the event.

`event_type`

Get self task state. If no task is currently set, TaskState::Stopped is returned.

Feature: v1_12

Returns

The current state of self's task.

Check if self has caps set on it with a EventType::Caps event.

true if the pad is linked, false otherwise.

MT safe.

Gets an iterator for the pads to which the given pad is linked to inside of the parent element.

Each Pad element yielded by the iterator will have its refcount increased, so unref after use.

Free-function: gst_iterator_free

Returns

a new Iterator of Pad or None when the pad does not have an iterator function configured. Use Iterator::free after usage.

Iterate the list of pads to which the given pad is linked to inside of the parent element. This is the default handler, and thus returns an iterator of all of the pads inside the parent element with opposite direction.

The caller must free this iterator after use with Iterator::free.

`parent`

the parent of self or None

Returns

a Iterator of Pad, or None if self has no parent. Unref each returned pad with GstObjectExt::unref.

Links the source pad and the sink pad.

`sinkpad`

the sink Pad to link.

Returns

A result code indicating if the connection worked or what went wrong.

MT Safe.

Links the source pad and the sink pad.

This variant of PadExt::link provides a more granular control on the checks being done when linking. While providing some considerable speedups the caller of this method must be aware that wrong usage of those flags can cause severe issues. Refer to the documentation of PadLinkCheck for more information.

MT Safe.

`sinkpad`

the sink Pad to link.

`flags`

the checks to validate when linking

Returns

A result code indicating if the connection worked or what went wrong.

Links self to sink, creating any GhostPad's in between as necessary.

This is a convenience function to save having to create and add intermediate GhostPad's as required for linking across Bin boundaries.

If self or sink pads don't have parent elements or do not share a common ancestor, the link will fail.

Feature: v1_10

`sink`

a Pad

Returns

whether the link succeeded.

Links self to sink, creating any GhostPad's in between as necessary.

This is a convenience function to save having to create and add intermediate GhostPad's as required for linking across Bin boundaries.

If self or sink pads don't have parent elements or do not share a common ancestor, the link will fail.

Calling PadExt::link_maybe_ghosting_full with flags == PadLinkCheck::Default is the recommended way of linking pads with safety checks applied.

Feature: v1_10

`sink`

a Pad

`flags`

some PadLinkCheck flags

Returns

whether the link succeeded.

Mark a pad for needing reconfiguration. The next call to PadExt::check_reconfigure will return true after this call.

Check the PadFlags::NeedReconfigure flag on self and return true if the flag was set.

Returns

true is the GST_PAD_FLAG_NEED_RECONFIGURE flag is set on self.

true if query could be executed

Pulls a buffer from the peer pad or fills up a provided buffer.

This function will first trigger the pad block signal if it was installed.

When self is not linked FlowReturn::NotLinked is returned else this function returns the result of Pad::get_range on the peer pad. See Pad::get_range for a list of return values and for the semantics of the arguments of this function.

When buffer points to a variable that points to a valid Buffer, the buffer will be filled with the result data when this function returns FlowReturn::Ok. When this function returns any other result value, buffer will be unchanged. If the provided buffer is larger than size, only size bytes will be filled in the result buffer and its size will be updated accordingly.

`offset`

`query`

the Query to perform.

Returns

true if the query could be performed.

Check if the given pad accepts the caps.

`caps`

a Caps to check on the pad

Returns

true if the pad can accept the caps.

Gets the capabilities this pad can produce or consume. Note that this method doesn't necessarily return the caps set by sending a Event::new_caps - use PadExt::get_current_caps for that instead. gst_pad_query_caps returns all possible caps a pad can operate with, using the pad's CAPS query function, If the query fails, this function will return filter, if not None, otherwise ANY.

When called on sinkpads filter contains the caps that upstream could produce in the order preferred by upstream. When called on srcpads filter contains the caps accepted by downstream in the preferred order. filter might be None but if it is not None the returned caps will be a subset of filter.

Note that this function does not return writable Caps, use gst_caps_make_writable before modifying the caps.

`filter`

suggested Caps, or None

Returns

the caps of the pad with incremented ref-count.

Queries a pad to convert src_val in src_format to dest_format.

`src_format`

a Format to convert from.

`src_val`

a value to convert.

`dest_format`

the Format to convert to.

`dest_val`

a pointer to the result.

Returns

true if the query could be performed.

Remove the probe with id from self.

MT safe.

`id`

the probe id to remove

Sends the event to the pad. This function can be used by applications to send events in the pipeline.

If self is a source pad, event should be an upstream event. If self is a sink pad, event should be a downstream event. For example, you would not send a EventType::Eos on a src pad; EOS events only propagate downstream. Furthermore, some downstream events have to be serialized with data flow, like EOS, while some can travel out-of-band, like EventType::FlushStart. If the event needs to be serialized with data flow, this function will take the pad's stream lock while calling its event function.

To find out whether an event type is upstream, downstream, or downstream and serialized, see EventTypeFlags, EventType::get_flags, GST_EVENT_IS_UPSTREAM, GST_EVENT_IS_DOWNSTREAM, and GST_EVENT_IS_SERIALIZED. Note that in practice that an application or plugin doesn't need to bother itself with this information; the core handles all necessary locks and checks.

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.

`event`

the Event to send to the pad.

Returns

true if the event was handled.

Sets the given activate function for self. The activate function will dispatch to PadExt::activate_mode to perform the actual activation. Only makes sense to set on sink pads.

Call this function if your sink pad can start a pull-based task.

`activate`

the GstPadActivateFunction to set.

`user_data`

user_data passed to notify

`notify`

notify called when activate will not be used anymore.

Sets the given activate_mode function for the pad. An activate_mode function prepares the element for data passing.

`activatemode`

the GstPadActivateModeFunction to set.

`user_data`

user_data passed to notify

`notify`

notify called when activatemode will not be used anymore.

Activates or deactivates the given pad. Normally called from within core state change functions.

If active, makes sure the pad is active. If it is already active, either in push or pull mode, just return. Otherwise dispatches to the pad's activate function to perform the actual activation.

If not active, calls PadExt::activate_mode with the pad's current mode and a false argument.

`active`

whether or not the pad should be active.

Returns

true if the operation was successful.

MT safe.

Sets the given chain function for the pad. The chain function is called to process a Buffer input buffer. see GstPadChainFunction for more details.

`chain`

the GstPadChainFunction to set.

`user_data`

user_data passed to notify

`notify`

notify called when chain will not be used anymore.

Sets the given chain list function for the pad. The chainlist function is called to process a BufferList input buffer list. See GstPadChainListFunction for more details.

`chainlist`

the GstPadChainListFunction to set.

`user_data`

user_data passed to notify

`notify`

notify called when chainlist will not be used anymore.

Set the given private data gpointer on the pad. This function can only be used by the element that owns the pad. No locking is performed in this function.

`priv_`

The private data to attach to the pad.

Sets the given event handler for the pad.

`event`

the GstPadEventFullFunction to set.

`user_data`

user_data passed to notify

`notify`

notify called when event will not be used anymore.

Sets the given event handler for the pad.

`event`

the GstPadEventFunction to set.

`user_data`

user_data passed to notify

`notify`

notify called when event will not be used anymore.

Sets the given getrange function for the pad. The getrange function is called to produce a new Buffer to start the processing pipeline. see GstPadGetRangeFunction for a description of the getrange function.

`get`

the GstPadGetRangeFunction to set.

`user_data`

Sets the given unlink function for the pad. It will be called when the pad is unlinked.

`unlink`

the GstPadUnlinkFunction to set.

`user_data`

user_data passed to notify

`notify`

notify called when unlink will not be used anymore.

Starts a task that repeatedly calls func with user_data. This function is mostly used in pad activation functions to start the dataflow. The GST_PAD_STREAM_LOCK of self will automatically be acquired before func is called.

`func`

the task function to call

`user_data`

user data passed to the task function

`notify`

called when user_data is no longer referenced

Returns

a true if the task could be started.

Iterates all sticky events on self and calls foreach_func for every event. If foreach_func returns false the iteration is immediately stopped.

`foreach_func`

the GstPadStickyEventsForeachFunction that should be called for every event.

`user_data`

the optional user data.

Stop the task of self. This function will also make sure that the function executed by the task will effectively stop if not called from the GstTaskFunction.

This function will deadlock if called from the GstTaskFunction of the task. Use Task::pause instead.

Regardless of whether the pad has a task, the stream lock is acquired and released so as to ensure that streaming through this pad has finished.

Returns

a true if the task could be stopped or false on error.

Store the sticky event on self

`event`

a Event

Returns

FlowReturn::Ok on success, FlowReturn::Flushing when the pad was flushing or FlowReturn::Eos when the pad was EOS.

Unlinks the source pad from the sink pad. Will emit the Pad::unlinked signal on both pads.

`sinkpad`

the sink Pad to unlink.

Returns

true if the pads were unlinked. This function returns false if the pads were not linked together.

MT safe.

A helper function you can use that sets the FIXED_CAPS flag This way the default CAPS query will always return the negotiated caps or in case the pad is not negotiated, the padtemplate caps.

The negotiated caps are the caps of the last CAPS event that passed on the pad. Use this function on a pad that, once it negotiated to a CAPS, cannot be renegotiated to something else.

Signals that a pad has been linked to the peer pad.

`peer`

the peer pad that has been connected

Signals that a pad has been unlinked from the peer pad.

`peer`

the peer pad that has been disconnected

The offset that will be applied to the running time of the pad.

The direction of a pad.

direction is unknown.

the pad is a source pad.

the pad is a sink pad.

Result values from gst_pad_link and friends.

link succeeded

pads have no common grandparent

pad was already linked

pads have wrong direction

pads do not have common format

pads cannot cooperate in scheduling

refused for some reason

The status of a GstPad. After activating a pad, which usually happens when the parent element goes from READY to PAUSED, the GstPadMode defines if the pad operates in push or pull mode.

Pad will not handle dataflow

Pad handles dataflow in downstream push mode

Pad handles dataflow in upstream pull mode

Indicates when this pad will become available.

the pad is always available

the pad will become available depending on the media stream

the pad is only available on request with ElementExt::request_pad.

Different return values for the GstPadProbeCallback.

drop data in data probes. For push mode this means that the data item is not sent downstream. For pull mode, it means that the data item is not passed upstream. In both cases, no other probes are called for this item and FlowReturn::Ok or true is returned to the caller.

normal probe return value. This leaves the probe in place, and defers decisions about dropping or passing data to other probes, if any. If there are no other probes, the default behaviour for the probe type applies ('block' for blocking probes, and 'pass' for non-blocking probes).

remove this probe.

pass the data item in the block probe and block on the next item.

Data has been handled in the probe and will not be forwarded further. For events and buffers this is the same behaviour as PadProbeReturn::Drop (except that in this case you need to unref the buffer or event yourself). For queries it will also return true to the caller. The probe can also modify the FlowReturn value by using the GST_PAD_PROBE_INFO_FLOW_RETURN() accessor. Note that the resulting query must contain valid entries. Since: 1.6

Padtemplates describe the possible media types a pad or an elementfactory can handle. This allows for both inspection of handled types before loading the element plugin as well as identifying pads on elements that are not yet created (request or sometimes pads).

Pad and PadTemplates have Caps attached to it to describe the media type they are capable of dealing with. PadTemplate::get_caps or GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not possible to modify the caps of a padtemplate after creation.

PadTemplates have a PadPresence property which identifies the lifetime of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also the direction of the pad can be retrieved from the PadTemplate with GST_PAD_TEMPLATE_DIRECTION().

The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads because it has to be used as the name in the ElementExt::get_request_pad call to instantiate a pad from this template.

Padtemplates can be created with PadTemplate::new or with gst_static_pad_template_get (), which creates a PadTemplate from a StaticPadTemplate that can be filled with the convenient GST_STATIC_PAD_TEMPLATE() macro.

A padtemplate can be used to create a pad (see Pad::new_from_template or gst_pad_new_from_static_template ()) or to add to an element class (see gst_element_class_add_static_pad_template ()).

The following code example shows the code to create a pad from a padtemplate.

  GstStaticPadTemplate my_template =
  GST_STATIC_PAD_TEMPLATE (
    "sink",          // the name of the pad
    GST_PAD_SINK,    // the direction of the pad
    GST_PAD_ALWAYS,  // when this pad will be present
    GST_STATIC_CAPS (        // the capabilities of the padtemplate
      "audio/x-raw, "
        "channels = (int) [ 1, 6 ]"
    )
  );
  void
  my_method (void)
  {
    GstPad *pad;
    pad = gst_pad_new_from_static_template (&amp;my_template, "sink");
    ...
  }

The following example shows you how to add the padtemplate to an element class, this is usually done in the class_init of the class:

  static void
  my_element_class_init (GstMyElementClass *klass)
  {
    GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);

    gst_element_class_add_static_pad_template (gstelement_class, &amp;my_template);
  }

Implements

GstObjectExt, glib::object::ObjectExt

Creates a new pad template with a name according to the given template and with the given arguments.

`name_template`

the name template.

`direction`

the PadDirection of the template.

`presence`

the PadPresence of the pad.

`caps`

a Caps set for the template.

Returns

a new PadTemplate.

Converts a StaticPadTemplate into a PadTemplate with a type.

Feature: v1_14

`pad_template`

the static pad template

`pad_type`

The glib::Type of the pad to create

Returns

a new PadTemplate.

Creates a new pad template with a name according to the given template and with the given arguments.

Feature: v1_14

`name_template`

the name template.

`direction`

the PadDirection of the template.

`presence`

the PadPresence of the pad.

`caps`

a Caps set for the template.

`pad_type`

The glib::Type of the pad to create

Returns

a new PadTemplate.

Gets the capabilities of the pad template.

Returns

the Caps of the pad template. Unref after usage.

Emit the pad-created signal for this template when created by this pad.

`pad`

the Pad that created it

This signal is fired when an element creates a pad from this template.

`pad`

the pad that was created.

The capabilities of the pad described by the pad template.

The direction of the pad described by the pad template.

The type of the pad described by the pad template.

Feature: v1_14

The type of the pad described by the pad template.

Feature: v1_14

The name template of the pad template.

When the pad described by the pad template will become available.

Opaque structure.

Allocates a parse context for use with gst_parse_launch_full or gst_parse_launchv_full.

Free-function: gst_parse_context_free

Returns

a newly-allocated parse context. Free with ParseContext::free when no longer needed.

Copies the self.

Returns

A copied ParseContext

Frees a parse context previously allocated with ParseContext::new.

Retrieve missing elements from a previous run of gst_parse_launch_full or gst_parse_launchv_full. Will only return results if an error code of ParseError::NoSuchElement was returned.

Returns

a None-terminated array of element factory name strings of missing elements. Free with g_strfreev when no longer needed.

The different parsing errors that can occur.

A syntax error occurred.

The description contained an unknown element

An element did not have a specified property

There was an error linking two pads.

There was an error setting a property

An empty bin was specified.

An empty description was specified

A delayed link did not get resolved.

A Pipeline is a special Bin used as the toplevel container for the filter graph. The Pipeline will manage the selection and distribution of a global Clock as well as provide a Bus to the application.

Pipeline::new is used to create a pipeline. when you are done with the pipeline, use GstObjectExt::unref to free its resources including all added Element objects (if not otherwise referenced).

Elements are added and removed from the pipeline using the Bin methods like BinExt::add and BinExt::remove (see Bin).

Before changing the state of the Pipeline (see Element) a Bus can be retrieved with Pipeline::get_bus. This bus can then be used to receive Message from the elements in the pipeline.

By default, a Pipeline will automatically flush the pending Bus messages when going to the NULL state to ensure that no circular references exist when no messages are read from the Bus. This behaviour can be changed with PipelineExt::set_auto_flush_bus.

When the Pipeline performs the PAUSED to PLAYING state change it will select a clock for the elements. The clock selection algorithm will by default select a clock provided by an element that is most upstream (closest to the source). For live pipelines (ones that return StateChangeReturn::NoPreroll from the ElementExt::set_state call) this will select the clock provided by the live source. For normal pipelines this will select a clock provided by the sinks (most likely the audio sink). If no element provides a clock, a default SystemClock is used.

The clock selection can be controlled with the PipelineExt::use_clock method, which will enforce a given clock on the pipeline. With PipelineExt::auto_clock the default clock selection algorithm can be restored.

A Pipeline maintains a running time for the elements. The running time is defined as the difference between the current clock time and the base time. When the pipeline goes to READY or a flushing seek is performed on it, the running time is reset to 0. When the pipeline is set from PLAYING to PAUSED, the current clock time is sampled and used to configure the base time for the elements when the pipeline is set to PLAYING again. The effect is that the running time (as the difference between the clock time and the base time) will count how much time was spent in the PLAYING state. This default behaviour can be changed with the ElementExt::set_start_time method.

Implements

PipelineExt, BinExt, ElementExt, GstObjectExt, glib::object::ObjectExt, ChildProxyExt

Trait containing all Pipeline methods.

Implementors

Pipeline

Create a new pipeline with the given name.

`name`

name of new pipeline

Returns

newly created GstPipeline

MT safe.

Let self select a clock automatically. This is the default behaviour.

Use this function if you previous forced a fixed clock with PipelineExt::use_clock and want to restore the default pipeline clock selection algorithm.

MT safe.

Check if self will automatically flush messages when going to the NULL state.

Returns

whether the pipeline will automatically flush its bus when going from READY to NULL state or not.

MT safe.

Gets the Bus of self. The bus allows applications to receive Message packets.

Returns

a Bus, unref after usage.

MT safe.

Gets the current clock used by self. Users of object oriented languages should use PipelineExt::get_pipeline_clock to avoid confusion with ElementExt::get_clock which has a different behavior.

Unlike ElementExt::get_clock, this function will always return a clock, even if the pipeline is not in the PLAYING state.

a Clock, unref after usage.

Usually, when a pipeline goes from READY to NULL state, it automatically flushes all pending messages on the bus, which is done for refcounting purposes, to break circular references.

This means that applications that update state using (async) bus messages (e.g. do certain things when a pipeline goes from PAUSED to READY) might not get to see messages when the pipeline is shut down, because they might be flushed before they can be dispatched in the main thread. This behaviour can be disabled using this function.

It is important that all messages on the bus are handled when the automatic flushing is disabled else memory leaks will be introduced.

MT safe.

`auto_flush`

whether or not to automatically flush the bus when the pipeline goes from READY to NULL state

Set the clock for self. The clock will be distributed to all the elements managed by the pipeline.

`clock`

the clock to set

Returns

true if the clock could be set on the pipeline. false if some element did not accept the clock.

MT safe.

Set the expected delay needed for all elements to perform the PAUSED to PLAYING state change. delay will be added to the base time of the elements so that they wait an additional delay amount of time before starting to process buffers and cannot be GST_CLOCK_TIME_NONE.

This option is used for tuning purposes and should normally not be used.

MT safe.

`delay`

the delay

Sets the latency that should be configured on the pipeline. Setting GST_CLOCK_TIME_NONE will restore the default behaviour of using the minimum latency from the LATENCY query. Setting this is usually not required and the pipeline will figure out an appropriate latency automatically.

Setting a too low latency, especially lower than the minimum latency from the LATENCY query, will most likely cause the pipeline to fail.

`latency`

latency to configure

Force self to use the given clock. The pipeline will always use the given clock even if new clock providers are added to this pipeline.

If clock is None all clocking will be disabled which will make the pipeline run as fast as possible.

MT safe.

`clock`

the clock to use

Whether or not to automatically flush all messages on the pipeline's bus when going from READY to NULL state. Please see PipelineExt::set_auto_flush_bus for more information on this option.

The expected delay needed for elements to spin up to the PLAYING state expressed in nanoseconds. see PipelineExt::set_delay for more information on this option.

Latency to configure on the pipeline. See PipelineExt::set_latency.

GStreamer is extensible, so Element instances can be loaded at runtime. A plugin system can provide one or more of the basic <application>GStreamer</application> PluginFeature subclasses.

A plugin should export a symbol <symbol>gst_plugin_desc</symbol> that is a struct of type PluginDesc. the plugin loader will check the version of the core library the plugin was linked against and will create a new Plugin. It will then call the GstPluginInitFunc function that was provided in the <symbol>gst_plugin_desc</symbol>.

Once you have a handle to a Plugin (e.g. from the Registry), you can add any object that subclasses PluginFeature.

Usually plugins are always automatically loaded so you don't need to call Plugin::load explicitly to bring it into memory. There are options to statically link plugins to an app or even use GStreamer without a plugin repository in which case Plugin::load can be needed to bring the plugin into memory.

Implements

GstObjectExt, glib::object::ObjectExt

Unrefs each member of list, then frees the list.

`list`

list of Plugin

Load the named plugin. Refs the plugin.

`name`

name of plugin to load

Returns

a reference to a loaded plugin, or None on error.

Loads the given plugin and refs it. Caller needs to unref after use.

`filename`

the plugin filename to load

Returns

a reference to the existing loaded GstPlugin, a reference to the newly-loaded GstPlugin, or None if an error occurred.

Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file).

You must make sure that GStreamer has been initialised (with gst_init or via gst_init_get_option_group) before calling this function.

`major_version`

the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here

`minor_version`

the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here

`name`

a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer)

`description`

description of the plugin

`init_func`

pointer to the init function of this plugin.

`version`

version string of the plugin

`license`

effective license of plugin. Must be one of the approved licenses (see PluginDesc above) or the plugin will not be registered.

`source`

source module plugin belongs to

`package`

shipped package plugin belongs to

`origin`

URL to provider of plugin

Returns

true if the plugin was registered correctly, otherwise false.

Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file) with a GstPluginInitFullFunc which allows user data to be passed to the callback function (useful for bindings).

You must make sure that GStreamer has been initialised (with gst_init or via gst_init_get_option_group) before calling this function.

`major_version`

the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here

`minor_version`

the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here

`name`

`description`

description of the plugin

`init_full_func`

pointer to the init function with user data of this plugin.

`version`

version string of the plugin

`license`

effective license of plugin. Must be one of the approved licenses (see PluginDesc above) or the plugin will not be registered.

`source`

source module plugin belongs to

`package`

shipped package plugin belongs to

`origin`

URL to provider of plugin

`user_data`

gpointer to user data

Returns

true if the plugin was registered correctly, otherwise false.

Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed.

`env_vars`

None-terminated array of environment variables affecting the feature set of the plugin (e.g. an environment variable containing paths where to look for additional modules/plugins of a library), or None. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins".

`paths`

None-terminated array of directories/paths where dependent files may be, or None.

`names`

None-terminated array of file names (or file name suffixes, depending on flags) to be used in combination with the paths from paths and/or the paths extracted from the environment variables in env_vars, or None.

`flags`

optional flags, or PluginDependencyFlags::None

Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

Convenience wrapper function for Plugin::add_dependency which takes simple strings as arguments instead of string arrays, with multiple arguments separated by predefined delimiters (see above).

`env_vars`

one or more environment variables (separated by ':', ';' or ','), or None. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH"

`paths`

one ore more directory paths (separated by ':' or ';' or ','), or None. Example: "/usr/lib/mystuff/plugins"

`names`

one or more file names or file name suffixes (separated by commas), or None

`flags`

There may be plugins that do not have a valid release date set on them.

Returns

the date string of the plugin, or None if not available.

get the source module the plugin belongs to.

Returns

the source of the plugin

get the version of the plugin

Returns

the version of the plugin

queries if the plugin is loaded into memory

Returns

true is loaded, false otherwise

Loads self. Note that the return value is the loaded plugin; self is untouched. The normal use pattern of this function goes like this:

GstPlugin *loaded_plugin;
loaded_plugin = gst_plugin_load (plugin);
// presumably, we're no longer interested in the potentially-unloaded plugin
gst_object_unref (plugin);
plugin = loaded_plugin;

Returns

a reference to a loaded plugin, or None on error.

Adds plugin specific data to cache. Passes the ownership of the structure to the self.

The cache is flushed every time the registry is rebuilt.

`cache_data`

a structure containing the data to cache

The plugin loading errors

The plugin could not be loaded

The plugin has unresolved dependencies

The plugin has already be loaded from a different file

This is a base class for anything that can be added to a Plugin.

Implements

PluginFeatureExt, GstObjectExt, glib::object::ObjectExt

Trait containing all PluginFeature methods.

Implementors

DeviceProviderFactory, ElementFactory, PluginFeature, TypeFindFactory

Copies the list of features. Caller should call PluginFeature::list_free when done with the list.

`list`

list of PluginFeature

Returns

a copy of list, with each feature's reference count incremented.

Debug the plugin feature names in list.

`list`

a glib::List of plugin features

Unrefs each member of list, then frees the list.

`list`

list of PluginFeature

Compares the two given PluginFeature instances. This function can be used as a GCompareFunc when sorting by rank and then by name.

`p1`

a PluginFeature

`p2`

a PluginFeature

Returns

negative value if the rank of p1 > the rank of p2 or the ranks are equal but the name of p1 comes before the name of p2; zero if the rank and names are equal; positive value if the rank of p1 < the rank of p2 or the ranks are equal but the name of p2 comes before the name of p1

Checks whether the given plugin feature is at least the required version

`min_major`

minimum required major version

`min_minor`

minimum required minor version

`min_micro`

minimum required micro version

Returns

true if the plugin feature has at least the required version, otherwise false.

Get the plugin that provides this feature.

Returns

preset name

`tag`

meta data item name

`value`

value

Returns

true for success, false if e.g. there is no preset with that name or no value for the given tag

Get a copy of preset names as a None terminated string array.

Returns

list with names, use g_strfreev after usage.

Get a the names of the GObject properties that can be used for presets.

Returns

an array of property names which should be freed with g_strfreev after use.

Check if one can add new presets, change existing ones and remove presets.

Returns

true if presets are editable or false if they are static

Load the given preset.

`name`

preset name to load

Returns

true for success, false if e.g. there is no preset with that name

The type of a MessageType::Progress. The progress messages inform the application of the status of asynchronous tasks.

A new task started.

A task completed and a new one continues.

A task completed.

A task was canceled.

A task caused an error. An error message is also posted on the bus.

The Promise object implements the container for values that may be available later. i.e. a Future or a Promise in https://en.wikipedia.org/wiki/Futures_and_promises</ulink> As with all Future/Promise-like functionality, there is the concept of the producer of the value and the consumer of the value.

A Promise is created with Promise::new by the consumer and passed to the producer to avoid thread safety issues with the change callback. A Promise can be replied to with a value (or an error) by the producer with Promise::reply. Promise::interrupt is for the consumer to indicate to the producer that the value is not needed anymore and producing that value can stop. The PromiseResult::Expired state set by a call to Promise::expire indicates to the consumer that a value will never be produced and is intended to be called by a third party that implements some notion of message handling such as Bus. A callback can also be installed at Promise creation for result changes with Promise::new_with_change_func. The change callback can be used to chain GstPromises's together as in the following example.

const GstStructure *reply;
GstPromise *p;
if (gst_promise_wait (promise) != GST_PROMISE_RESULT_REPLIED)
  return; // interrupted or expired value
reply = gst_promise_get_reply (promise);
if (error in reply)
  return; // propagate error
p = gst_promise_new_with_change_func (another_promise_change_func, user_data, notify);
pass p to promise-using API

Each Promise starts out with a PromiseResult of PromiseResult::Pending and only ever transitions once into one of the other PromiseResult's.

In order to support multi-threaded code, Promise::reply, Promise::interrupt and Promise::expire may all be from different threads with some restrictions and the final result of the promise is whichever call is made first. There are two restrictions on ordering:

That Promise::reply and Promise::interrupt cannot be called after Promise::expire
That Promise::reply and Promise::interrupt cannot be called twice.

The change function set with Promise::new_with_change_func is called directly from either the Promise::reply, Promise::interrupt or Promise::expire and can be called from an arbitrary thread. Promise using APIs can restrict this to a single thread or a subset of threads but that is entirely up to the API that uses Promise.

The reply set on self

Interrupt waiting for a self. This will wake up any waiters with PromiseResult::Interrupted. Called when the consumer does not want the value produced anymore.

Feature: v1_14

Set a reply on self. This will wake up any waiters with PromiseResult::Replied. Called by the producer of the value to indicate success (or failure).

If self has already been interrupted by the consumer, then this reply is not visible to the consumer.

Feature: v1_14

`s`

a Structure with the the reply contents

Wait for self to move out of the PromiseResult::Pending state. If self is not in PromiseResult::Pending then it will return immediately with the current result.

Feature: v1_14

Returns

the result of the promise

The result of a Promise

Initial state. Waiting for transition to any other state.

Interrupted by the consumer as it doesn't want the value anymore.

A producer marked a reply

The promise expired (the carrying object lost all refs) and the promise will never be fulfilled.

Feature: v1_14

Implements

`offset`

The start offset of the buffer

`size`

The length of the buffer

`buffer`

a pointer to hold the Buffer, returns FlowReturn::Error if None.

Returns

a FlowReturn from the pad.

Invoke the default iterate internal links function of the proxy pad.

`pad`

the Pad to get the internal links of.

`parent`

the parent of pad or None

Returns

a Iterator of Pad, or None if pad has no parent. Unref each returned pad with GstObjectExt::unref.

Get the internal pad of self. Unref target pad after usage.

The internal pad of a GhostPad is the internally used pad of opposite direction, which is used to link to the target.

Returns

the target ProxyPad, can be None. Unref target pad after usage.

The different types of QoS events that can be given to the Event::new_qos method.

The QoS event type that is produced when upstream elements are producing data too quickly and the element can't keep up processing the data. Upstream should reduce their production rate. This type is also used when buffers arrive early or in time.

The QoS event type that is produced when upstream elements are producing data too slowly and need to speed up their production rate.

The QoS event type that is produced when the application enabled throttling to limit the data rate.

Queries can be performed on pads (Pad::query) and elements (Element::query). Please note that some queries might need a running pipeline to work.

Queries can be created using the gst_query_new_() functions. Query values can be set using gst_query_set_(), and parsed using gst_query_parse_*() helpers.

The following example shows how to query the duration of a pipeline:

  GstQuery *query;
  gboolean res;
  query = gst_query_new_duration (GST_FORMAT_TIME);
  res = gst_element_query (pipeline, query);
  if (res) {
    gint64 duration;
    gst_query_parse_duration (query, NULL, &amp;duration);
    g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration));
  } else {
    g_print ("duration query failed...");
  }
  gst_query_unref (query);

Constructs a new query object for querying if caps are accepted.

Free-function: gst_query_unref

`caps`

a fixed Caps

Returns

a new Query

Constructs a new query object for querying the allocation properties.

Free-function: gst_query_unref

`caps`

the negotiated caps

`need_pool`

return a pool

Returns

a new Query

Constructs a new query object for querying the buffering status of a stream.

Free-function: gst_query_unref

`format`

the default Format for the new query

Returns

a new Query

Constructs a new query object for querying the caps.

The CAPS query should return the allowable caps for a pad in the context of the element's state, its link to other elements, and the devices or files it has opened. These caps must be a subset of the pad template caps. In the NULL state with no links, the CAPS query should ideally return the same caps as the pad template. In rare circumstances, an object property can affect the caps returned by the CAPS query, but this is discouraged.

For most filters, the caps returned by CAPS query is directly affected by the allowed caps on other pads. For demuxers and decoders, the caps returned by the srcpad's getcaps function is directly related to the stream data. Again, the CAPS query should return the most specific caps it reasonably can, since this helps with autoplugging.

The filter is used to restrict the result caps, only the caps matching filter should be returned from the CAPS query. Specifying a filter might greatly reduce the amount of processing an element needs to do.

Free-function: gst_query_unref

`filter`

a filter

Returns

a new Query

Constructs a new query object for querying the pipeline-local context.

Free-function: gst_query_unref

`context_type`

Context type to query

Returns

a new Query

Constructs a new convert query object. Use gst_query_unref when done with it. A convert query is used to ask for a conversion between one format and another.

Free-function: gst_query_unref

`src_format`

the source Format for the new query

`value`

Free-function: gst_query_unref

Returns

a new Query

Constructs a new latency query object. Use gst_query_unref when done with it. A latency query is usually performed by sinks to compensate for additional latency introduced by elements in the pipeline.

Free-function: gst_query_unref

Returns

a Query

Constructs a new query stream position query object. Use gst_query_unref when done with it. A position query is used to query the current position of playback in the streams, in some format.

Free-function: gst_query_unref

`format`

the default Format for the new query

Returns

a new Query

Constructs a new query object for querying the scheduling properties.

a new Query

Add api with params as one of the supported metadata API to self.

`api`

the metadata API

`params`

API specific parameters

Add allocator and its params as a supported memory allocator.

`allocator`

the memory allocator

`params`

a AllocationParams

Set the pool parameters in self.

`pool`

the BufferPool

`size`

the buffer size

`min_buffers`

the min buffers

`max_buffers`

the max buffers

Set the buffering-ranges array field in self. The current last start position of the array should be inferior to start.

`start`

start position of the range

`stop`

stop position of the range

Returns

a gboolean indicating if the range was added or not.

Add mode as one of the supported scheduling modes to self.

`mode`

a PadMode

Check if self has metadata api set. When this function returns true, index will contain the index where the requested API and the parameters can be found.

`api`

the metadata API

`index`

the index

Returns

true when api is in the list of metadata.

Retrieve the number of values currently stored in the meta API array of the query's structure.

Returns

the metadata API array size as a guint.

the scheduling mode

`flags`

SchedulingFlags

Returns

true when mode is in the list of scheduling modes and flags are compatible with query flags.

Get the caps from self. The caps remains valid as long as self remains valid.

`caps`

A pointer to the caps

Parse the result from self and store in result.

`result`

location for the result

Parse an allocation query, writing the requested caps in caps and whether a pool is needed in need_pool, if the respective parameters are non-None.

Pool details can be retrieved using Query::get_n_allocation_pools and Query::parse_nth_allocation_pool.

`caps`

The Caps

`need_pool`

Whether a BufferPool is needed

Get the percentage of buffered data. This is a value between 0 and 100. The busy indicator is true when the buffering is in progress.

`busy`

if buffering is busy, or None

`percent`

a buffering percent, or None

Parse an available query, writing the format into format, and other results into the passed parameters, if the respective parameters are non-None

`format`

the format to set for the segment_start and segment_end values, or None

`start`

the start to set, or None

`stop`

the stop to set, or None

`estimated_total`

estimated total amount of download time remaining in milliseconds, or None

Extracts the buffering stats values from self.

`mode`

a buffering mode, or None

`avg_in`

the average input rate, or None

`avg_out`

the average output rat, or None

`buffering_left`

amount of buffering time left in milliseconds, or None

Get the filter from the caps self. The caps remains valid as long as self remains valid.

`filter`

A pointer to the caps filter

Get the caps result from self. The caps remains valid as long as self remains valid.

`caps`

A pointer to the caps

Get the context from the context self. The context remains valid as long as self remains valid.

`context`

A pointer to store the Context

Parse a context type from an existing GST_QUERY_CONTEXT query.

`context_type`

the context type, or None

Returns

a gboolean indicating if the parsing succeeded.

Parse a convert query answer. Any of src_format, src_value, dest_format, and dest_value may be None, in which case that value is omitted.

`src_format`

the storage for the Format of the source value, or None

`src_value`

the storage for the source value, or None

`dest_format`

the storage for the Format of the destination value, or None

`dest_value`

the storage for the destination value, or None

Parse a duration query answer. Write the format of the duration into format, and the value into duration, if the respective variables are non-None.

`format`

the storage for the Format of the duration value, or None.

`duration`

the storage for the total duration, or None.

Parse a latency query answer.

`live`

storage for live or None

`min_latency`

the storage for the min latency or None

`max_latency`

the storage for the max latency or None

Parse the number of formats in the formats self.

`n_formats`

the number of formats in this query.

Parse an available query and get the metadata API at index of the metadata API array.

`index`

position in the metadata API array to read

`params`

API specific parameters

Returns

a glib::Type of the metadata API at index.

Parse an available query and get the allocator and its params at index of the allocator array.

`index`

position in the allocator array to read

`allocator`

variable to hold the result

`params`

parameters for the allocator

Get the pool parameters in self.

Unref pool with GstObjectExt::unref when it's not needed any more.

`index`

index to parse

`pool`

the BufferPool

`size`

the buffer size

`min_buffers`

the min buffers

`max_buffers`

the max buffers

Parse an available query and get the start and stop values stored at the index of the buffered ranges array.

`index`

position in the buffered-ranges array to read

`start`

the start position to set, or None

`stop`

the stop position to set, or None

Returns

a gboolean indicating if the parsing succeeded.

Parse the format query and retrieve the nth format from it into format. If the list contains less elements than nth, format will be set to GST_FORMAT_UNDEFINED.

`nth`

the nth format to retrieve.

`format`

a pointer to store the nth format

Parse an available query and get the scheduling mode at index of the scheduling modes array.

`index`

position in the scheduling modes array to read

Returns

a PadMode of the scheduling mode at index.

Parse a position query, writing the format into format, and the position into cur, if the respective parameters are non-None.

`format`

the storage for the Format of the position values (may be None)

`cur`

the storage for the current position (may be None)

Set the scheduling properties.

`flags`

SchedulingFlags

`minsize`

the suggested minimum size of pull requests

`maxsize`

the suggested maximum size of pull requests:

`align`

the suggested alignment of pull requests

Parse a seeking query, writing the format into format, and other results into the passed parameters, if the respective parameters are non-None

`format`

the format to set for the segment_start and segment_end values, or None

`seekable`

the seekable flag to set, or None

`segment_start`

the segment_start to set, or None

`segment_end`

the segment_end to set, or None

Parse a segment query answer. Any of rate, format, start_value, and stop_value may be None, which will cause this value to be omitted.

See Query::set_segment for an explanation of the function arguments.

`rate`

the storage for the rate of the segment, or None

`format`

the storage for the Format of the values, or None

if buffering is busy

`percent`

a buffering percent

Set the available query result fields in self.

`format`

the format to set for the start and stop values

`start`

the start to set

`stop`

the stop to set

`estimated_total`

estimated total amount of download time remaining in milliseconds

Configures the buffering stats values in self.

`mode`

a buffering mode

`avg_in`

the average input rate

`avg_out`

the average output rate

`buffering_left`

amount of buffering time left in milliseconds

Set the caps result in self.

`caps`

A pointer to the caps

Answer a context query by setting the requested context.

`context`

the requested Context

Answer a convert query by setting the requested values.

`src_format`

the source Format

`src_value`

the source value

`dest_format`

the destination Format

`dest_value`

the destination value

Answer a duration query by setting the requested value in the given format.

`format`

the Format for the duration

`duration`

the duration of the stream

Set the formats query result fields in self. The number of formats passed must be equal to n_formats.

`n_formats`

the number of formats to set.

Set the formats query result fields in self. The number of formats passed in the formats array must be equal to n_formats.

`n_formats`

the number of formats to set.

`formats`

an array containing n_formats Format values.

Answer a latency query by setting the requested values in the given format.

`live`

if there is a live element upstream

`min_latency`

the minimal latency of the upstream elements

`max_latency`

the maximal latency of the upstream elements

Parse an available query and get the allocator and its params at index of the allocator array.

`index`

position in the allocator array to set

`allocator`

new allocator to set

`params`

parameters for the allocator

Set the pool parameters in self.

`index`

index to modify

`pool`

the BufferPool

`size`

the buffer size

`min_buffers`

the min buffers

`max_buffers`

the max buffers

Answer a position query by setting the requested value in the given format.

`format`

the requested Format

`cur`

the position to set

Set the scheduling properties.

`flags`

SchedulingFlags

`minsize`

the suggested minimum size of pull requests

`maxsize`

the suggested maximum size of pull requests

`align`

the suggested alignment of pull requests

Set the seeking query result fields in self.

`format`

the format to set for the segment_start and segment_end values

`seekable`

the seekable flag to set

`segment_start`

the segment_start to set

`segment_end`

the segment_end to set

Answer a segment query by setting the requested values. The normal playback segment of a pipeline is 0 to duration at the default rate of 1.0. If a seek was performed on the pipeline to play a different segment, this query will return the range specified in the last seek.

start_value and stop_value will respectively contain the configured playback range start and stop values expressed in format. The values are always between 0 and the duration of the media and start_value <= stop_value. rate will contain the playback rate. For negative rates, playback will actually happen from stop_value to start_value.

`rate`

the rate of the segment

`format`

the Format of the segment values (start_value and stop_value)

`start_value`

the start value

`stop_value`

the stop value

Answer a URI query by setting the requested URI.

`uri`

the URI to set

Answer a URI query by setting the requested URI redirection.

`uri`

the URI to set

Answer a URI query by setting the requested URI redirection to permanent or not.

`permanent`

whether the redirect is permanent or not

Get the structure of a query. This method should be called with a writable self so that the returned structure is guaranteed to be writable.

Returns

the Structure of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed.

Element priority ranks. Defines the order in which the autoplugger (or similar rank-picking mechanisms, such as e.g. Element::make_from_uri) will choose this element over an alternative one with the same function.

These constants serve as a rough guidance for defining the rank of a PluginFeature. Any value is valid, including values bigger than Rank::Primary.

will be chosen last or not at all

unlikely to be chosen

likely to be chosen

will be chosen first

One registry holds the metadata of a set of plugins.

Design:</emphasis>

The Registry object is a list of plugins and some functions for dealing with them. Each Plugin is matched 1-1 with a file on disk, and may or may not be loaded at a given time.

The primary source, at all times, of plugin information is each plugin file itself. Thus, if an application wants information about a particular plugin, or wants to search for a feature that satisfies given criteria, the primary means of doing so is to load every plugin and look at the resulting information that is gathered in the default registry. Clearly, this is a time consuming process, so we cache information in the registry file. The format and location of the cache file is internal to gstreamer.

On startup, plugins are searched for in the plugin search path. The following locations are checked in this order:

location from --gst-plugin-path commandline option.
the GST_PLUGIN_PATH environment variable.
the GST_PLUGIN_SYSTEM_PATH environment variable.
default locations (if GST_PLUGIN_SYSTEM_PATH is not set). Those default locations are: $XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/ and $prefix/libs/gstreamer-$GST_API_VERSION/. $XDG_DATA_HOME defaults to $HOME/.local/share.

The registry cache file is loaded from $XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin (where $XDG_CACHE_HOME defaults to $HOME/.cache) or the file listed in the GST_REGISTRY env var. One reason to change the registry location is for testing.

For each plugin that is found in the plugin search path, there could be 3 possibilities for cached information:

the cache may not contain information about a given file.
the cache may have stale information.
the cache may have current information.

In the first two cases, the plugin is loaded and the cache updated. In addition to these cases, the cache may have entries for plugins that are not relevant to the current process. These are marked as not available to the current process. If the cache is updated for whatever reason, it is marked dirty.

A dirty cache is written out at the end of initialization. Each entry is checked to make sure the information is minimally valid. If not, the entry is simply dropped.

Implementation notes:

The "cache" and "registry" are different concepts and can represent different sets of plugins. For various reasons, at init time, the cache is stored in the default registry, and plugins not relevant to the current process are marked with the PluginFlags::Cached bit. These plugins are removed at the end of initialization.

Implements

GstObjectExt, glib::object::ObjectExt

By default GStreamer will perform scanning and rebuilding of the registry file using a helper child process.

Applications might want to disable this behaviour with the Registry::fork_set_enabled function, in which case new plugins are scanned (and loaded) into the application process.

Returns

true if GStreamer will use the child helper process when rebuilding the registry.

Applications might want to disable/enable spawning of a child helper process when rebuilding the registry. See Registry::fork_is_enabled for more information.

`enabled`

whether rebuilding the registry can use a temporary child helper process.

Retrieves the singleton plugin registry. The caller does not own a reference on the registry, as it is alive as long as GStreamer is initialized.

Returns

the Registry.

Add the feature to the registry. The feature-added signal will be emitted.

feature's reference count will be incremented, and any floating reference will be removed (see Object::ref_sink)

`feature`

the feature to add

Returns

true on success.

MT safe.

Add the plugin to the registry. The plugin-added signal will be emitted.

plugin's reference count will be incremented, and any floating reference will be removed (see Object::ref_sink)

`plugin`

the plugin to add

Returns

true on success.

MT safe.

Checks whether a plugin feature by the given name exists in self and whether its version is at least the version required.

`feature_name`

the name of the feature (e.g. "oggdemux")

`min_major`

the minimum major version number

`min_minor`

the minimum minor version number

`min_micro`

the minimum micro version number

Returns

true if the feature could be found and the version is the same as the required version or newer, and false otherwise.

Runs a filter against all features of the plugins in the registry and returns a GList with the results. If the first flag is set, only the first match is returned (as a list with a single object).

`filter`

the filter to use

`first`

only return first match

`user_data`

user data passed to the filter function

Returns

a glib::List of PluginFeature. Use PluginFeature::list_free after usage.

MT safe.

Find the pluginfeature with the given name and type in the registry.

`name`

the pluginfeature name to find

`type_`

the pluginfeature type to find

Returns

the pluginfeature with the given name and type or None if the plugin was not found. GstObjectExt::unref after usage.

MT safe.

Find the plugin with the given name in the registry. The plugin will be reffed; caller is responsible for unreffing.

`name`

the plugin name to find

Returns

the plugin with the given name or None if the plugin was not found. GstObjectExt::unref after usage.

MT safe.

Retrieves a glib::List of PluginFeature of type_.

`type_`

a glib::Type.

Returns

a glib::List of PluginFeature of type_. Use PluginFeature::list_free after use

MT safe.

Retrieves a glib::List of features of the plugin with name name.

`name`

a plugin name.

Returns

a glib::List of PluginFeature. Use PluginFeature::list_free after usage.

Returns the registry's feature list cookie. This changes every time a feature is added or removed from the registry.

Returns

the feature list cookie.

Get a copy of all plugins registered in the given registry. The refcount of each element in the list in incremented.

Returns

a glib::List of Plugin. Use Plugin::list_free after usage.

MT safe.

Look up a plugin in the given registry with the given filename. If found, plugin is reffed.

`filename`

the name of the file to look up

Returns

the Plugin if found, or None if not. GstObjectExt::unref after usage.

`feature`

the feature to remove

Remove the plugin from the registry.

MT safe.

`plugin`

the plugin to remove

Scan the given path for plugins to add to the registry. The syntax of the path is specific to the registry.

`path`

the path to scan

Returns

true if registry changed

Signals that a feature has been added to the registry (possibly replacing a previously-added one by the same name)

`feature`

the feature that has been added

Signals that a plugin has been added to the registry (possibly replacing a previously-added one by the same name)

`plugin`

the plugin that has been added

Resource errors are for any resource used by an element: memory, files, network connections, process space, ... They're typically used by source and sink elements.

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

do not use this except as a placeholder for deciding where to go while developing code.

used when the resource could not be found.

used when resource is busy.

used when resource fails to open for reading.

used when resource fails to open for writing.

used when resource cannot be opened for both reading and writing, or either (but unspecified which).

used when the resource can't be closed.

used when the resource can't be read from.

used when the resource can't be written to.

used when a seek on the resource fails.

used when a synchronize on the resource fails.

used when settings can't be manipulated on.

used when the resource has no space left.

used when the resource can't be opened due to missing authorization. (Since 1.2.4)

the number of resource error types.

A Sample is a small object containing data, a type, timing and extra arbitrary information.

Create a new Sample with the provided details.

Free-function: gst_sample_unref

`buffer`

a Buffer, or None

`caps`

a Caps, or None

`segment`

a Segment, or None

the segment of self. The segment remains valid as long as self is valid.

Set the buffer list associated with self

`buffer_list`

a BufferList

The different types of seek events. When constructing a seek event with Event::new_seek or when doing gst_segment_do_seek ().

no change in position is required

absolute position is requested

relative position to duration is requested

This helper structure holds the relevant values for tracking the region of interest in a media file, called a segment.

The structure can be used for two purposes:

performing seeks (handling seek events)
tracking playback regions (handling newsegment events)

The segment is usually configured by the application with a seek event which is propagated upstream and eventually handled by an element that performs the seek.

The configured segment is then propagated back downstream with a newsegment event. This information is then used to clip media to the segment boundaries.

A segment structure is initialized with Segment::init, which takes a Format that will be used as the format of the segment values. The segment will be configured with a start value of 0 and a stop/duration of -1, which is undefined. The default rate and applied_rate is 1.0.

The public duration field contains the duration of the segment. When using the segment for seeking, the start and time members should normally be left to their default 0 value. The stop position is left to -1 unless explicitly configured to a different value after a seek event.

The current position in the segment should be set by changing the position member in the structure.

For elements that perform seeks, the current segment should be updated with the Segment::do_seek and the values from the seek event. This method will update all the segment fields. The position field will contain the new playback position. If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from the position position, possibly with updated flags or rate.

For elements that want to use Segment to track the playback region, update the segment fields with the information from the newsegment event. The Segment::clip method can be used to check and clip the media data to the segment boundaries.

For elements that want to synchronize to the pipeline clock, Segment::to_running_time can be used to convert a timestamp to a value that can be used to synchronize to the clock. This function takes into account the base as well as any rate or applied_rate conversions.

For elements that need to perform operations on media data in stream_time, Segment::to_stream_time can be used to convert a timestamp and the segment info to stream time (which is always between 0 and the duration of the stream).

Allocate a new Segment structure and initialize it using Segment::init.

Free-function: gst_segment_free

Returns

a new Segment, free with Segment::free.

Clip the given start and stop values to the segment boundaries given in self. start and stop are compared and clipped to self start and stop values.

If the function returns false, start and stop are known to fall outside of self and clip_start and clip_stop are not updated.

When the function returns true, clip_start and clip_stop will be updated. If clip_start or clip_stop are different from start or stop respectively, the region fell partially in the segment.

Note that when stop is -1, clip_stop will be set to the end of the segment. Depending on the use case, this may or may not be what you want.

`format`

the format of the segment.

`start`

the start position in the segment

`stop`

the stop position in the segment

`clip_start`

the clipped start position in the segment

`clip_stop`

the clipped stop position in the segment

Returns

true if the given start and stop times fall partially or completely in self, false if the values are completely outside of the segment.

Create a copy of given self.

Free-function: gst_segment_free

Returns

a new Segment, free with Segment::free.

Copy the contents of self into dest.

`dest`

a Segment

Update the segment structure with the field values of a seek event (see Event::new_seek).

After calling this method, the segment field position and time will contain the requested new position in the segment. The new requested position in the segment depends on rate and start_type and stop_type.

For positive rate, the new position in the segment is the new self start field when it was updated with a start_type different from SeekType::None. If no update was performed on self start position (SeekType::None), start is ignored and self position is unmodified.

For negative rate, the new position in the segment is the new self stop field when it was updated with a stop_type different from SeekType::None. If no stop was previously configured in the segment, the duration of the segment will be used to update the stop position. If no update was performed on self stop position (SeekType::None), stop is ignored and self position is unmodified.

The applied rate of the segment will be set to 1.0 by default. If the caller can apply a rate change, it should update self rate and applied_rate after calling this function.

update will be set to true if a seek should be performed to the segment position field. This field can be false if, for example, only the rate has been changed but not the playback position.

`rate`

the rate of the segment.

`format`

the format of the segment.

`flags`

the segment flags for the segment

`start_type`

the seek method

`start`

the seek start value

`stop_type`

the seek method

`stop`

the seek stop value

`update`

boolean holding whether position was updated.

Returns

true if the seek could be performed.

Free the allocated segment self.

The start/position fields are set to 0 and the stop/duration fields are set to -1 (unknown). The default rate of 1.0 and no flags are set.

Initialize self to its default values.

`format`

the position in the segment

`running_time`

result running-time

Returns

a 1 or -1 on success, 0 on failure.

Translate position to stream time using the currently configured segment. The position value must be between self start and stop value.

This function is typically used by elements that need to operate on the stream time of the buffers it receives, such as effect plugins. In those use cases, position is typically the buffer timestamp or clock time that one wants to convert to the stream time. The stream time is always between 0 and the total duration of the media stream.

`format`

the format of the segment.

`position`

the position in the segment

Returns

the position in stream_time or -1 when an invalid position was given.

Translate position to the total stream time using the currently configured segment. Compared to Segment::to_stream_time this function can return negative stream-time.

This function is typically used by elements that need to synchronize buffers against the clock or eachother.

position can be any value and the result of this function for values outside of the segment is extrapolated.

When 1 is returned, position resulted in a positive stream-time returned in stream_time.

When this function returns -1, the returned stream_time should be negated to get the real negative stream time.

`format`

the format of the segment.

`position`

the position in the segment

`stream_time`

result stream-time

Returns

a 1 or -1 on success, 0 on failure.

The possible states an element can be in. States can be changed using ElementExt::set_state and checked using ElementExt::get_state.

no pending state.

the NULL state or initial state of an element.

the element is ready to go to PAUSED.

the element is PAUSED, it is ready to accept and process data. Sink elements however only accept one buffer and then block.

the element is PLAYING, the Clock is running and the data is flowing.

These are the different state changes an element goes through. State::Null ⇒ State::Playing is called an upwards state change and State::Playing ⇒ State::Null a downwards state change.

state change from NULL to READY.

The element must check if the resources it needs are available. Device sinks and -sources typically try to probe the device to constrain their caps.
The element opens the device (in case feature need to be probed).

state change from READY to PAUSED.

The element pads are activated in order to receive data in PAUSED. Streaming threads are started.
Some elements might need to return StateChangeReturn::Async and complete the state change when they have enough information. It is a requirement for sinks to return StateChangeReturn::Async and complete the state change when they receive the first buffer or EventType::Eos (preroll). Sinks also block the dataflow when in PAUSED.
A pipeline resets the running_time to 0.
Live sources return StateChangeReturn::NoPreroll and don't generate data.

state change from PAUSED to PLAYING.

Most elements ignore this state change.
The pipeline selects a Clock and distributes this to all the children before setting them to PLAYING. This means that it is only allowed to synchronize on the Clock in the PLAYING state.
The pipeline uses the Clock and the running_time to calculate the base_time. The base_time is distributed to all children when performing the state change.
Sink elements stop blocking on the preroll buffer or event and start rendering the data.
Sinks can post MessageType::Eos in the PLAYING state. It is not allowed to post MessageType::Eos when not in the PLAYING state.
While streaming in PAUSED or PLAYING elements can create and remove sometimes pads.
Live sources start generating data and return StateChangeReturn::Success.

state change from PLAYING to PAUSED.

Most elements ignore this state change.
The pipeline calculates the running_time based on the last selected Clock and the base_time. It stores this information to continue playback when going back to the PLAYING state.
Sinks unblock any Clock wait calls.
When a sink does not have a pending buffer to play, it returns StateChangeReturn::Async from this state change and completes the state change when it receives a new buffer or an EventType::Eos.
Any queued MessageType::Eos items are removed since they will be reposted when going back to the PLAYING state. The EOS messages are queued in Bin containers.
Live sources stop generating data and return StateChangeReturn::NoPreroll.

state change from PAUSED to READY.

Sinks unblock any waits in the preroll.
Elements unblock any waits on devices
Chain or get_range functions return FlowReturn::Flushing.
The element pads are deactivated so that streaming becomes impossible and all streaming threads are stopped.
The sink forgets all negotiated formats
Elements remove all sometimes pads

state change from READY to NULL.

Elements close devices
Elements reset any internal state.

state change from NULL to NULL. (Since 1.14)

state change from READY to READY, This might happen when going to PAUSED asynchronously failed, in that case elements should make sure they are in a proper, coherent READY state. (Since 1.14)

state change from PAUSED to PAUSED. This might happen when elements were in PLAYING state and 'lost state', they should make sure to go back to real 'PAUSED' state (prerolling for example). (Since 1.14)

state change from PLAYING to PLAYING. (Since 1.14)

The possible return values from a state change function such as ElementExt::set_state. Only StateChangeReturn::Failure is a real failure.

the state change failed

the state change succeeded

the state change will happen asynchronously

the state change succeeded but the element cannot produce data in State::Paused. This typically happens with live sources.

Datastructure to initialize Caps from a string description usually used in conjunction with GST_STATIC_CAPS() and StaticCaps::get to instantiate a Caps.

the id for the new stream. If None, a new one will be automatically generated

`caps`

Feature: v1_10

`tags`

a TagList

The Caps of the Stream.

The unique identifier of the Stream. Can only be set at construction time.

The StreamType of the Stream. Can only be set at construction time.

The TagList of the Stream.

A collection of Stream that are available.

A StreamCollection will be provided by elements that can make those streams available. Applications can use the collection to show the user what streams are available by using StreamCollection::get_stream()

Once posted, a StreamCollection is immutable. Updates are made by sending a new StreamCollection message, which may or may not share some of the Stream objects from the collection it replaces. The receiver can check the sender of a stream collection message to know which collection is obsoleted.

Several elements in a pipeline can provide StreamCollection.

Applications can activate streams from a collection by using the EventType::SelectStreams event on a pipeline, bin or element.

The number of streams that self contains

Retrieve the Stream with index index from the collection.

The caller should not modify the returned Stream

Feature: v1_10

`index`

Index of the stream to retrieve

Returns

A Stream

Returns the upstream id of the self.

Feature: v1_10

Returns

The upstream id

Stream errors are for anything related to the stream being processed: format errors, media type errors, ... They're typically used by decoders, demuxers, converters, ...

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

do not use this except as a placeholder for deciding where to go while developing code.

use this when you do not want to implement this functionality yet.

used when the element doesn't know the stream's type.

used when the element doesn't handle this type of stream.

used when there's no codec to handle the stream's type.

used when decoding fails.

used when encoding fails.

used when demuxing fails.

used when muxing fails.

used when the stream is of the wrong format (for example, wrong caps).

used when the stream is encrypted and can't be decrypted because this is not supported by the element.

used when the stream is encrypted and can't be decrypted because no suitable key is available.

the number of stream error types.

The type of a MessageType::StreamStatus. The stream status messages inform the application of new streaming threads and their status.

A new thread need to be created.

a thread entered its loop function

a thread left its loop function

a thread is destroyed

a thread is started

a thread is paused

a thread is stopped

A Structure is a collection of key/value pairs. The keys are expressed as GQuarks and the values can be of any GType.

In addition to the key/value pairs, a Structure also has a name. The name starts with a letter and can be filled by letters, numbers and any of "/-_.:".

Structure is used by various GStreamer subsystems to store information in a flexible and extensible way. A Structure does not have a refcount because it usually is part of a higher level object such as Caps, Message, Event, Query. It provides a means to enforce mutability using the refcount of the parent with the Structure::set_parent_refcount method.

A Structure can be created with Structure::new_empty or Structure::new, which both take a name and an optional set of key/value pairs along with the types of the values.

Field values can be changed with Structure::set_value or Structure::set.

Field values can be retrieved with Structure::get_value or the more convenient gst_structure_get_*() functions.

Fields can be removed with Structure::remove_field or Structure::remove_fields.

Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be None however.

Creates a new Structure with the given name. Parses the list of variable arguments and sets fields to the values listed. Variable arguments should be passed as field name, field type, and value. Last variable argument should be None.

Free-function: gst_structure_free

`name`

name of new structure

`firstfield`

name of first field to set

Returns

a new Structure

Creates a new, empty Structure with the given name.

See Structure::set_name for constraints on the name parameter.

Free-function: gst_structure_free

`name`

name of new structure

Returns

a new, empty Structure

Creates a Structure from a string representation. If end is not None, a pointer to the place inside the given string where parsing ended will be returned.

The current implementation of serialization will lead to unexpected results when there are nested Caps / Structure deeper than one level.

Free-function: gst_structure_free

`string`

a string representation of a Structure

Returns

a new Structure or None when the string could not be parsed. Free with Structure::free after use.

Creates a new Structure with the given name as a GQuark, followed by fieldname quark, GType, argument(s) "triplets" in the same format as Structure::id_set. Basically a convenience wrapper around Structure::new_id_empty and Structure::id_set.

The last variable argument must be None (or 0).

Free-function: gst_structure_free

`name_quark`

name of new structure

`field_quark`

the GQuark for the name of the field to set

Returns

a new Structure

Creates a new, empty Structure with the given name as a GQuark.

Free-function: gst_structure_free

`quark`

name of new structure

Returns

a new, empty Structure

Creates a new Structure with the given name. Structure fields are set according to the varargs in a manner similar to Structure::new.

true if the values could be set correctly. If there was no field with fieldname or the existing field did not contain a GstFlagSet, this function returns false.

Sets the integers pointed to by value_numerator and value_denominator corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain an int, this function returns false.

Since 1.12

Get the name of self as a string.

Returns

the name of the structure.

Get the name of self as a GQuark.

Returns

Get the value of the field with name fieldname.

`fieldname`

the name of the field to get

Returns

the gobject::Value corresponding to the field with the given name.

Check if self contains a field named fieldname.

`fieldname`

the name of a field

Returns

true if the structure contains a field with the given name

Check if self contains a field named fieldname and with GType type_.

`fieldname`

the name of a field

`type_`

the type of a value

Returns

true if the structure contains a field with the given name and type

Checks if the structure has the given name

`name`

structure name to check for

Returns

true if name matches the name of the structure.

Parses the variable arguments and reads fields from self accordingly. Variable arguments should be in the form field id quark, field type (as a GType), pointer(s) to a variable(s) to hold the return value(s). The last variable argument should be None (technically it should be a 0 quark, but we require None so compilers that support it can check for the None terminator and warn if it's not there).

This function is just like Structure::get only that it is slightly more efficient since it saves the string-to-quark lookup in the global quark hashtable.

`first_field_id`

the quark of the first field to read

Returns

false if there was a problem reading any of the fields (e.g. because the field requested did not exist, or was of a type other than the type specified), otherwise true.

Parses the variable arguments and reads fields from self accordingly. valist-variant of Structure::id_get. Look at the documentation of Structure::id_get for more details.

`first_field_id`

the quark of the first field to read

Removes the field with the given name. If the field with the given name does not exist, the structure is unchanged.

`fieldname`

the name of the field to remove

Removes the fields with the given names. If a field does not exist, the argument is ignored.

`fieldname`

the name of the field to remove

va_list form of Structure::remove_fields.

`fieldname`

the name of the field to remove

`varargs`

None-terminated list of more fieldnames to remove

Parses the variable arguments and sets fields accordingly. Fields that weren't already part of the structure are added as needed. Variable arguments should be in the form field name, field type (as a GType), value(s). The last variable argument should be None.

`fieldname`

the name of the field to set

This is useful in language bindings where unknown GValue types are not supported. This function will convert a array to GST_TYPE_ARRAY and set the field specified by fieldname. Be aware that this is slower then using GST_TYPE_ARRAY in a gobject::Value directly.

Since 1.12

`fieldname`

the name of a field

`array`

a pointer to a gobject::ValueArray

Since 1.12

`fieldname`

the name of a field

`array`

a pointer to a gobject::ValueArray

Sets the name of the structure to the given name. The string provided is copied before being used. It must not be empty, start with a letter and can be followed by letters, numbers and any of "/-_.:".

`name`

the new name of the structure

Sets the parent_refcount field of Structure. This field is used to determine whether a structure is mutable or not. This function should only be called by code implementing parent objects of Structure, as described in the MT Refcounting section of the design documents.

`refcount`

a pointer to the parent's refcount

Returns

true if the parent refcount could be set.

va_list form of Structure::set.

`fieldname`

the name of the field to set

`varargs`

variable arguments

Sets the field with the given name field to value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed.

`fieldname`

the name of the field to set

`value`

the new value of the field

Sets the field with the given name field to value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed. The function will take ownership of value.

`fieldname`

the name of the field to set

`value`

the new value of the field

Converts self to a human-readable string representation.

For debugging purposes its easier to do something like this:

GST_LOG ("structure is %" GST_PTR_FORMAT, structure);

This prints the structure in human readable form.

The current implementation of serialization will lead to unexpected results when there are nested Caps / Structure deeper than one level.

Free-function: g_free

Returns

a pointer to string allocated by g_malloc. g_free after usage.

Creates a Structure from a string representation. If end is not None, a pointer to the place inside the given string where parsing ended will be returned.

Free-function: gst_structure_free

`string`

a string representation of a Structure.

`end`

pointer to store the end of the string in.

Returns

a new Structure or None when the string could not be parsed. Free with Structure::free after use.

The type of a MessageType::StructureChange.

Pad linking is starting or done.

Pad unlinking is starting or done.

The GStreamer core provides a GstSystemClock based on the system time. Asynchronous callbacks are scheduled from an internal thread.

Clock implementors are encouraged to subclass this systemclock as it implements the async notification.

Subclasses can however override all of the important methods for sync and async notifications to implement their own callback methods or blocking wait operations.

Implements

SystemClockExt, ClockExt, GstObjectExt, glib::object::ObjectExt

Trait containing all SystemClock methods.

Implementors

SystemClock

Get a handle to the default system clock. The refcount of the clock will be increased so you need to unref the clock after usage.

Returns

the default clock.

MT safe.

Sets the default system clock that can be obtained with SystemClock::obtain.

This is mostly used for testing and debugging purposes when you want to have control over the time reported by the default system clock.

MT safe.

`new_clock`

a Clock

List of tags and values used to describe media metadata.

Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings must not be empty or None.

Creates a new taglist and appends the values for the given tags. It expects tag-value pairs like TagList::add, and a None terminator after the last pair. The type of the values is implicit and is documented in the API reference, but can also be queried at runtime with gst_tag_get_type. It is an error to pass a value of a type not matching the tag type into this function. The tag list will make copies of any arguments passed (e.g. strings, buffers).

After creation you might also want to set a TagScope on the returned taglist to signal if the contained tags are global or stream tags. By default stream scope is assumes. See TagList::set_scope.

Free-function: gst_tag_list_unref

`tag`

tag

Returns

a new TagList. Free with gst_tag_list_unref when no longer needed.

Creates a new empty GstTagList.

Free-function: gst_tag_list_unref

Returns

An empty tag list

Deserializes a tag list.

`str`

a string created with TagList::to_string

Returns

a new TagList, or None in case of an error.

Just like TagList::new, only that it takes a va_list argument. Useful mostly for language bindings.

Free-function: gst_tag_list_unref

`var_args`

tag / value pairs to set

Returns

`mode`

the mode to use

`tag`

tag

Calls the given function for each tag inside the tag list. Note that if there is no tag, the function won't be called at all.

`func`

function to be called for each tag

`user_data`

user specified data

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`tag`

tag to read out

`value`

location for the result

Returns

true, if a value was copied, false if the tag didn't exist in the given list.

number of entry to read out

`value`

location for the result

Returns

true, if a value was copied, false if the tag didn't exist in the given list or if it was None.

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`tag`

tag to read out

`value`

location for the result

Returns

true, if a value was copied, false if the tag didn't exist in the given list.

Gets the value that is at the given index for the given tag in the given list.

number of entry to read out

`value`

location for the result

Returns

true, if a value was copied, false if the tag didn't exist in the given list.

Gets the value that is at the given index for the given tag in the given list.

location for the result

Returns

true, if a value was copied, false if the tag didn't exist in the given list.

Copies the first sample for the given tag in the taglist into the variable pointed to by sample. Free the sample with gst_sample_unref when it is no longer needed. You can retrieve the buffer from the sample using Sample::get_buffer and the associated caps (if any) with Sample::get_caps.

Free-function: gst_sample_unref

`tag`

tag to read out

`sample`

address of a GstSample pointer variable to store the result into

Returns

true, if a sample was returned, false if the tag didn't exist in the given list or if it was None.

Gets the sample that is at the given index for the given tag in the given list and copies it into the variable pointed to by sample. Free the sample with gst_sample_unref when it is no longer needed. You can retrieve the buffer from the sample using Sample::get_buffer and the associated caps (if any) with Sample::get_caps.

Free-function: gst_sample_unref

`tag`

tag to read out

`index`

number of entry to read out

`sample`

address of a GstSample pointer variable to store the result into

Returns

true, if a sample was copied, false if the tag didn't exist in the given list or if it was None.

Gets the scope of self.

Returns

The scope of self

Copies the contents for the given tag into the value, possibly merging multiple values into one if multiple values are associated with the tag.

Use gst_tag_list_get_string_index (list, tag, 0, value) if you want to retrieve the first string associated with this tag unmodified.

The resulting string in value will be in UTF-8 encoding and should be freed by the caller using g_free when no longer needed. The returned string is also guaranteed to be non-None and non-empty.

Free-function: g_free

`tag`

tag to read out

`value`

location for the result

Returns

true, if a value was copied, false if the tag didn't exist in the given list.

Gets the value that is at the given index for the given tag in the given list.

The resulting string in value will be in UTF-8 encoding and should be freed by the caller using g_free when no longer needed. The returned string is also guaranteed to be non-None and non-empty.

Free-function: g_free

`tag`

tag to read out

`index`

number of entry to read out

`value`

location for the result

Returns

`tag`

tag to read out

`index`

number of entry to read out

`value`

location for the result

Returns

true, if a value was copied, false if the tag didn't exist in the given list.

Gets the value that is at the given index for the given tag in the given list.

`tag`

tag to read out

`index`

number of entry to read out

`value`

location for the result

Returns

true, if a value was copied, false if the tag didn't exist in the given list.

Gets the value that is at the given index for the given tag in the given list.

`tag`

tag to read out

`index`

number of entry to read out

Returns

`tag`

tag to read out

`index`

number of entry to read out

`value`

location for the result

Returns

true, if a value was set, false if the tag didn't exist in the given list.

Removes the given tag from the taglist.

`tag`

tag to remove

Sets the scope of self to scope. By default the scope of a taglist is stream scope.

`scope`

new scope for self

Serializes a tag list to a string.

Returns

a newly-allocated string, or None in case of an error. The string must be freed with g_free when no longer needed.

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. You must gobject::Value::unset the value after use.

`dest`

uninitialized gobject::Value to copy into

`list`

list to get the tag from

`tag`

tag to read out

Returns

true, if a value was copied, false if the tag didn't exist in the given list.

The different tag merging modes are basically replace, overwrite and append, but they can be seen from two directions. Given two taglists: (A) the tags already in the element and (B) the ones that are supplied to the element ( e.g. via TagSetter::merge_tags / TagSetter::add_tags or a EventType::Tag), how are these tags merged? In the table below this is shown for the cases that a tag exists in the list (A) or does not exists (!A) and combinations thereof.

`` `` `` ``merge mode`` ``A + B`` ``A + !B`` ``!A + B`` ``!A + !B`` `` `` `` `` ``REPLACE_ALL`` ``B`` ``-`` ``B`` ``-`` `` `` ``REPLACE`` ``B`` ``A`` ``B`` ``-`` `` `` ``APPEND`` ``A, B`` ``A`` ``B`` ``-`` `` `` ``PREPEND`` ``B, A`` ``A`` ``B`` ``-`` `` `` ``KEEP`` ``A`` ``A`` ``B`` ``-`` `` `` ``KEEP_ALL`` ``A`` ``A`` ``-`` ``-`` `` `` `` `

` undefined merge mode replace all tags (clear list and append) replace tags append tags prepend tags keep existing tags keep all existing tags the number of merge modes Element interface that allows setting of media metadata.

Elements that support changing a stream's metadata will implement this interface. Examples of such elements are 'vorbisenc', 'theoraenc' and 'id3v2mux'.

If you just want to retrieve metadata in your application then all you need to do is watch for tag messages on your pipeline's bus. This interface is only for setting metadata, not for extracting it. To set tags from the application, find tagsetter elements and set tags using e.g. TagSetter::merge_tags or TagSetter::add_tags. Also consider setting the TagMergeMode that is used for tag events that arrive at the tagsetter element (default mode is to keep existing tags). The application should do that before the element goes to State::Paused.

Elements implementing the TagSetter interface often have to merge any tags received from upstream and the tags set by the application via the interface. This can be done like this:

GstTagMergeMode merge_mode;
const GstTagList *application_tags;
const GstTagList *event_tags;
GstTagSetter *tagsetter;
GstTagList *result;

tagsetter = GST_TAG_SETTER (element);

merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter);
application_tags = gst_tag_setter_get_tag_list (tagsetter);
event_tags = (const GstTagList *) element->event_tags;

GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode);
GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags);
GST_LOG_OBJECT (tagsetter, "set   tags: %" GST_PTR_FORMAT, application_tags);

result = gst_tag_list_merge (application_tags, event_tags, merge_mode);

GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result);

Implements

tag to set

Returns the current list of tags the setter uses. The list should not be modified or freed.

This function is not thread-safe.

Returns

a current snapshot of the taglist used in the setter or None if none is used.

Queries the mode by which tags inside the setter are overwritten by tags from events

Returns

the merge mode used inside the element.

Merges the given list into the setter's list using the given mode.

`list`

a tag list to merge from

`mode`

the mode to merge with

Reset the internal taglist. Elements should call this from within the state-change handler.

Sets the given merge mode that is used for adding tags from events to tags specified by this interface. The default is TagMergeMode::Keep, which keeps the tags set with this interface and discards tags from events.

`mode`

The mode with which tags are added

The different states a task can be in

the task is started and running

the task is stopped

the task is paused

Toc functions are used to create/free Toc and TocEntry structures. Also they are used to convert Toc into Structure and vice versa.

Toc lets you to inform other elements in pipeline or application that playing source has some kind of table of contents (TOC). These may be chapters, editions, angles or other types. For example: DVD chapters, Matroska chapters or cue sheet TOC. Such TOC will be useful for applications to display instead of just a playlist.

Using TOC is very easy. Firstly, create Toc structure which represents root contents of the source. You can also attach TOC-specific tags to it. Then fill it with TocEntry entries by appending them to the Toc using Toc::append_entry, and appending subentries to a TocEntry using TocEntry::append_sub_entry.

Note that root level of the TOC can contain only either editions or chapters. You should not mix them together at the same level. Otherwise you will get serialization /deserialization errors. Make sure that no one of the entries has negative start and stop values.

Use Event::new_toc to create a new TOC Event, and Event::parse_toc to parse received TOC event. Use Event::new_toc_select to create a new TOC select Event, and Event::parse_toc_select to parse received TOC select event. The same rule for the Message: Message::new_toc to create new TOC Message, and Message::parse_toc to parse received TOC message.

TOCs can have global scope or current scope. Global scope TOCs contain all entries that can possibly be selected using a toc select event, and are what an application is usually interested in. TOCs with current scope only contain the parts of the TOC relevant to the currently selected/playing stream; the current scope TOC is used by downstream elements such as muxers to write correct TOC entries when transcoding files, for example. When playing a DVD, the global TOC would contain a hierarchy of all titles, chapters and angles, for example, while the current TOC would only contain the chapters for the currently playing title if playback of a specific title was requested.

Applications and plugins should not rely on TOCs having a certain kind of structure, but should allow for different alternatives. For example, a simple CUE sheet embedded in a file may be presented as a flat list of track entries, or could have a top-level edition node (or some other alternative type entry) with track entries underneath that node; or even multiple top-level edition nodes (or some other alternative type entries) each with track entries underneath, in case the source file has extracted a track listing from different sources).

Create a new Toc structure.

`scope`

scope of this TOC

Returns

newly allocated Toc structure, free it with gst_toc_unref.

A TagList for entry

Merge tags into the existing tags of self using mode.

`tags`

A TagList or None

`mode`

A TagMergeMode

Set a TagList with tags for the complete self.

`tags`

A TagList or None

Create new TocEntry structure.

`type_`

entry type.

`uid`

unique ID (UID) in the whole TOC.

Returns

newly allocated TocEntry structure, free it with gst_toc_entry_unref.

Appends the TocEntry subentry to self.

`subentry`

A TocEntry

Returns

self's entry type

Get loop_type and repeat_count values from the self and write them into appropriate storages. Loops are e.g. used by sampled instruments. GStreamer is not automatically applying the loop. The application can process this meta data and use it e.g. to send a seek-event to loop a section.

`loop_type`

the storage for the loop_type value, leave None if not need.

`repeat_count`

the storage for the repeat_count value, leave None if not need.

Returns

true if all non-None storage pointers were filled with appropriate values, false otherwise.

Gets the parent TocEntry of self.

Returns

The parent TocEntry of self

Get start and stop values from the self and write them into appropriate storages.

`start`

the storage for the start value, leave None if not need.

`stop`

the storage for the stop value, leave None if not need.

Returns

true if all non-None storage pointers were filled with appropriate values, false otherwise.

Gets the sub-entries of self.

Returns

A glib::List of TocEntry of self

Gets the tags for self.

Returns

A TagList for self

Gets the parent Toc of self.

Returns

The parent Toc of self

Gets the UID of self.

Returns

The UID of self

Returns

true if self's type is an alternative type, otherwise false

Returns

true if self's type is a sequence type, otherwise false

Merge tags into the existing tags of self using mode.

`tags`

A TagList or None

`mode`

A TagMergeMode

Set loop_type and repeat_count values for the self.

`loop_type`

loop_type value to set.

`repeat_count`

repeat_count value to set.

Set start and stop values for the self.

`start`

start value to set.

`stop`

stop value to set.

Set a TagList with tags for the complete self.

`tags`

A TagList or None

The different types of TOC entries (see TocEntry).

There are two types of TOC entries: alternatives or parts in a sequence.

entry is an angle (i.e. an alternative)

entry is a version (i.e. alternative)

entry is an edition (i.e. alternative)

invalid entry type value

entry is a title (i.e. a part of a sequence)

entry is a track (i.e. a part of a sequence)

entry is a chapter (i.e. a part of a sequence)

How a TocEntry should be repeated. By default, entries are played a single time.

single forward playback

repeat forward

repeat backward

repeat forward and backward

The scope of a TOC.

global TOC representing all selectable options (this is what applications are usually interested in)

TOC for the currently active/selected stream (this is a TOC representing the current stream from start to EOS, and is what a TOC writer / muxer is usually interested in; it will usually be a subset of the global TOC, e.g. just the chapters of the current title, or the chapters selected for playback from the current title)

Element interface that allows setting of the TOC.

Elements that support some kind of chapters or editions (or tracks like in the FLAC cue sheet) will implement this interface.

If you just want to retrieve the TOC in your application then all you need to do is watch for TOC messages on your pipeline's bus (or you can perform TOC query). This interface is only for setting TOC data, not for extracting it. To set TOC from the application, find proper tocsetter element and set TOC using TocSetter::set_toc.

Elements implementing the TocSetter interface can extend existing TOC by getting extend UID for that (you can use Toc::find_entry to retrieve it) with any TOC entries received from downstream.

Implements

TocSetterExt, ElementExt, GstObjectExt, glib::object::ObjectExt

Trait containing all TocSetter methods.

Implementors

TocSetter

Return current TOC the setter uses. The TOC should not be modified without making it writable first.

Returns

TOC set, or None. Unref with gst_toc_unref when no longer needed

Reset the internal TOC. Elements should call this from within the state-change handler.

Set the given TOC on the setter. Previously set TOC will be unreffed before setting a new one.

`toc`

a Toc to set.

These functions allow querying informations about registered typefind functions. How to create and register these functions is described in the section "Writing typefind functions"</link>.

The following example shows how to write a very simple typefinder that identifies the given data. You can get quite a bit more complicated than that though.

  typedef struct {
    guint8 *data;
    guint size;
    guint probability;
    GstCaps *data;
  } MyTypeFind;
  static void
  my_peek (gpointer data, gint64 offset, guint size)
  {
    MyTypeFind *find = (MyTypeFind *) data;
    if (offset &gt;= 0 &amp;&amp; offset + size &lt;= find->size) {
      return find->data + offset;
    }
    return NULL;
  }
  static void
  my_suggest (gpointer data, guint probability, GstCaps *caps)
  {
    MyTypeFind *find = (MyTypeFind *) data;
    if (probability &gt; find->probability) {
      find->probability = probability;
      gst_caps_replace (&amp;find->caps, caps);
    }
  }
  static GstCaps *
  find_type (guint8 *data, guint size)
  {
    GList *walk, *type_list;
    MyTypeFind find = {data, size, 0, NULL};
    GstTypeFind gst_find = {my_peek, my_suggest, &amp;find, };
    walk = type_list = gst_type_find_factory_get_list ();
    while (walk) {
      GstTypeFindFactory *factory = GST_TYPE_FIND_FACTORY (walk->data);
      walk = g_list_next (walk)
      gst_type_find_factory_call_function (factory, &amp;gst_find);
    }
    g_list_free (type_list);
    return find.caps;
  };

Implements

PluginFeatureExt, GstObjectExt, glib::object::ObjectExt

Gets the list of all registered typefind factories. You must free the list using PluginFeature::list_free.

unlikely typefind.

possible type detected.

likely a type was detected.

nearly certain that a type was detected.

very certain a type was detected.

Different URI-related errors that can occur.

The protocol is not supported

There was a problem with the URI

Could not set or change the URI because the URI handler was in a state where that is not possible or not permitted

There was a problem with the entity that the URI references

The URIHandler is an interface that is implemented by Source and Sink Element to unify handling of URI.

URI to set

Returns

true if the URI was set successfully, else false.

The different types of URI direction.

The URI direction is unknown

The URI is a consumer.

The URI is a producer.

469 KiB Raw Blame History

Notes

Implements

Implementors

name

Returns

element

Returns

element_1

direction

Returns

iface

Returns

name

Returns

name

Returns

Returns

iface

Returns

Returns

Returns

Returns

Returns

Returns

Returns

element

Returns

element_1

flags

Returns

sub_bin

element

sub_bin

element

element

element

Returns

allocator

size

params

Returns

data

size

Returns

flags

data

maxsize

offset

size

user_data

notify

Returns

info

params

Returns

ref_

Returns

info

Returns

reference

timestamp

duration

Returns

buf2

Returns

mem

buf2

offset

size

Returns

Returns

src

flags

offset

size

Returns

flags

offset

size

469 KiB

Raw Blame History

`name`

`element`

`element_1`

`direction`

`iface`

`name`

`name`

`iface`

`element`

`element_1`

`flags`

`sub_bin`

`element`

`sub_bin`

`element`

`element`

`element`

`allocator`

`size`

`params`

`data`

`size`

`flags`

`data`

`maxsize`

`offset`

`size`

`user_data`

`notify`

`info`

`params`

`ref_`

`info`

`reference`

`timestamp`

`duration`

`buf2`

`mem`

`buf2`

`offset`

`size`

`src`

`flags`

`offset`

`size`

`flags`

`offset`

`size`

`offset`

`dest`

`size`

`offset`

`size`

`dest`

`dest_size`

`offset`

`src`

`size`

`offset`

`size`

`idx`

`length`

`skip`

`func`

`user_data`

`idx`

`idx`

`length`

`api`

`api_type`

`reference`

`offset`

`maxsize`

`idx`

`length`

`offset`

`maxsize`

`idx`

`mem`