gstreamer-rs/docs/gstreamer/docs.md
Sebastian Dröge d2467b4b65 Update docs
2020-07-06 15:22:07 +03:00

521 KiB

Memory is usually created by allocators with a AllocatorExt::alloc method call. When None is used as the allocator, the default allocator will be used.

New allocators can be registered with Allocator::register. Allocators are identified by name and can be retrieved with Allocator::find. AllocatorExt::set_default can be used to change the default allocator.

New memory can be created with Memory::new_wrapped that wraps the memory allocated elsewhere.

Implements

AllocatorExt, GstObjectExt, glib::object::ObjectExt, AllocatorExtManual

Trait containing all Allocator methods.

Implementors

Allocator

Find a previously registered allocator with name. When name is None, the default allocator will be returned.

name

the name of the allocator

Returns

a Allocator or None when the allocator with name was not registered. Use GstObjectExt::unref to release the allocator after usage.

Registers the memory allocator with name. This function takes ownership of allocator.

name

the name of the allocator

allocator

Allocator

Use self to allocate a new memory block with memory that is at least size big.

The optional params can specify the prefix and padding for the memory. If None is passed, no flags, no extra prefix/padding and a default alignment is used.

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

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

The alignment in params is given as a bitmask so that align + 1 equals the amount of bytes to align to. For example, to align to 8 bytes, use an alignment of 7.

size

size of the visible memory area

params

optional parameters

Returns

a new Memory.

Free memory that was previously allocated with AllocatorExt::alloc.

memory

the memory to free

Set the default allocator. This function takes ownership of self.

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 GstBinExt::add. You can remove elements with GstBinExt::remove.

An element can be retrieved from a bin with GstBinExt::get_by_name, using the elements name. GstBinExt::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 GstBinExt::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 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. Note also that there might be a discrepancy (due to internal buffering/queueing) between the stream being currently displayed and the returned duration query. Applications might want to also query for duration (and changes) by listening to the GST_MESSAGE_STREAM_START message, signaling the active start of a (new) stream.

  • 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: The bin will forward the query to all sink elements contained within and will return the maximum value. 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

GstBinExt, ElementExt, GstObjectExt, glib::object::ObjectExt, ChildProxyExt, ElementExtManual, ChildProxyExtManual

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 Element::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 GstBinExt::add for each member of the list. The return value of each GstBinExt::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 GstBinExt::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 with the given element factory name. The function recurses inside child bins. The iterator will yield a series of Element that should be unreffed after use.

MT safe. Caller owns returned value.

Feature: v1_18

factory_name

the name of the ElementFactory

Returns

a Iterator of Element for all elements in the bin with the given element factory name, or None.

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.

MT safe. Caller owns returned value.

iface

the glib::Type of an interface

Returns

a Iterator of Element for all elements in the bin implementing the given interface, or None

Gets an iterator for the elements in this bin.

MT safe. Caller owns returned value.

Returns

a Iterator of Element, or None

Gets an iterator for the elements in this bin. This iterator recurses into GstBin children.

MT safe. Caller owns returned value.

Returns

a Iterator of Element, or None

Gets an iterator for all elements in the bin that have the ElementFlags::Sink flag set.

MT safe. Caller owns returned value.

Returns

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.

Returns

a Iterator of Element, or None

Gets an iterator for all elements in the bin that have the ElementFlags::Source flag set.

MT safe. Caller owns returned value.

Returns

a Iterator of Element, or None

Query self for the current latency using and reconfigures this latency to all the elements with a LATENCY event.

This method is typically called on the pipeline when a MessageType::Latency is posted on the bus.

This function simply emits the 'do-latency' signal so any custom latency calculations will be performed.

Returns

true if the latency could be queried and reconfigured.

Removes the element from the bin, unparenting it as well. Unparenting the element means that the element will be dereferenced, so if the bin holds the only reference to the element, the element will be freed in the process of removing it from the bin. If you want the element to still exist after removing, you need to call GstObjectExt::ref before removing it from the bin.

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

MT safe.

element

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

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.

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.

GstBinFlags are a set of flags specific to bins. Most are set/used internally. They can be checked using the GST_OBJECT_FLAG_IS_SET () macro, and (un)set using GST_OBJECT_FLAG_SET () and GST_OBJECT_FLAG_UNSET ().

don't resync a state change when elements are added or linked in the bin (Since: 1.0.5)

Indicates whether the bin can handle elements that add/remove source pads at any point in time without first posting a no-more-pads signal (Since: 1.10)

the last enum in the series of flags for bins. Derived classes can use this as first value in a list of flags.

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.

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

Creates a new Buffer that wraps the given bytes. The data inside bytes cannot be None and the resulting buffer will be marked as read only.

MT safe.

Feature: v1_16

bytes

a glib::Bytes to wrap

Returns

a new Buffer wrapping bytes

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.

info

a MetaInfo

params

params for info

Returns

the metadata for the api in info on self.

Add a ParentBufferMeta to self that holds a reference on ref_ until the buffer is freed.

ref_

a Buffer to ref

Returns

The ParentBufferMeta that was added to the buffer

Attaches protection metadata to a Buffer.

info

a Structure holding cryptographic information relating to the sample contained in self. This function takes ownership of info.

Returns

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

Add a ReferenceTimestampMeta to self that holds a timestamp and optionally duration based on a specific timestamp reference. See the documentation of ReferenceTimestampMeta for details.

Feature: v1_14

reference

identifier for the timestamp reference.

timestamp

timestamp

duration

duration, or GST_CLOCK_TIME_NONE

Returns

The ReferenceTimestampMeta that was added to the buffer

Append all the memory from buf2 to self. The result buffer will contain a concatenation of the memory of self and buf2.

buf2

the second source Buffer to append.

Returns

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

Append 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 -1. See Buffer::insert_memory for more details.

mem

a Memory.

Append size bytes at offset from buf2 to self. The result buffer will contain a concatenation of the memory of self and the requested region of buf2.

buf2

the second source Buffer to append.

offset

the offset in buf2

size

the size or -1 of buf2

Returns

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

Create a copy of the given buffer. This will only copy the buffer's data to a newly allocated memory if needed (if the type of memory requires it), otherwise the underlying data is just referenced. Check Buffer::copy_deep if you want to force the data to be copied to newly allocated memory.

Returns

a new copy of self.

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.

Creates a sub-buffer from self at offset and size. This sub-buffer uses the actual memory space of the parent buffer. This function will copy the offset and timestamp fields when the offset is 0. If not, they will be set to GST_CLOCK_TIME_NONE and GST_BUFFER_OFFSET_NONE. If offset equals 0 and size equals the total size of buffer, the duration and offset end fields are also copied. If not they will be set to GST_CLOCK_TIME_NONE and GST_BUFFER_OFFSET_NONE.

MT safe.

flags

the BufferCopyFlags

offset

the offset into parent Buffer at which the new sub-buffer begins.

size

the size of the new Buffer sub-buffer, in bytes. If -1, all data is copied.

Returns

the new Buffer or None if the arguments were invalid.

Copy size bytes starting from offset in self to dest.

offset

the offset to extract

dest

the destination address

size

the size to extract

Returns

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

Extracts a copy of at most size bytes the data at offset into newly-allocated memory. dest must be freed using g_free when done.

offset

the offset to extract

size

the size to extract

dest

A pointer where the destination array will be written. Might be None if the size is 0.

dest_size

A location where the size of dest can be written

Copy size bytes from src to self at offset.

offset

the offset to fill

src

the source address

size

the size to fill

Returns

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

Find the memory blocks that span size bytes starting from offset in self.

When this function returns true, idx will contain the index of the first memory block where the byte for offset can be found and length contains the number of memory blocks containing the size remaining bytes. skip contains the number of bytes to skip in the memory block at idx to get to the byte for offset.

size can be -1 to get all the memory blocks after idx.

offset

an offset

size

a size

idx

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.

Call func with user_data for each meta in self.

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

func

a GstBufferForeachMetaFunc to call

user_data

user data passed to func

Returns

false when func returned false for one of the metadata.

Get all the memory block in self. The memory blocks will be merged into one large Memory.

Returns

a Memory that contains the merged memory. Use gst_memory_unref () after usage.

Get the BufferFlags flags set on this buffer.

Feature: v1_10

Returns

the flags set on this buffer.

Get the memory block at index idx in self.

idx

an index

Returns

a Memory that contains the data of the memory block at idx. Use gst_memory_unref () after usage.

Get length memory blocks in self starting at idx. The memory blocks will be merged into one large Memory.

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

idx

an index

length

a length

Returns

a Memory that contains the merged data of length blocks starting at idx. Use gst_memory_unref () after usage.

Get the metadata for api on buffer. When there is no such metadata, None is returned. If multiple metadata with the given api are attached to this buffer only the first one is returned. To handle multiple metadata with a given API use Buffer::iterate_meta or Buffer::foreach_meta instead and check the meta->info.api member for the API type.

api

the glib::Type of an API

Returns

the metadata for api on self.

Feature: v1_14

api_type

the glib::Type of an API

Returns

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.

Gives the status of a specific flag on a buffer.

Feature: v1_10

flags

the BufferFlags flag to check.

Returns

true if all flags in flags are found on 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

Returns

The next Meta or None when there are no more items.

Retrieve the next Meta of type meta_api_type after the current one according to state. If state points to None, the first metadata of type meta_api_type is returned.

state will be updated with an opaque state pointer

Feature: v1_12

state

an opaque state pointer

meta_api_type

only return Meta of this type

Returns

The next Meta of type meta_api_type or None when there are no more items.

This function fills info with the MapInfo of all merged memory blocks in self.

flags describe the desired access of the memory. When flags is MapFlags::Write, self should be writable (as returned from gst_buffer_is_writable).

When self is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

The memory in info should be unmapped with Buffer::unmap after usage.

info

info about the mapping

flags

flags for the mapping

Returns

true if the map succeeded and info contains valid data.

This function fills info with the MapInfo of length merged memory blocks starting at idx in self. When length is -1, all memory blocks starting from idx are merged and mapped.

flags describe the desired access of the memory. When flags is MapFlags::Write, self should be writable (as returned from gst_buffer_is_writable).

When self is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

The memory in info should be unmapped with Buffer::unmap after usage.

idx

an index

length

a length

info

info about the mapping

flags

flags for the mapping

Returns

true if the map succeeded and info contains valid data.

Compare size bytes starting from offset in self with the memory in mem.

offset

the offset in self

mem

the memory to compare

size

the size to compare

Returns

0 if the memory is equal.

Fill buf with size bytes with val starting from offset.

offset

the offset in self

val

the value to set

size

the size to set

Returns

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.

Increases the refcount of the given buffer by one.

Note that the refcount affects the writability of self and its metadata, see gst_buffer_is_writable. It is important to note that keeping additional references to GstBuffer instances can potentially increase the number of memcpy operations in a pipeline.

Returns

self

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.

Replaces all memory in self with mem.

mem

a Memory

Replaces the memory block at index idx in self with mem.

idx

an index

mem

a Memory

Replaces length memory blocks in self starting at idx with mem.

If length is -1, all memory starting from idx will be removed and replaced with mem.

self should be writable.

idx

an index

length

a length should not be 0

mem

a Memory

Set the offset and total size of the memory blocks in self.

offset

the offset adjustment

size

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

Decreases the refcount of the buffer. If the refcount reaches 0, the buffer with the associated metadata and memory will be freed.

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.

Modifies a pointer to a Buffer to point to a different Buffer. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old buffer is unreffed, the new is reffed).

Either nbuf or the Buffer pointed to by obuf may be None.

obuf

pointer to a pointer to a Buffer to be replaced.

nbuf

pointer to a Buffer that will replace the buffer pointed to by obuf.

Returns

true when obuf was different from nbuf.

A set of flags that can be provided to the Buffer::copy_into function to specify which items should be copied.

copy nothing

flag indicating that buffer flags should be copied

flag indicating that buffer pts, dts, duration, offset and offset_end should be copied

flag indicating that buffer meta should be copied

flag indicating that buffer memory should be reffed and appended to already existing memory. Unless the memory is marked as NO_SHARE, no actual copy of the memory is made but it is simply reffed. Add BufferCopyFlags::Deep to force a real copy.

flag indicating that buffer memory should be merged

flag indicating that memory should always be copied instead of reffed (Since: 1.2)

A set of buffer flags used to describe properties of a Buffer.

the buffer is live data and should be discarded in the PAUSED state.

the buffer contains data that should be dropped because it will be clipped against the segment boundaries or because it does not contain data that should be shown to the user.

the buffer marks a data discontinuity in the stream. This typically occurs after a seek or a dropped buffer from a live or network source.

the buffer timestamps might have a discontinuity and this buffer is a good point to resynchronize.

the buffer data is corrupted.

the buffer contains a media specific marker. for video this is the end of a frame boundary, for audio this is the start of a talkspurt.

the buffer contains header information that is needed to decode the following data.

the buffer has been created to fill a gap in the stream and contains media neutral data (elements can switch to optimized code path that ignores the buffer content).

the buffer can be dropped without breaking the stream, for example to reduce bandwidth.

this unit cannot be decoded independently.

this flag is set when memory of the buffer is added/removed

Elements which write to disk or permanent storage should ensure the data is synced after writing the contents of this buffer. (Since: 1.6)

This buffer is important and should not be dropped. This can be used to mark important buffers, e.g. to flag RTP packets carrying keyframes or codec setup data for RTP Forward Error Correction purposes, or to prevent still video frames from being dropped by elements due to QoS. (Since: 1.14)

additional media specific flags can be added starting from this flag.

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. BufferList::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. BufferList::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 shallow copy of the given buffer list. This will make a newly allocated copy of the source list with copies of buffer pointers. The refcount of buffers pointed to will be increased by one.

Returns

a new copy of self.

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

Increases the refcount of the given buffer list by one.

Note that the refcount affects the writability of self and its data, see gst_buffer_list_make_writable. It is important to note that keeping additional references to GstBufferList instances can potentially increase the number of memcpy operations in a pipeline.

Returns

self

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

Decreases the refcount of the buffer list. If the refcount reaches 0, the buffer list will be freed.

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, BufferPoolExtManual

Trait containing all BufferPool methods.

Implementors

BufferPool

Creates a new BufferPool instance.

Returns

a new BufferPool instance

Enabled the option in config. This will instruct the bufferpool to enable the specified option on the buffers that it allocates.

The supported options by pool can be retrieved with BufferPoolExt::get_options.

config

a BufferPool configuration

option

an option to add

Get the allocator and params from config.

config

a BufferPool configuration

allocator

a Allocator, or None

params

AllocationParams, or None

Returns

true, if the values are set.

Parse an available config and get the option at index of the options API array.

config

a BufferPool configuration

index

position in the option array to read

Returns

a gchar of the option at index.

Get the configuration values from config.

config

a BufferPool configuration

caps

the caps of buffers

size

the size of each buffer, not including prefix and padding

min_buffers

the minimum amount of buffers to allocate.

max_buffers

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

Returns

true if all parameters could be fetched.

Check if config contains option.

config

a BufferPool configuration

option

an option

Returns

true if the options array contains option.

Retrieve the number of values currently stored in the options array of the config structure.

config

a BufferPool configuration

Returns

the options array size as a guint.

Set the allocator and params on config.

One of allocator and params can be None, but not both. When allocator is None, the default allocator of the pool will use the values in param to perform its allocation. When param is None, the pool will use the provided allocator with its default AllocationParams.

A call to BufferPool::set_config can update the allocator and params with the values that it is able to do. Some pools are, for example, not able to operate with different allocators or cannot allocate with the values specified in params. Use BufferPool::get_config to get the currently used values.

config

a BufferPool configuration

allocator

a Allocator

params

AllocationParams

Configure config with the given parameters.

config

a BufferPool configuration

caps

caps for the buffers

size

the size of each buffer, not including prefix and padding

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

Additional flags to control the allocation of a buffer

no flags

buffer is keyframe

when the bufferpool is empty, acquire_buffer will by default block until a buffer is released into the pool again. Setting this flag makes acquire_buffer return FlowReturn::Eos instead of blocking.

buffer is discont

last flag, subclasses can use private flags starting from this value.

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 Message::ref before leaving func.

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.

priority

The priority of the watch.

func

A function to call when a message is received.

user_data

user data passed to func.

notify

the function to call when the source is removed.

Returns

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

A helper GstBusFunc that can be used to convert all asynchronous messages into signals.

message

the Message received

data

user data

Returns

true

Create watch for this bus. The GSource will be dispatched whenever a message is on the bus. After the GSource is dispatched, the message is popped off the bus and unreffed.

Returns

a glib::Source that can be added to a mainloop.

Instructs GStreamer to stop emitting the "sync-message" signal for this bus. See Bus::enable_sync_message_emission for more information.

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 synchronous emission of signals when messages arrive; Bus::add_signal_watch adds an idle callback to pop messages off the bus asynchronously. 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 Message::unref after usage.

Get a message from the bus.

Returns

the Message that is on the bus, or None if the bus is empty. The message is taken from the bus and needs to be unreffed with Message::unref after usage.

MT safe.

Get a message matching type_ from the bus. Will discard all messages on the bus that do not match type_ and that have been posted before the first message that does match type_. If there is no message matching type_ on the bus, all messages will be discarded. It is not possible to use message enums beyond MessageType::Extended in the events mask.

types

message types to take into account

Returns

the next Message matching type_ that is on the bus, or None if the bus is empty or there is no message matching type_. The message is taken from the bus and needs to be unreffed with Message::unref after usage.

MT safe.

Post a message on the given bus. Ownership of the message is taken by the bus.

message

the Message to post

Returns

true if the message could be posted, false if the bus is flushing.

MT safe.

Removes a signal watch previously added with Bus::add_signal_watch.

MT safe.

Removes an installed bus watch from self.

Returns

true on success or false if self has no event source.

If flushing, flush out and unref any messages queued in the bus. Releases references to the message origin objects. Will flush future messages until Bus::set_flushing sets flushing to false.

MT safe.

flushing

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.

Before 1.16.3 it was not possible to replace an existing handler and clearing an existing handler with None was not thread-safe.

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

Creates a new Caps that is empty. That is, the returned Caps contains no media formats. The Caps is guaranteed to be writable. Caller is responsible for unreffing the returned caps.

Returns

the new Caps

Creates a new Caps that contains one Structure with name media_type. Caller is responsible for unreffing the returned caps.

media_type

the media type of the structure

Returns

the new Caps

Creates a new Caps and adds all the structures listed as arguments. The list must be None-terminated. The structures are not copied; the returned Caps owns the structures.

struct1

the first structure to add

Returns

the new Caps

Creates a new Caps and adds all the structures listed as arguments. The list must be None-terminated. The structures are not copied; the returned Caps owns the structures.

structure

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 as a copy of the old self. The new caps will have a refcount of 1, owned by the caller. The structures are copied as well.

Note that this function is the semantic equivalent of a Caps::ref followed by a gst_caps_make_writable. If you only want to hold on to a reference to the data, you should use Caps::ref.

When you are finished with the caps, call Caps::unref on it.

Returns

the new Caps

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

Feature: v1_16

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.

This function takes ownership of self and will call gst_caps_make_writable on it so you must not use self afterwards unless you keep an additional reference to it with Caps::ref.

Note that it is not guaranteed that the returned caps have exactly one structure. If self are empty caps then then returned caps will be the empty too and contain no structure at all.

Calling this function with any caps is not allowed.

Returns

the fixated caps

Calls the provided function once for each structure and caps feature in the Caps. The function must not modify the fields. Also see Caps::map_in_place and Caps::filter_and_map_in_place.

func

a function to call for each field

user_data

private data

Returns

true if the supplied function returns true for each call, false otherwise.

Finds the features in self that has the index index, and returns it.

WARNING: This function takes a const GstCaps *, but returns a non-const GstCapsFeatures *. 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 features returned in the usual way, e.g. with functions like CapsFeatures::add.

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 CapsFeatures corresponding to index

Gets the number of structures contained in self.

Returns

the number of structures that self contains

Finds the structure in self that has the index index, and returns it.

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.

Determines if self represents no media formats.

Returns

true if self represents no formats.

Checks if the given caps represent the same set of caps.

caps2

another Caps

Returns

true if both caps are equal.

Tests if two Caps are equal. This function only works on fixed Caps.

caps2

the Caps to test

Returns

true if the arguments represent the same format

Fixed Caps describe exactly one format, that is, they have exactly one structure, and each field in the structure describes a fixed type. Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST.

Returns

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

true if self is a subset of superset

Checks if structure is a subset of self. See Caps::is_subset for more information.

structure

a potential Structure subset of self

Returns

true if structure is a subset of self

Checks if structure is a subset of self. See Caps::is_subset for more information.

structure

a potential Structure subset of self

features

a CapsFeatures for structure

Returns

true if structure is a subset of self

Calls the provided function once for each structure and caps feature in the Caps. In contrast to Caps::foreach, the function may modify but not delete the structures and features. The caps must be mutable.

func

a function to call for each field

user_data

private data

Returns

true if the supplied function returns true for each call, false otherwise.

Appends the structures contained in caps2 to self if they are not yet expressed by self. The structures in caps2 are not copied -- they are transferred to a writable copy of self, and then caps2 is freed. If either caps is ANY, the resulting caps will be ANY.

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

the merged caps.

Returns a Caps that represents the same set of formats as self, but contains no lists. Each list is expanded into separate GstStructures.

This function takes ownership of self and will call gst_caps_make_writable on it so you must not use self afterwards unless you keep an additional reference to it with Caps::ref.

Returns

the normalized Caps

Add a reference to a Caps object.

From this point on, until the caller calls Caps::unref or gst_caps_make_writable, it is guaranteed that the caps object will not change. This means its structures won't change, etc. To use a Caps object, you must always have a refcount on it -- either the one made implicitly by e.g. Caps::new_simple, or via taking one explicitly with this function.

Returns

the same Caps object.

removes the structure with the given index from the list of structures contained in self.

idx

Index of the structure to remove

Sets the CapsFeatures features for the structure at index.

index

the index of the structure

features

the CapsFeatures to set

Sets the CapsFeatures features for all the structures of self.

Feature: v1_16

features

the CapsFeatures to set

Sets fields in a Caps. The arguments must be passed in the same manner as Structure::set, and be None-terminated.

field

first field to set

Sets fields in a Caps. The arguments must be passed in the same manner as Structure::set, and be None-terminated.

field

first field to set

varargs

additional parameters

Sets the given field on all structures of self to the given value. This is a convenience function for calling Structure::set_value on all structures of self.

field

name of the field to set

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

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 Caps::ref.

Note that it is not guaranteed that the returned caps have exactly one structure. If self is any or empty caps then then returned caps will be the same and contain no structure at all.

Returns

truncated caps

Unref a Caps and and free all its structures and the structures' values when the refcount reaches 0.

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

Modifies a pointer to a Caps to point to a different Caps. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old caps is unreffed, the new is reffed).

Either new_caps or the Caps pointed to by old_caps may be None.

old_caps

pointer to a pointer to a Caps to be replaced.

new_caps

pointer to a Caps that will replace the caps pointed to by old_caps.

Returns

true if new_caps was different from old_caps

Modifies a pointer to a Caps to point to a different Caps. This function is similar to Caps::replace except that it takes ownership of new_caps.

old_caps

pointer to a pointer to a Caps to be replaced.

new_caps

pointer to a Caps that will replace the caps pointed to by old_caps.

Returns

true if new_caps was different from old_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, ChildProxyExtManual

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, ClockExtManual

Trait containing all Clock methods.

Implementors

Clock, SystemClock

Compares the two ClockID instances. This function can be used as a GCompareFunc when sorting ids.

id1

A ClockID

id2

A ClockID to compare with

Returns

negative value if a < b; zero if a = b; positive value if a > b

MT safe.

This function returns the underlying clock.

Feature: v1_16

id

a ClockID

Returns

a Clock or None when the underlying clock has been freed. Unref after usage.

MT safe.

Get the time of the clock ID

id

The ClockID to query

Returns

the time of the given clock id.

MT safe.

Increase the refcount of given id.

id

The ClockID to ref

Returns

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

This function returns whether id uses clock as the underlying clock. clock can be NULL, in which case the return value indicates whether the underlying clock has been freed. If this is the case, the id is no longer usable and should be freed.

Feature: v1_16

id

a ClockID to check

clock

a Clock to compare against

Returns

whether the clock id uses the same underlying Clock clock.

MT safe.

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

the result of the blocking wait. ClockReturn::Early will be returned if the current clock time is past the time of id, ClockReturn::Ok if id was scheduled in time. ClockReturn::Unscheduled if id was unscheduled with Clock::id_unschedule.

MT safe.

Register a callback on the given ClockID id with the given function and user_data. When passing a ClockID with an invalid time to this function, the callback will be called immediately with a time set to GST_CLOCK_TIME_NONE. The callback will be called when the time of id has been reached.

The callback func can be invoked from any thread, either provided by the core or from a streaming thread. The application should be prepared for this.

id

a ClockID to wait on

func

The callback function

user_data

User data passed in the callback

destroy_data

GDestroyNotify for user_data

Returns

the result of the non blocking wait.

MT safe.

The time master of the master clock and the time slave of the slave clock are added to the list of observations. If enough observations are available, a linear regression algorithm is run on the observations and self is recalibrated.

If this functions returns true, r_squared will contain the correlation coefficient of the interpolation. A value of 1.0 means a perfect regression was performed. This value can be used to control the sampling frequency of the master and slave clocks.

slave

a time on the slave

master

a time on the master

r_squared

a pointer to hold the result

Returns

true if enough observations were added to run the regression algorithm.

MT safe.

Add a clock observation to the internal slaving algorithm the same as ClockExt::add_observation, and return the result of the master clock estimation, without updating the internal calibration.

The caller can then take the results and call ClockExt::set_calibration with the values, or some modified version of them.

slave

a time on the slave

master

a time on the master

r_squared

a pointer to hold the result

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

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

rate_denom

a location to store the rate denominator

Gets the current internal time of the given clock. The time is returned unadjusted for the offset and the rate.

Returns

the internal time of the clock. Or GST_CLOCK_TIME_NONE when given invalid input.

MT safe.

Get the master clock that self is slaved to or None when the clock is not slaved to any master clock.

Returns

a master Clock or None when this clock is not slaved to a master clock. Unref after usage.

MT safe.

Get the accuracy of the clock. The accuracy of the clock is the granularity of the values returned by ClockExt::get_time.

Returns

the resolution of the clock in units of ClockTime.

MT safe.

Gets the current time of the given clock. The time is always monotonically increasing and adjusted according to the current offset and rate.

Returns

the time of the clock. Or GST_CLOCK_TIME_NONE when given invalid input.

MT safe.

Get the amount of time that master and slave clocks are sampled.

Returns

the interval between samples.

Checks if the clock is currently synced.

This returns if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock.

Returns

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 type of the clock entry

a single shot timeout

a periodic timeout request

The capabilities of this clock

clock can do a single sync timeout request

clock can do a single async timeout request

clock can do sync periodic timeout requests

clock can do async periodic timeout callbacks

clock's resolution can be changed

clock can be slaved to a master clock

clock needs to be synced before it can be used (Since: 1.6)

subclasses can add additional flags starting from this flag

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)

time since Epoch, but using International Atomic Time as reference (Since: 1.18)

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:

  1. Check if the element already has a context
  2. Query downstream with GST_QUERY_CONTEXT for the context
  3. Query upstream with GST_QUERY_CONTEXT for the context
  4. 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
  5. 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

Offset from UTC in hours.

year

the gregorian year

month

the gregorian month

day

the day of the gregorian month

hour

the hour of the day

minute

the minute of the hour

seconds

the second of the minute

Returns

the newly created DateTime

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

Free-function: gst_date_time_unref

dt

the glib::DateTime. The new DateTime takes ownership.

Returns

a newly created DateTime, or None on error

Tries to parse common variants of ISO-8601 datetime strings into a DateTime. Possible input formats are (for example): 2012-06-30T22:46:43Z, 2012, 2012-06, 2012-06-30, 2012-06-30T22:46:43-0430, 2012-06-30T22:46Z, 2012-06-30T22:46-0430, 2012-06-30 22:46, 2012-06-30 22:46:43, 2012-06-00, 2012-00-00, 2012-00-30, 22:46:43Z, 22:46Z, 22:46:43-0430, 22:46-0430, 22:46:30, 22:46 If no date is provided, it is assumed to be "today" in the timezone provided (if any), otherwise UTC.

Free-function: gst_date_time_unref

string

ISO 8601-formatted datetime string.

Returns

a newly created DateTime, or None on error

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

Free-function: gst_date_time_unref

secs

seconds from the Unix epoch

Returns

the newly created DateTime

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

Feature: v1_18

usecs

microseconds from the Unix epoch

Returns

a 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 time since Jan 1, 1970 specified by usecs. The DateTime is in UTC.

Feature: v1_18

usecs

microseconds from the Unix epoch

Returns

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

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

If hour is -1, then the DateTime created will only contain year and month and day, and the time fields will be considered not set. In this case minute and seconds should also be -1.

Free-function: gst_date_time_unref

year

the gregorian year

month

the gregorian month, or -1

day

the day of the gregorian month, or -1

hour

the hour of the day, or -1

minute

the minute of the hour, or -1

seconds

the second of the minute, or -1

Returns

the newly created DateTime

Creates a new DateTime representing the current date and time.

Free-function: gst_date_time_unref

Returns

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

Creates a new DateTime that represents the current instant at Universal coordinated time.

Free-function: gst_date_time_unref

Returns

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.

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

year

the gregorian year

month

the gregorian month

day

the day of the gregorian month

Returns

the newly created DateTime

Returns the day of the month of this DateTime. Call DateTime::has_day before, to avoid warnings.

Returns

The day of this DateTime

Retrieves the hour of the day represented by self in the gregorian calendar. The return is in the range of 0 to 23. Call DateTime::has_time before, to avoid warnings.

Returns

the hour of the day

Retrieves the fractional part of the seconds in microseconds represented by self in the gregorian calendar.

Returns

the microsecond of the second

Retrieves the minute of the hour represented by self in the gregorian calendar. Call DateTime::has_time before, to avoid warnings.

Returns

the minute of the hour

Returns the month of this DateTime. January is 1, February is 2, etc.. Call DateTime::has_month before, to avoid warnings.

Returns

The month of this DateTime

Retrieves the second of the minute represented by self in the gregorian calendar. Call DateTime::has_time before, to avoid warnings.

Returns

the second represented by self

Retrieves the offset from UTC in hours that the timezone specified by self represents. Timezones ahead (to the east) of UTC have positive values, timezones before (to the west) of UTC have negative values. If self represents UTC time, then the offset is zero.

Returns

the offset from UTC in hours

Returns the year of this DateTime Call DateTime::has_year before, to avoid warnings.

Returns

The year of this DateTime

Returns

true if self's day field is set, otherwise false

Returns

true if self's month field is set, otherwise false

Returns

true if self's second field is set, otherwise false

Returns

true if self's hour and minute fields are set, otherwise false

Returns

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.

These are some terminal style flags you can use when creating your debugging categories to make them stand out in debugging output.

Use black as foreground color.

Use red as foreground color.

Use green as foreground color.

Use yellow as foreground color.

Use blue as foreground color.

Use magenta as foreground color.

Use cyan as foreground color.

Use white as foreground color.

Use black as background color.

Use red as background color.

Use green as background color.

Use yellow as background color.

Use blue as background color.

Use magenta as background color.

Use cyan as background color.

Use white as background color.

Make the output bold.

Underline the output.

Available details for pipeline graphs produced by GST_DEBUG_BIN_TO_DOT_FILE() and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS().

show caps-name on edges

show caps-details on edges

show modified parameters on elements

show element states

show full element parameter values even if they are very long

show all the typical details that one might want

show all details regardless of how large or verbose they make the resulting output

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.

name

name of new element, or None to automatically create a unique name.

Returns

a new Element configured to use this device

Getter for the Caps that this device supports.

Returns

The Caps supported by this device. Unref with Caps::unref when done.

Gets the "class" of a device. This is a "/" separated list of classes that represent this device. They are a subset of the classes of the DeviceProvider that produced this device.

Returns

The device class. Free with g_free after use.

Gets the user-friendly name of the device.

Returns

The device name. Free with g_free after use.

Gets the extra properties of a device.

Returns

The extra properties or None when there are none. Free with Structure::free after use.

Check if self matches all of the given classes

classes

a "/"-separated list of device classes to match, only match if all classes are matched

Returns

true if self matches.

Check if factory matches all of the given classes

classes

a None terminated array of classes to match, only match if all classes are matched

Returns

true if self matches.

Tries to reconfigure an existing element to use the device. If this function fails, then one must destroy the element and create a new one using DeviceExt::create_element.

Note: This should only be implemented for elements can change their device in the PLAYING state.

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, DeviceMonitorExtManual

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 currently 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 DeviceMonitor::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 programmatically 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, DeviceProviderExtManual

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

This function is used when changed_device was modified into its new form device. This will post a DEVICE_CHANGED message on the bus to let the application know that the device was modified. Device is immutable for MT. safety purposes so this is an "atomic" way of letting the application know when a device was modified.

Feature: v1_16

device

the new version of changed_device

changed_device

the old version of the device that has been updated

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

This is for use by subclasses.

device

a Device that has been removed

Gets the Bus of this DeviceProvider

Returns

a Bus

Gets a list of devices that this provider understands. This may actually probe the hardware if the provider is not currently started.

Returns

a glib::List of Device

Retrieves the factory that was used to create this device provider.

Returns

the DeviceProviderFactory used for creating this device provider. no refcounting is needed.

Get the provider factory names of the DeviceProvider instances that are hidden by self.

Returns

a list of hidden providers factory names or None when nothing is hidden by self. Free with g_strfreev.

Get metadata with key in self.

Feature: v1_14

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.

Use the DeviceProviderFactory::find and DeviceProviderFactory::get functions to create device provider instances or use DeviceProviderFactory::get_by_name as a convenient shortcut.

Implements

PluginFeatureExt, GstObjectExt, glib::object::ObjectExt, PluginFeatureExtManual

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

name

name of factory to find

Returns

DeviceProviderFactory if found, None otherwise

Returns the device provider of the type defined by the given device provider factory.

factoryname

a named factory to instantiate

Returns

a DeviceProvider or None if unable to create device provider

Get a list of factories with a rank greater or equal to minrank. The list of factories is returned by decreasing rank.

minrank

Minimum rank

Returns

a glib::List of DeviceProviderFactory device providers. Use PluginFeature::list_free after usage.

Returns the device provider of the type defined by the given device providerfactory.

Returns

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.

Get the available keys for the metadata on self.

Returns

a None-terminated array of key strings, or None when there is no metadata. Free with g_strfreev when no longer needed.

Check if self matches all of the given classes

classes

a "/" separate list of classes to match, only match if all classes are matched

Returns

true if self matches or if classes is None.

Check if self matches all of the given classes

classes

a None terminated array of classes to match, only match if all classes are matched

Returns

true if self matches.

GstElement is the abstract base class needed to construct an element that can be used in a GStreamer pipeline. Please refer to the plugin writers guide for more information on creating Element subclasses.

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

Elements can have pads (of the type Pad). These pads link to pads on other elements. Buffer flow between these linked pads. A Element has a 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 Element::get_state and Element::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, ElementExtManual

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

rank

rank of element (higher rank means more importance when autoplugging)

type_

GType of element to register

Returns

true, if the registering succeeded, false on error

Gets a string representing the given state change result.

state_ret

a StateChangeReturn to get the name of.

Returns

a string with the name of the state result.

Gets a string representing the given state.

state

a State to get the name of.

Returns

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 automatically activated when added in the PAUSED or PLAYING state.

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

This function will emit the 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 Element::set_state or indirectly e.g. via SEEK events.

Calling those functions directly from the streaming thread will cause deadlocks in many situations, as they might involve waiting for the streaming thread to shut down from this very streaming thread.

MT safe.

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.

Returns

the base time of the element.

MT safe.

Returns the bus of the element. Note that only a Pipeline will provide a bus for the application.

Returns

the element's Bus. unref after usage.

MT safe.

Gets the currently configured clock of the element. This is the clock as was last set with ElementExt::set_clock.

Elements in a pipeline will only have their clock set when the pipeline is in the PLAYING state.

Returns

the Clock of the element. unref after usage.

MT safe.

Looks for an unlinked pad to which the given pad can link. It is not guaranteed that linking the pads will work, though it should work in most cases.

This function will first attempt to find a compatible unlinked ALWAYS pad, and if none can be found, it will request a compatible REQUEST pad by looking at the templates of self.

pad

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

Returns the current clock time of the element, as in, the time of the element's clock, or GST_CLOCK_TIME_NONE if there is no clock.

Feature: v1_18

Returns

the clock time of the element, or GST_CLOCK_TIME_NONE if there is no clock.

Returns the running time of the element. The running time is the element's clock time minus its base time. Will return GST_CLOCK_TIME_NONE if the element has no clock, or if its base time has not been set.

Feature: v1_18

Returns

the running time of the element, or GST_CLOCK_TIME_NONE if the element has no clock or its base time has not been set.

Retrieves the factory that was used to create this element.

Returns

the ElementFactory used for creating this element or None if element has not been registered (static element). no refcounting is needed.

Get metadata with key in klass.

Feature: v1_14

key

the key to get

Returns

the metadata for key.

Retrieves a padtemplate from self with the given name.

Feature: v1_14

name

the name of the PadTemplate to get.

Returns

the PadTemplate with the given name, or None if none was found. No unreferencing is necessary.

Retrieves a list of the pad templates associated with self. The list must not be modified by the calling code.

Feature: v1_14

Returns

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 Element::set_state, this function will block up to the specified timeout value for the state change to complete. If the element completes the state change or goes into an error, this function returns immediately with a return value of 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.

Returns

true, if the element's state is locked.

Retrieves an iterator of self's pads. The iterator should be freed after usage. Also more specialized iterators exists such as ElementExt::iterate_src_pads or ElementExt::iterate_sink_pads.

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns

the Iterator of Pad.

MT safe.

Retrieves an iterator of self's sink pads.

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns

the Iterator of Pad.

MT safe.

Retrieves an iterator of self's source pads.

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns

the Iterator of Pad.

MT safe.

Links self to dest. The link must be from source to destination; the other direction will not be tried. The function looks for existing pads that aren't linked yet. It will request new pads if necessary. Such pads need to be released manually when unlinking. If multiple links are possible, only one is established.

Make sure you have added your elements to a bin or pipeline with GstBinExt::add before trying to link them.

dest

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

element_2

the second Element in the link chain.

Returns

true on success, false otherwise.

Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails.

srcpadname

the name of the Pad in source element or None for any pad.

dest

the Element containing the destination pad.

destpadname

the name of the Pad in destination element, or None for any pad.

Returns

true if the pads could be linked, false otherwise.

Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. If caps is not None, makes sure that the caps of the link is a subset of caps.

srcpadname

the name of the Pad in source element or None for any pad.

dest

the Element containing the destination pad.

destpadname

the name of the Pad in destination element or None for any pad.

filter

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

Returns

true if the pads could be linked, false otherwise.

Links the two named pads of the source and destination elements. Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails.

Calling ElementExt::link_pads_full with flags == PadLinkCheck::Default is the same as calling ElementExt::link_pads and the recommended way of linking pads with safety checks applied.

This is a convenience function for Pad::link_full.

srcpadname

the name of the Pad in source element or None for any pad.

dest

the Element containing the destination pad.

destpadname

the name of the Pad in destination element, or None for any pad.

flags

the PadLinkCheck to be performed when linking pads.

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

true if the event was handled. Flushing seeks will trigger a preroll, which will emit MessageType::AsyncDone.

Simple API to perform a seek on the given element, meaning it just seeks to the given position relative to the start of the stream. For more complex operations like segment seeks (e.g. for looping) or changing the playback rate or seeking relative to the last configured playback segment you should use Element::seek.

In a completely prerolled PAUSED or PLAYING pipeline, seeking is always guaranteed to return true on a seekable media type or false when the media type is certainly not seekable (such as a live stream).

Some elements allow for seeking in the READY state, in this case they will store the seek event and execute it when they are put to PAUSED. If the element supports seek in READY, it will always return true when it receives the event in the READY state.

format

a Format to execute the seek in, such as Format::Time

seek_flags

seek options; playback applications will usually want to use GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here

seek_pos

position to seek to (relative to the start); if you are doing a seek in Format::Time this value is in nanoseconds - multiply with GST_SECOND to convert seconds to nanoseconds or with GST_MSECOND to convert milliseconds to nanoseconds.

Returns

true if the seek operation succeeded. Flushing seeks will trigger a preroll, which will emit MessageType::AsyncDone.

Sends an event to an element. If the element doesn't implement an event handler, the event will be pushed on a random linked sink pad for downstream events or a random linked source pad for upstream events.

This function takes ownership of the provided event so you should Event::ref it if you want to reuse the event after this call.

MT safe.

event

the Event to send to the element.

Returns

true if the event was handled. Events that trigger a preroll (such as flushing seeks and steps) will emit MessageType::AsyncDone.

Set the base time of an element. See ElementExt::get_base_time.

MT safe.

time

the base time to set.

Sets the bus of the element. Increases the refcount on the bus. For internal use only, unless you're testing elements.

MT safe.

bus

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.

Note that this is racy if the state lock of the parent bin is not taken. The parent bin might've just checked the flag in another thread and as the next step proceed to change the child element's state.

MT safe.

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 Element::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 Element::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, PluginFeatureExtManual

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

caps

a Caps

direction

a PadDirection to filter on

subsetonly

whether to filter on caps subsets or not.

Returns

a glib::List of ElementFactory elements that match the given requisites. Use PluginFeature::list_free after usage.

Get a list of factories that match the given type_. Only elements with a rank greater or equal to minrank will be returned. The list of factories is returned by decreasing rank.

type_

a ElementFactoryListType

minrank

Minimum rank

Returns

a glib::List of ElementFactory elements. Use PluginFeature::list_free after usage.

Create a new element of the type defined by the given element factory. If name is None, then the element will receive a guaranteed unique name, consisting of the element factory name and a number. If name is given, it will be given the name supplied.

factoryname

a named factory to instantiate

name

name of new element, or None to automatically create a unique name

Returns

new Element or None if unable to create element

Checks if the factory can sink all possible capabilities.

caps

the caps to check

Returns

true if the caps are fully compatible.

Checks if the factory can sink any possible capability.

caps

the caps to check

Returns

true if the caps have a common subset.

Checks if the factory can src all possible capabilities.

caps

the caps to check

Returns

true if the caps are fully compatible.

Checks if the factory can src any possible capability.

caps

the caps to check

Returns

true if the caps have a common subset.

Create a new element of the type defined by the given elementfactory. It will be given the name supplied, since all elements require a name as their first argument.

name

name of new element, or None to automatically create a unique name

Returns

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.

key

a key

Returns

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

Get the available keys for the metadata on self.

Returns

a None-terminated array of key strings, or None when there is no metadata. Free with g_strfreev when no longer needed.

Gets the number of pad_templates in this factory.

Returns

the number of pad_templates

Gets the glib::List of StaticPadTemplate for this factory.

Returns

the static pad templates

Gets a None-terminated array of protocols this element supports or None if no protocols are supported. You may not change the contents of the returned array, as it is still owned by the element factory. Use g_strdupv to make a copy of the protocol string array if you need to.

Returns

the supported protocols or None

Gets the type of URIs the element supports or URIType::Unknown if none.

Returns

type of URIs this element supports

Check if self implements the interface with name interfacename.

interfacename

an interface name

Returns

true when self implement the interface.

Check if self is of the given types.

type_

a ElementFactoryListType

Returns

true if self is of type_.

The standard flags that an element may have.

ignore state changes from parent

the element is a sink

the element is a source.

the element can provide a clock

the element requires a clock

the element can use an index

offset to define more flags

The event class provides factory methods to construct events for sending and functions to query (parse) received events.

Events are usually created with gst_event_new_*() which takes event-type specific parameters as arguments. To send an event application will usually use Element::send_event and elements will use Pad::send_event or Pad::push_event. The event should be unreffed with Event::unref if it has not been sent.

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

minimum buffer size

maxsize

maximum buffer size

async

thread behavior

Returns

a new Event

Create a new CAPS event for caps. The caps event can only travel downstream synchronized with the buffer flow and contains the format of the buffers that will follow after the event.

caps

a Caps

Returns

the new CAPS event.

Create a new custom-typed event. This can be used for anything not handled by other event-specific functions to pass an event to another element.

Make sure to allocate an event type with the GST_EVENT_MAKE_TYPE macro, assigning a free number and filling in the correct direction and serialization flags.

New custom events can also be created by subclassing the event type if needed.

type_

The type of the new event

structure

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

Returns

the new custom event.

Create a new EOS event. The eos event can only travel downstream synchronized with the buffer flow. Elements that receive the EOS event on a pad can return FlowReturn::Eos as a FlowReturn when data after the EOS event arrives.

The EOS event will travel down to the sink elements in the pipeline which will then post the MessageType::Eos on the bus after they have finished playing any buffered data.

When all sinks have posted an EOS message, an EOS message is forwarded to the application.

The EOS event itself will not cause any state transitions of the pipeline.

Returns

the new EOS event.

Allocate a new flush start event. The flush start event can be sent upstream and downstream and travels out-of-bounds with the dataflow.

It marks pads as being flushing and will make them return FlowReturn::Flushing when used for data flow with Pad::push, Pad::chain, Pad::get_range and Pad::pull_range. Any event (except a EventType::FlushStop) received on a flushing pad will return false immediately.

Elements should unlock any blocking functions and exit their streaming functions as fast as possible when this event is received.

This event is typically generated after a seek to flush out all queued data in the pipeline so that the new media is played as soon as possible.

Returns

a new flush start event.

Allocate a new flush stop event. The flush stop event can be sent upstream and downstream and travels serialized with the dataflow. It is typically sent after sending a FLUSH_START event to make the pads accept data again.

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 instant-rate-change event. This event is sent by seek handlers (e.g. demuxers) when receiving a seek with the SeekFlags::InstantRateChange and signals to downstream elements that the playback rate in the existing segment should be immediately multiplied by the rate_multiplier factor.

The flags provided replace any flags in the existing segment, for the flags within the GST_SEGMENT_INSTANT_FLAGS set. Other GstSegmentFlags are ignored and not transferred in the event.

Feature: v1_18

rate_multiplier

the multiplier to be applied to the playback rate

new_flags

A new subset of segment flags to replace in segments

Returns

the new instant-rate-change event.

Create a new instant-rate-sync-time event. This event is sent by the pipeline to notify elements handling the instant-rate-change event about the running-time when the new rate should be applied. The running time may be in the past when elements handle this event, which can lead to switching artifacts. The magnitude of those depends on the exact timing of event delivery to each element and the magnitude of the change in playback rate being applied.

The running_time and upstream_running_time are the same if this is the first instant-rate adjustment, but will differ for later ones to compensate for the accumulated offset due to playing at a rate different to the one indicated in the playback segments.

Feature: v1_18

rate_multiplier

the new playback rate multiplier to be applied

running_time

Running time when the rate change should be applied

upstream_running_time

The upstream-centric running-time when the rate change should be applied.

Returns

the new instant-rate-sync-time 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

the step rate

flush

flushing steps

intermediate

intermediate steps

Returns

a new Event

Create a new STREAM_COLLECTION event. The stream collection event can only travel downstream synchronized with the buffer flow.

Source elements, demuxers and other elements that manage collections of streams and post StreamCollection messages on the bus also send this event downstream on each pad involved in the collection, so that activation of a new collection can be tracked through the downstream data flow.

Feature: v1_10

collection

Active collection for this data flow

Returns

the new STREAM_COLLECTION event.

Create a new Stream Group Done event. The stream-group-done event can only travel downstream synchronized with the buffer flow. Elements that receive the event on a pad should handle it mostly like EOS, and emit any data or pending buffers that would depend on more data arriving and unblock, since there won't be any more data.

This event is followed by EOS at some point in the future, and is generally used when switching pads - to unblock downstream so that new pads can be exposed before sending EOS on the existing pads.

Feature: v1_10

group_id

the group id of the stream group which is ending

Returns

the new stream-group-done event.

Create a new STREAM_START event. The stream start event can only travel downstream synchronized with the buffer flow. It is expected to be the first event that is sent for a new stream.

Source elements, demuxers and other elements that create new streams are supposed to send this event as the first event of a new stream. It should not be sent after a flushing seek or in similar situations and is used to mark the beginning of a new logical stream. Elements combining multiple streams must ensure that this event is only forwarded downstream once and not for every single input stream.

The stream_id should be a unique string that consists of the upstream stream-id, / as separator and a unique stream-id for this specific stream. A new stream-id should only be created for a stream if the upstream stream is split into (potentially) multiple new streams, e.g. in a demuxer, but not for every single element in the pipeline. PadExt::create_stream_id or PadExt::create_stream_id_printf can be used to create a stream-id. There are no particular semantics for the stream-id, though it should be deterministic (to support stream matching) and it might be used to order streams (besides any information conveyed by stream flags).

stream_id

Identifier for this stream

Returns

the new STREAM_START event.

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.

Copy the event using the event specific copy function.

Returns

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

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

Feature: v1_18

name

name to check as a GQuark

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.

Extract rate and flags from an instant-rate-change event.

Feature: v1_18

rate_multiplier

location in which to store the rate multiplier of the instant-rate-change event, or None

new_flags

location in which to store the new segment flags of the instant-rate-change event, or None

Extract the rate multiplier and running times from an instant-rate-sync-time event.

Feature: v1_18

rate_multiplier

location where to store the rate of the instant-rate-sync-time event, or None

running_time

location in which to store the running time of the instant-rate-sync-time event, or None

upstream_running_time

location in which to store the upstream running time of the instant-rate-sync-time event, or None

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

Retrieve the trickmode interval that may have been set on a seek event with Event::set_seek_trickmode_interval.

Feature: v1_16

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

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

Increase the refcount of this event.

Returns

self (for convenience when doing assignments)

All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the same group id but different stream ids. The group id should change each time the stream is started, resulting in different group ids each time a file is played for example.

Use gst_util_group_id_next to get a new group id.

group_id

the group id to set

Set the running time offset of a event. See Event::get_running_time_offset for more information.

MT safe.

offset

A the new running time offset

Sets a trickmode interval on a (writable) seek event. Elements that support TRICKMODE_KEY_UNITS seeks SHOULD use this as the minimal interval between each frame they may output.

Feature: v1_16

Set the sequence number of a event.

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

MT safe.

seqnum

A sequence number.

Set the stream on the stream-start self

Feature: v1_10

stream

the stream object to set

flags

the stream flags to set

Decrease the refcount of an event, freeing it if the refcount reaches 0.

Get a writable version of the structure.

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. This function checks if self is writable and will never return None.

MT safe.

Modifies a pointer to a Event to point to a different Event. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old event is unreffed, the new one is reffed).

Either new_event or the Event pointed to by old_event may be None.

old_event

pointer to a pointer to a Event to be replaced.

new_event

pointer to a Event that will replace the event pointed to by old_event.

Returns

true if new_event was different from old_event

Atomically replace the Event pointed to by old_event with None and return the original event.

old_event

pointer to a pointer to a Event to be stolen.

Returns

the Event that was in old_event

Modifies a pointer to a Event to point to a different Event. This function is similar to Event::replace except that it takes ownership of new_event.

Either new_event or the Event pointed to by old_event may be None.

old_event

pointer to a pointer to a Event to be stolen.

new_event

pointer to a Event that will replace the event pointed to by old_event.

Returns

true if new_event was different from old_event

EventType lists the standard event types that can be sent in a pipeline.

The custom event types can be used for private messages between elements that can't be expressed using normal GStreamer buffer passing semantics. Custom events carry an arbitrary Structure. Specific custom events are distinguished by the name of the structure.

unknown event.

Start a flush operation. This event clears all data from the pipeline and unblock all streaming threads.

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.

Notify downstream that a playback rate override should be applied as soon as possible. (Since: 1.18)

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)

Sent by the pipeline to notify elements that handle the instant-rate-change event about the running-time when the rate multiplier should be applied (or was applied). (Since: 1.18)

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, ProxyPadExtManual, PadExtManual

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

Deprecated

This function is deprecated since 1.18 and does nothing anymore.

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.

Flags for wrapped memory.

memory is readonly. It is not allowed to map the memory with MapFlags::Write.

memory must not be shared. Copies will have to be made when this memory needs to be shared between buffers.

the memory prefix is filled with 0 bytes

the memory padding is filled with 0 bytes

the memory is physically contiguous. (Since: 1.2)

the memory can't be mapped via Memory::map without any preconditions. (Since: 1.2)

first flag that can be used for custom purposes

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());

A Element usually posts messages on the bus provided by the parent container using Element::post_message.

Create a new application-typed message. GStreamer will never create these messages; they are a gift from us to you. Enjoy.

src

The object originating the message.

structure

the structure for the message. The message will take ownership of the structure.

Returns

The new application message.

MT safe.

The message is posted when elements completed an ASYNC state change. running_time contains the time of the desired running_time when this elements goes to PLAYING. A value of GST_CLOCK_TIME_NONE for running_time means that the element has no clock interaction and thus doesn't care about the running_time of the pipeline.

src

The object originating the message.

running_time

the desired running_time

Returns

The new async_done message.

MT safe.

This message is posted by elements when they start an ASYNC state change.

src

The object originating the message.

Returns

The new async_start message.

MT safe.

Create a new buffering message. This message can be posted by an element that needs to buffer data before it can continue processing. percent should be a value between 0 and 100. A value of 100 means that the buffering completed.

When percent is < 100 the application should PAUSE a PLAYING pipeline. When percent is 100, the application can set the pipeline (back) to PLAYING. The application must be prepared to receive BUFFERING messages in the PREROLLING state and may only set the pipeline to PLAYING after receiving a message with percent set to 100, which can happen after the pipeline completed prerolling.

MT safe.

src

The object originating the message.

percent

The buffering percent

Returns

The new buffering message.

Create a clock lost message. This message is posted whenever the clock is not valid anymore.

If this message is posted by the pipeline, the pipeline will select a new clock again when it goes to PLAYING. It might therefore be needed to set the pipeline to PAUSED and PLAYING again.

src

The object originating the message.

clock

the clock that was lost

Returns

The new clock lost message.

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

This message is mainly used internally to manage the clock selection.

src

The object originating the message.

clock

the clock it provides

ready

true if the sender can provide a clock

Returns

the new provide clock message.

MT safe.

Create a new custom-typed message. This can be used for anything not handled by other message-specific functions to pass a message to the app. The structure field can be None.

type_

The MessageType to distinguish messages

src

The object originating the message.

structure

the structure for the message. The message will take ownership of the structure.

Returns

The new message.

MT safe.

Creates a new device-added message. The device-added message is produced by DeviceProvider or a DeviceMonitor. They announce the appearance of monitored devices.

src

The Object that created the message

device

The new Device

Returns

a newly allocated Message

Creates a new device-changed message. The device-changed message is produced by DeviceProvider or a DeviceMonitor. They announce that a device properties has changed and device represent the new modified version of changed_device.

Feature: v1_16

src

The Object that created the message

device

The newly created device representing replaced_device with its new configuration.

Returns

a newly allocated Message

Creates a new device-removed message. The device-removed message is produced by DeviceProvider or a DeviceMonitor. They announce the disappearance of monitored devices.

src

The Object that created the message

device

The removed Device

Returns

a newly allocated Message

Create a new duration changed message. This message is posted by elements that know the duration of a stream when the duration changes. This message is received by bins and is used to calculate the total duration of a pipeline.

src

The object originating the message.

Returns

The new duration-changed message.

MT safe.

Create a new element-specific message. This is meant as a generic way of allowing one-way communication from an element to an application, for example "the firewire cable was unplugged". The format of the message should be documented in the element's documentation. The structure field can be None.

src

The object originating the message.

structure

The structure for the message. The message will take ownership of the structure.

Returns

The new element message.

MT safe.

Create a new eos message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the EOS message to the application if all sinks have posted an EOS message.

src

The object originating the message.

Returns

The new eos message.

MT safe.

Create a new error message. The message will copy error and debug. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline.

src

The object originating the message.

error

The GError for this message.

debug

A debugging string.

Returns

the new error message.

MT safe.

Create a new error message. The message will copy error and debug. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline.

Feature: v1_10

src

The object originating the message.

error

The GError for this message.

debug

A debugging string.

details

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

A GstStructure with details

Returns

the new warning message.

Creates a new instant-rate-request message. Elements handling the instant-rate-change event must post this message. The message is handled at the pipeline, and allows the pipeline to select the running time when the rate change should happen and to send an EventType::InstantRateSyncTime event to notify the elements in the pipeline.

Feature: v1_18

src

The Object that posted the message

rate_multiplier

the rate multiplier factor that should be applied

Returns

a newly allocated Message

This message can be posted by elements when their latency requirements have changed.

src

The object originating the message.

Returns

The new latency message.

MT safe.

This message is posted when an element needs a specific Context.

src

The object originating the message.

context_type

The context type that is needed

Returns

The new need-context message.

MT safe.

Create a new clock message. This message is posted whenever the pipeline selects a new clock for the pipeline.

src

The object originating the message.

clock

the new selected clock

Returns

The new new clock message.

MT safe.

Progress messages are posted by elements when they use an asynchronous task to perform actions triggered by a state change.

code contains a well defined string describing the action. text should contain a user visible string detailing the current action.

src

The object originating the message.

type_

a ProgressType

code

a progress code

text

free, user visible text describing the progress

Returns

The new qos message.

Feature: v1_10

src

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

property_name

name of the property that changed

val

new property value, or None

Returns

a newly allocated Message

A QOS message is posted on the bus whenever an element decides to drop a buffer because of QoS reasons or whenever it changes its processing strategy because of QoS reasons (quality adjustments such as processing at lower accuracy).

This message can be posted by an element that performs synchronisation against the clock (live) or it could be dropped by an element that performs QoS because of QOS events received from a downstream element (!live).

running_time, stream_time, timestamp, duration should be set to the respective running-time, stream-time, timestamp and duration of the (dropped) buffer that generated the QoS event. Values can be left to GST_CLOCK_TIME_NONE when unknown.

src

The object originating the message.

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

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

Returns

a newly allocated Message

This message can be posted by elements when they want to have their state changed. A typical use case would be an audio server that wants to pause the pipeline because a higher priority stream is being played.

src

The object originating the message.

state

The new requested state

Returns

the new request state message.

MT safe.

This message is posted when the pipeline running-time should be reset to running_time, like after a flushing seek.

src

The object originating the message.

running_time

the requested running-time

Returns

The new reset_time message.

MT safe.

Create a new segment done message. This message is posted by elements that finish playback of a segment as a result of a segment seek. This message is received by the application after all elements that posted a segment_start have posted the segment_done.

src

The object originating the message.

format

The format of the position being done

position

The position of the segment being done

Returns

the new segment done message.

MT safe.

Create a new segment message. This message is posted by elements that start playback of a segment as a result of a segment seek. This message is not received by the application but is used for maintenance reasons in container elements.

src

The object originating the message.

format

The format of the position being played

position

The position of the segment being played

Returns

the new segment start message.

MT safe.

Create a state change message. This message is posted whenever an element changed its state.

src

The object originating the message.

oldstate

the previous state

newstate

the new (current) state

pending

the pending (target) state

Returns

the new state change message.

MT safe.

Create a state dirty message. This message is posted whenever an element changed its state asynchronously and is used internally to update the states of container objects.

src

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

is this an flushing step

intermediate

is this an intermediate step

Returns

The new step_start message.

MT safe.

Creates a new stream-collection message. The message is used to announce new StreamCollection

Feature: v1_10

src

The Object that created the message

collection

The StreamCollection

Returns

a newly allocated Message

Create a new stream_start message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the STREAM_START message to the application if all sinks have posted an STREAM_START message.

src

The object originating the message.

Returns

The new stream_start message.

MT safe.

Create a new stream status message. This message is posted when a streaming thread is created/destroyed or when the state changed.

src

The object originating the message.

type_

The stream status type.

owner

the owner element of src.

Returns

the new stream status message.

MT safe.

Creates a new steams-selected message. The message is used to announce that an array of streams has been selected. This is generally in response to a EventType::SelectStreams event, or when an element (such as decodebin3) makes an initial selection of streams.

The message also contains the StreamCollection to which the various streams belong to.

Users of Message::new_streams_selected can add the selected streams with Message::streams_selected_add.

Feature: v1_10

src

The Object that created the message

collection

The StreamCollection

Returns

a newly allocated Message

Create a new structure change message. This message is posted when the structure of a pipeline is in the process of being changed, for example when pads are linked or unlinked.

src should be the sinkpad that unlinked or linked.

src

The object originating the message.

type_

The change type.

owner

The owner element of src.

busy

Whether the structure change is busy.

Returns

the new structure change message.

MT safe.

Create a new tag message. The message will take ownership of the tag list. The message is posted by elements that discovered a new taglist.

src

The object originating the message.

tag_list

the tag list for the message.

Returns

the new tag message.

MT safe.

Create a new TOC message. The message is posted by elements that discovered or updated a TOC.

src

the object originating the message.

toc

Toc structure for the message.

updated

whether TOC was updated or not.

Returns

a new TOC message.

MT safe.

Create a new warning 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 warning message.

MT safe.

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

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

Creates a copy of the message. Returns a copy of the message.

Returns

a new copy of self.

MT safe

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-changed message. The device-changed message is produced by DeviceProvider or a DeviceMonitor. It announces the disappearance of monitored devices. * It announce that a device properties has changed and device represents the new modified version of changed_device.

Feature: v1_16

device

A location where to store a pointer to the updated version of the Device, or None

changed_device

A location where to store a pointer to the old version of the 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.

Feature: v1_10

structure

A pointer to the returned details

Extract the group from the STREAM_START message.

group_id

Result location for the group id or None

Returns

true if the message had a group id set, false otherwise

MT safe.

Extract the context from the HAVE_CONTEXT message.

MT safe.

context

Result location for the context 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.

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.

Feature: v1_10

structure

A pointer to the returned details structure

Parses the rate_multiplier from the instant-rate-request message.

Feature: v1_18

rate_multiplier

return location for the rate, or None

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.

MT safe.

running_time

Result location for the running_time or None

Extracts the position and format from the segment done message.

MT safe.

format

Result location for the format, or None

position

Result location for the position, or None

Extracts the position and format from the segment start message.

MT safe.

format

Result location for the format, or None

position

Result location for the position, or None

Extracts the old and new states from the GstMessage.

Typical usage of this function might be:

  ...
  switch (GST_MESSAGE_TYPE (msg)) {
    case GST_MESSAGE_STATE_CHANGED: {
      GstState old_state, new_state;

      gst_message_parse_state_changed (msg, &amp;old_state, &amp;new_state, NULL);
      g_print ("Element %s changed state from %s to %s.\n",
          GST_OBJECT_NAME (msg->src),
          gst_element_state_get_name (old_state),
          gst_element_state_get_name (new_state));
      break;
    }
    ...
  }
  ...

MT safe.

oldstate

the previous state, or None

newstate

the new (current) state, or None

pending

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

result location for the rate

flush

result location for the flush flag

intermediate

result location for the intermediate flag

duration

result location for the duration

eos

result location for the EOS flag

Extract the values from step_start message.

MT safe.

active

result location for the active flag

format

result location for the format

amount

result location for the amount

rate

result location for the rate

flush

result location for the flush flag

intermediate

result location for the intermediate flag

Parses a stream-collection message.

Feature: v1_10

collection

A location where to store a pointer to the StreamCollection, or None

Extracts the stream status type and owner the GstMessage. The returned owner remains valid for as long as the reference to self is valid and should thus not be unreffed.

MT safe.

type_

A pointer to hold the status type

owner

The owner element of the message source

Parses a streams-selected message.

Feature: v1_10

collection

A location where to store a pointer to the StreamCollection, or None

Extracts the change type and completion status from the GstMessage.

MT safe.

type_

A pointer to hold the change type

owner

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

MT safe.

tag_list

return location for the tag-list.

Extract the TOC from the Message. The TOC returned in the output argument is a copy; the caller must free it with gst_toc_unref when done.

MT safe.

toc

return location for the TOC.

updated

return location for the updated flag.

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.

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.

Feature: v1_10

structure

A pointer to the returned details structure

Convenience macro to increase the reference count of the message.

Returns

self (for convenience when doing assignments)

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.

All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the same group id but different stream ids. The group id should change each time the stream is started, resulting in different group ids each time a file is played for example.

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

Convenience macro to decrease the reference count of the message, possibly freeing it.

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.

Modifies a pointer to a Message to point to a different Message. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old message is unreffed, the new one is reffed).

Either new_message or the Message pointed to by old_message may be None.

old_message

pointer to a pointer to a Message to be replaced.

new_message

pointer to a Message that will replace the message pointed to by old_message.

Returns

true if new_message was different from old_message

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 GstBinExt::add and ElementExt::add_pad take ownership of the floating reference.

In contrast to gobject::Object instances, Object adds a name property. The functions Object::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

Allocator, 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 string..

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

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

Returns a copy of the name of self. Caller should g_free the return value after usage. For a nameless object, this returns None, which you can safely g_free as well.

Free-function: g_free

Returns

the name of self. g_free after usage.

MT safe. This function grabs and releases self's LOCK.

Returns the parent of self. This function increases the refcount of the parent object so you should GstObjectExt::unref it after usage.

Returns

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

the new control-rate in nanoseconds.

Sets the name of self, or gives self a guaranteed unique name (if name is None). This function makes a copy of the provided name, so the caller retains ownership of the name it sent.

name

new name of object

Returns

true if the name could be set. Since Objects that have a parent cannot be renamed, this function returns false in those cases.

MT safe. This function grabs and releases self's LOCK.

Sets the parent of self to parent. The object's reference count will be incremented, and any floating reference will be removed (see Object::ref_sink).

parent

new parent of object

Returns

true if parent could be set or false when self already had a parent or self and parent are the same.

MT safe. Grabs and releases self's LOCK.

Returns a suggestion for timestamps where buffers should be split to get best controller results.

Returns

Returns the suggested timestamp or GST_CLOCK_TIME_NONE if no control-rate was set.

Sets the properties of the object, according to the GstControlSources that (maybe) handle them and for the given timestamp.

If this function fails, it is most likely the application developers fault. Most probably the control sources are not setup correctly.

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.

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.

The standard flags that an gstobject may have.

the object is expected to stay alive even after gst_deinit has been called and so should be ignored by leak detection tools. (Since: 1.10)

subclasses can add additional flags starting from this flag

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 Pad::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 Pad::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 Pad::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 Pad::start_task, PadExt::pause_task and PadExt::stop_task respectively.

Implements

PadExt, GstObjectExt, glib::object::ObjectExt, PadExtManual

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

a new Pad.

MT safe.

Creates a new pad with the given name from the given static template. 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.

templ

the StaticPadTemplate to use

name

the name of the pad

Returns

a new Pad.

Creates a new pad with the given name from the given template. 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.

templ

the pad template to use

name

the name of the pad

Returns

a new Pad.

Gets a string representing the given pad-link return.

ret

a PadLinkReturn to get the name of.

Returns

a static string with the name of the pad-link return.

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

Creates a stream-id for the source Pad self by combining the upstream information with the optional stream_id of the stream of self. self must have a parent Element and which must have zero or one sinkpad. stream_id can only be None if the parent element of self has only a single source pad.

This function generates an unique stream-id by getting the upstream stream-start event stream ID and appending stream_id to it. If the element has no sinkpad it will generate an upstream stream-id by doing an URI query on the element and in the worst case just uses a random number. Source elements that don't implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead.

Since stream IDs are sorted alphabetically, any numbers in the stream ID should be printed with a fixed number of characters, preceded by 0's, such as by using the format %03u instead of %u.

parent

Parent Element of self

stream_id

The stream-id

Returns

A stream-id for self. g_free after usage.

Creates a stream-id for the source Pad self by combining the upstream information with the optional stream_id of the stream of self. self must have a parent Element and which must have zero or one sinkpad. stream_id can only be None if the parent element of self has only a single source pad.

This function generates an unique stream-id by getting the upstream stream-start event stream ID and appending stream_id to it. If the element has no sinkpad it will generate an upstream stream-id by doing an URI query on the element and in the worst case just uses a random number. Source elements that don't implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead.

parent

Parent Element of self

stream_id

The stream-id

Returns

A stream-id for self. g_free after usage.

Creates a stream-id for the source Pad self by combining the upstream information with the optional stream_id of the stream of self. self must have a parent Element and which must have zero or one sinkpad. stream_id can only be None if the parent element of self has only a single source pad.

This function generates an unique stream-id by getting the upstream stream-start event stream ID and appending stream_id to it. If the element has no sinkpad it will generate an upstream stream-id by doing an URI query on the element and in the worst case just uses a random number. Source elements that don't implement the URI handler interface should ideally generate a unique, deterministic stream-id manually instead.

parent

Parent Element of self

stream_id

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 event is sent to all pads internally linked to self. This function takes ownership of event.

parent

the parent of self or None

event

the Event to handle.

Returns

true if the event was sent successfully.

Calls forward for all internally linked pads of self. This function deals with dynamically changing internal pads and will make sure that the forward function is only called once for each pad.

When forward returns true, no further pads will be processed.

forward

a GstPadForwardFunction

user_data

user data passed to forward

Returns

true if one of the dispatcher functions returned true.

Gets the capabilities of the allowed media types that can flow through self and its peer.

The allowed capabilities is calculated as the intersection of the results of calling PadExt::query_caps on self and its peer. The caller owns a reference on the resulting caps.

Returns

the allowed Caps of the pad link. Unref the caps when you no longer need it. This function returns None when self has no peer.

MT safe.

Gets the capabilities currently configured on self with the last EventType::Caps event.

Returns

the current caps of the pad with incremented ref-count or None when pad has no caps. Unref after usage.

Gets the direction of the pad. The direction of the pad is decided at construction time so this function does not take the LOCK.

Returns

the PadDirection of the pad.

MT safe.

Gets the private data of a pad. No locking is performed in this function.

Returns

a gpointer to the private data.

Gets the FlowReturn return from the last data passed by this pad.

Get the offset applied to the running time of self. self has to be a source pad.

Returns

the offset.

Gets the template for self.

Returns

the PadTemplate from which this pad was instantiated, or None if this pad has no template. Unref after usage.

Gets the capabilities for self's template.

Returns

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

If there is a single internal link of the given pad, this function will return it. Otherwise, it will return NULL.

Feature: v1_18

Returns

a Pad, or None if self has none or more than one internal links. Unref returned pad with GstObjectExt::unref.

Returns a new reference of the sticky event of type event_type from the event.

event_type

the EventType that should be retrieved.

idx

the index of the event

Returns

a Event of type event_type or None when no event of event_type was on self. Unref after usage.

Returns the current Stream for the self, or None if none has been set yet, i.e. the pad has not received a stream-start event yet.

This is a convenience wrapper around PadExt::get_sticky_event and Event::parse_stream.

Feature: v1_10

Returns

the current Stream for self, or None. unref the returned stream when no longer needed.

Returns the current stream-id for the self, or None if none has been set yet, i.e. the pad has not received a stream-start event yet.

This is a convenience wrapper around PadExt::get_sticky_event and Event::parse_stream_start.

The returned stream-id string should be treated as an opaque string, its contents should not be interpreted.

Returns

a newly-allocated copy of the stream-id for self, or None. g_free the returned string when no longer needed.

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.

Returns

true when self has caps associated with it.

Query if a pad is active

Returns

true if the pad is active.

MT safe.

Checks if the pad is blocked or not. This function returns the last requested state of the pad. It is not certain that the pad is actually blocking at this point (see PadExt::is_blocking).

Returns

true if the pad is blocked.

MT safe.

Checks if the pad is blocking or not. This is a guaranteed state of whether the pad is actually blocking on a Buffer or a Event.

Returns

true if the pad is blocking.

MT safe.

Checks if a self is linked to another pad or not.

Returns

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

Pause the task of self. This function will also wait until the function executed by the task is finished if this function is not called from the task function.

Returns

a true if the task could be paused or false when the pad has no task.

Performs Pad::query on the peer of self.

The caller is responsible for both the allocation and deallocation of the query structure.

query

the Query to perform.

Returns

true if the query could be performed. This function returns false if self has no peer.

Check if the peer of self accepts caps. If self has no peer, this function returns true.

caps

a Caps to check on the pad

Returns

true if the peer of self can accept the caps or self has no peer.

Gets the capabilities of the peer connected to this pad. Similar to PadExt::query_caps.

When called on srcpads filter contains the caps that upstream could produce in the order preferred by upstream. When called on sinkpads 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.

filter

a Caps filter, or None.

Returns

the caps of the peer pad with incremented ref-count. When there is no peer pad, this function returns filter or, when filter is None, ANY caps.

Queries the peer pad of a given sink 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.

Queries the peer pad of a given sink pad for the total stream duration.

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 the peer of a given sink pad for the stream position.

format

the Format requested

cur

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

Returns

true if the query could be performed.

Checks if all internally linked pads of self accepts the caps in query and returns the intersection of the results.

This function is useful as a default accept caps query function for an element that can handle any stream format, but requires caps that are acceptable for all opposite pads.

query

an ACCEPT_CAPS Query.

Returns

true if query could be executed

Calls PadExt::query_caps for all internally linked pads of self and returns the intersection of the results.

This function is useful as a default caps query function for an element that can handle any stream format, but requires all its pads to have the same caps. Two such elements are tee and adder.

query

a CAPS Query.

Returns

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.

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 Buffer::unref after usage. When this function returns any other result value, buffer will still point to None.

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.

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.

offset

The start offset of the buffer

size

The length of the buffer

buffer

a pointer to hold the Buffer, returns GST_FLOW_ERROR if None.

Returns

a FlowReturn from the peer pad.

MT safe.

Pushes a buffer to the peer of self.

This function will call installed block probes before triggering any installed data probes.

The function proceeds calling Pad::chain on the peer pad and returns the value from that function. If self has no peer, FlowReturn::NotLinked will be returned.

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

buffer

the Buffer to push returns GST_FLOW_ERROR if not.

Returns

a FlowReturn from the peer pad.

MT safe.

Sends the event to the peer of the given pad. This function is mainly used by elements to send events to their peer elements.

This function takes ownership of the provided event so you should 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.

MT safe.

Pushes a buffer list to the peer of self.

This function will call installed block probes before triggering any installed data probes.

The function proceeds calling the chain function on the peer pad and returns the value from that function. If self has no peer, FlowReturn::NotLinked will be returned. If the peer pad does not have any installed chainlist function every group buffer of the list will be merged into a normal Buffer and chained via Pad::chain.

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

list

the BufferList to push returns GST_FLOW_ERROR if not.

Returns

a FlowReturn from the peer pad.

MT safe.

Dispatches a query to a pad. The query should have been allocated by the caller via one of the type-specific allocation functions. The element that the pad belongs to is responsible for filling the query with an appropriate response, which should then be parsed with a type-specific query parsing function.

Again, the caller is responsible for both the allocation and deallocation of the query structure.

Please also note that some queries might need a running pipeline to work.

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.

Invokes the default query handler for the given pad. The query is sent to all pads internally linked to self. Note that if there are many possible sink pads that are internally linked to self, only one will be sent the query. Multi-sinkpad elements should implement custom query handlers.

parent

the parent of self or None

query

the Query to handle.

Returns

true if the query was performed successfully.

Queries a pad for the total stream duration.

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 a pad for the stream position.

format

the Format requested

cur

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

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

user_data passed to notify

notify

notify called when get will not be used anymore.

Sets the given internal link iterator function for the pad.

the GstPadIterIntLinkFunction to set.

user_data

user_data passed to notify

notify

notify called when iterintlink will not be used anymore.

Sets the given link function for the pad. It will be called when the pad is linked with another pad.

The return value PadLinkReturn::Ok should be used when the connection can be made.

The return value PadLinkReturn::Refused should be used when the connection cannot be made for some reason.

If link is installed on a source pad, it should call the GstPadLinkFunction of the peer sink pad, if present.

the GstPadLinkFunction to set.

user_data

user_data passed to notify

notify

notify called when link will not be used anymore.

Set the offset that will be applied to the running time of self.

offset

the offset

Set the given query function for the pad.

query

the GstPadQueryFunction to set.

user_data

user_data passed to notify

notify

notify called when query will not be used anymore.

Sets the given unlink function for the pad. It will be called when the pad is unlinked.

Note that the pad's lock is already held when the unlink function is called, so most pad functions cannot be called from within the callback.

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

Pad state flags

is dataflow on a pad blocked

is pad flushing

is pad in EOS state

is pad currently blocking on a buffer or event

ensure that there is a parent object before calling into the pad callbacks.

the pad should be reconfigured/renegotiated. The flag has to be unset manually after reconfiguration happened.

the pad has pending events

the pad is using fixed caps. This means that once the caps are set on the pad, the default caps query function will only return those caps.

the default event and query handler will forward all events and queries to the internally linked pads instead of discarding them.

the default query handler will forward allocation queries to the internally linked pads instead of discarding them.

the default query handler will forward scheduling queries to the internally linked pads instead of discarding them.

the default accept-caps handler will check it the caps intersect the query-caps result instead of checking for a subset. This is interesting for parsers that can accept incompletely specified caps.

the default accept-caps handler will use the template pad caps instead of query caps to compare with the accept caps. Use this in combination with PadFlags::AcceptIntersect. (Since: 1.6)

offset to define more flags

The amount of checking to be done when linking pads. PadLinkCheck::Caps and PadLinkCheck::TemplateCaps are mutually exclusive. If both are specified, expensive but safe PadLinkCheck::Caps are performed.

Only disable some of the checks if you are 100% certain you know the link will not fail because of hierarchy/caps compatibility failures. If uncertain, use the default checks (PadLinkCheck::Default) or the regular methods for linking the pads.

Don't check hierarchy or caps compatibility.

Check the pads have same parents/grandparents. Could be omitted if it is already known that the two elements that own the pads are in the same bin.

Check if the pads are compatible by using their template caps. This is much faster than PadLinkCheck::Caps, but would be unsafe e.g. if one pad has GST_CAPS_ANY.

Check if the pads are compatible by comparing the caps returned by PadExt::query_caps.

Disables pushing a reconfigure event when pads are linked.

The default checks done when linking pads (i.e. the ones used by Pad::link).

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

The different probing types that can occur. When either one of PadProbeType::Idle or PadProbeType::Block is used, the probe will be a blocking probe.

invalid probe type

probe idle pads and block while the callback is called

probe and block pads

probe buffers

probe buffer lists

probe downstream events

probe upstream events

probe flush events. This probe has to be explicitly enabled and is not included in the @PadProbeType::EventDownstream or @PadProbeType::EventUpstream probe types.

probe downstream queries

probe upstream queries

probe push

probe pull

probe and block at the next opportunity, at data flow or when idle

probe downstream data (buffers, buffer lists, and events)

probe upstream data (events)

probe upstream and downstream data (buffers, buffer lists, and events)

probe and block downstream data (buffers, buffer lists, and events)

probe and block upstream data (events)

probe upstream and downstream events

probe upstream and downstream queries

probe upstream events and queries and downstream buffers, buffer lists, events and queries

probe push and pull

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.

See PadTemplate::set_documentation_caps.

Feature: v1_18

Returns

The caps to document. For convenience, this will return PadTemplate::get_caps when no documentation caps were set.

Emit the pad-created signal for this template when created by this pad.

pad

the Pad that created it

Certain elements will dynamically construct the caps of their pad templates. In order not to let environment-specific information into the documentation, element authors should use this method to expose "stable" caps to the reader.

Feature: v1_18

caps

the documented capabilities

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 capabilities of the pad described by the pad template.

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

The name template of the pad template.

When the pad described by the pad template will become available.

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.

Feature: v1_12_1

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.

Parsing options.

Do not use any special parsing options.

Always return None when an error occurs (default behaviour is to return partially constructed bins or elements in some cases)

If a bin only has a single element, just return the element.

If more than one toplevel element is described by the pipeline description string, put them in a Bin instead of a Pipeline. (Since: 1.10)

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 GstBinExt::add and GstBinExt::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 Element::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, GstBinExt, ElementExt, GstObjectExt, glib::object::ObjectExt, ChildProxyExt, ElementExtManual, ChildProxyExtManual

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.

Returns

a Clock, unref after usage.

Get the configured delay (see PipelineExt::set_delay).

Returns

The configured delay.

MT safe.

Gets the latency that should be configured on the pipeline. See PipelineExt::set_latency.

Returns

Latency to configure on the pipeline or GST_CLOCK_TIME_NONE

Gets the current clock used by self.

Unlike ElementExt::get_clock, this function will always return a clock, even if the pipeline is not in the PLAYING state.

Returns

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.

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.

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.

Latency to configure on the pipeline. See PipelineExt::set_latency.

Pipeline flags

this pipeline works with a fixed clock

offset to define more flags

GStreamer is extensible, so Element instances can be loaded at runtime. A plugin system can provide one or more of the basic GStreamer PluginFeature subclasses.

A plugin should export a symbol gst_plugin_desc 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 gst_plugin_desc.

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

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

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.

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

optional flags, or PluginDependencyFlags::None

Gets the plugin specific data cache. If it is None there is no cached data stored. This is the case when the registry is getting rebuilt.

Returns

The cached data as a Structure or None.

Get the long descriptive name of the plugin

Returns

the long name of the plugin

get the filename of the plugin

Returns

the filename of the plugin

get the license of the plugin

Returns

the license of the plugin

Get the short name of the plugin

Returns

the name of the plugin

get the URL where the plugin comes from

Returns

the origin of the plugin

get the package the plugin belongs to.

Returns

the package of the plugin

Get the release date (and possibly time) in form of a string, if available.

For normal GStreamer plugin releases this will usually just be a date in the form of "YYYY-MM-DD", while pre-releases and builds from git may contain a time component after the date as well, in which case the string will be formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z").

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

Ignore enum members when generating the plugins cache. This is useful if the members of the enum are generated dynamically, in order not to expose incorrect documentation to the end user.

Feature: v1_18

Flags used in connection with Plugin::add_dependency.

no special flags

recurse into subdirectories

use paths argument only if none of the environment variables is set

interpret filename argument as filter suffix and check all matching files in the directory

interpret filename argument as filter prefix and check all matching files in the directory. Since: 1.8.

interpret non-absolute paths as relative to the main executable directory. Since 1.14.

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, PluginFeatureExtManual

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

the plugin that provides this feature, or None. Unref with GstObjectExt::unref when no longer needed.

Get the name of the plugin that provides this feature.

Returns

the name of the plugin that provides this feature, or None if the feature is not associated with a plugin.

Gets the rank of a plugin feature.

Returns

The rank of the feature

Loads the plugin containing self if it's not already loaded. self is unaffected; use the return value instead.

Normally this function is used like this:

GstPluginFeature *loaded_feature;

loaded_feature = gst_plugin_feature_load (feature);
// presumably, we're no longer interested in the potentially-unloaded feature
gst_object_unref (feature);
feature = loaded_feature;

Returns

a reference to the loaded feature, or None on error

Specifies a rank for a plugin feature, so that autoplugging uses the most appropriate feature.

rank

rank value - higher number means more priority rank

The plugin loading state

Temporarily loaded plugins

The plugin won't be scanned (again)

This interface offers methods to query and manipulate parameter preset sets. A preset is a bunch of property settings, together with meta data and a name. The name of a preset serves as key for subsequent method calls to manipulate single presets. All instances of one type will share the list of presets. The list is created on demand, if presets are not used, the list is not created.

The interface comes with a default implementation that serves most plugins. Wrapper plugins will override most methods to implement support for the native preset format of those wrapped plugins. One method that is useful to be overridden is Preset::get_property_names. With that one can control which properties are saved and in which order. When implementing support for read-only presets, one should set the vmethods for Preset::save_preset and Preset::delete_preset to None. Applications can use Preset::is_editable to check for that.

The default implementation supports presets located in a system directory, application specific directory and in the users home directory. When getting a list of presets individual presets are read and overlaid in 1) system, 2) application and 3) user order. Whenever an earlier entry is newer, the later entries will be updated. Since 1.8 you can also provide extra paths where to find presets through the GST_PRESET_PATH environment variable. Presets found in those paths will be considered as "app presets".

Implements

PresetExt

Trait containing all Preset methods.

Implementors

Preset

Gets the directory for application specific presets if set by the application.

Returns

the directory or None, don't free or modify the string

Sets an extra directory as an absolute path that should be considered when looking for presets. Any presets in the application dir will shadow the system presets.

app_dir

the application specific preset dir

Returns

true for success, false if the dir already has been set

Delete the given preset.

name

preset name to remove

Returns

true for success, false if e.g. there is no preset with that name

Gets the value for an existing meta data tag. Meta data tag names can be something like e.g. "comment". Returned values need to be released when done.

name

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

Renames a preset. If there is already a preset by the new_name it will be overwritten.

old_name

current preset name

new_name

new preset name

Returns

true for success, false if e.g. there is no preset with old_name

Save the current object settings as a preset under the given name. If there is already a preset by this name it will be overwritten.

name

preset name to save

Returns

true for success, false

Sets a new value for an existing meta data item or adds a new item. Meta data tag names can be something like e.g. "comment". Supplying None for the value will unset an existing value.

name

preset name

tag

meta data item name

value

new value

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. 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. The exact value returned is defined by the API contract of the producer and None may be a valid 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:

  1. That Promise::reply and Promise::interrupt cannot be called after Promise::expire
  2. 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.

Feature: v1_14

Feature: v1_14

Returns

a new Promise

func will be called exactly once when transitioning out of PromiseResult::Pending into any of the other PromiseResult states.

Feature: v1_14

func

a GstPromiseChangeFunc to call

user_data

argument to call func with

notify

notification function that user_data is no longer needed

Returns

a new Promise

Expire a self. This will wake up any waiters with PromiseResult::Expired. Called by a message loop when the parent message is handled and/or destroyed (possibly unanswered).

Feature: v1_14

Retrieve the reply set on self. self must be in PromiseResult::Replied and the returned structure is owned by self

Feature: v1_14

Returns

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

ProxyPadExt, PadExt, GstObjectExt, glib::object::ObjectExt, ProxyPadExtManual, PadExtManual

Trait containing all ProxyPad methods.

Implementors

GhostPad, ProxyPad

Invoke the default chain function of the proxy pad.

pad

a sink Pad, returns GST_FLOW_ERROR if not.

parent

the parent of pad or None

buffer

the Buffer to send, return GST_FLOW_ERROR if not.

Returns

a FlowReturn from the pad.

Invoke the default chain list function of the proxy pad.

pad

a sink Pad, returns GST_FLOW_ERROR if not.

parent

the parent of pad or None

list

the BufferList to send, return GST_FLOW_ERROR if not.

Returns

a FlowReturn from the pad.

Invoke the default getrange function of the proxy pad.

pad

a src Pad, returns FlowReturn::Error if not.

parent

the parent of pad

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: Query::unref

caps

a fixed Caps

Returns

a new Query

Constructs a new query object for querying the allocation properties.

Free-function: Query::unref

caps

the negotiated caps

need_pool

return a pool

Returns

a new Query

Constructs a new query object for querying the bitrate.

Free-function: Query::unref

Feature: v1_16

Returns

a new Query

Constructs a new query object for querying the buffering status of a stream.

Free-function: 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: Query::unref

filter

a filter

Returns

a new Query

Constructs a new query object for querying the pipeline-local context.

Free-function: Query::unref

context_type

Context type to query

Returns

a new Query

Constructs a new convert query object. Use Query::unref when done with it. A convert query is used to ask for a conversion between one format and another.

Free-function: Query::unref

src_format

the source Format for the new query

value

the value to convert

dest_format

the target Format

Returns

a Query

Constructs a new custom query object. Use Query::unref when done with it.

Free-function: Query::unref

type_

the query type

structure

a structure for the query

Returns

a new Query

Constructs a new query object for querying the drain state.

Free-function: Query::unref

Returns

a new Query

Constructs a new stream duration query object to query in the given format. Use Query::unref when done with it. A duration query will give the total length of the stream.

Free-function: Query::unref

format

the Format for this duration query

Returns

a new Query

Constructs a new query object for querying formats of the stream.

Free-function: Query::unref

Returns

a new Query

Constructs a new latency query object. Use 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: Query::unref

Returns

a Query

Constructs a new query stream position query object. Use 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: Query::unref

format

the default Format for the new query

Returns

a new Query

Constructs a new query object for querying the scheduling properties.

Free-function: Query::unref

Returns

a new Query

Constructs a new query object for querying seeking properties of the stream.

Free-function: Query::unref

format

the default Format for the new query

Returns

a new Query

Constructs a new segment query object. Use Query::unref when done with it. A segment query is used to discover information about the currently configured segment for playback.

Free-function: Query::unref

format

the Format for the new query

Returns

a new Query

Constructs a new query URI query object. Use Query::unref when done with it. An URI query is used to query the current URI that is used by the source or sink.

Free-function: Query::unref

Returns

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

Copies the given query using the copy function of the parent Structure.

Free-function: gst_query_unref

Returns

a new copy of self.

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.

Retrieve the number of values currently stored in the allocator params array of the query's structure.

If no memory allocator is specified, the downstream element can handle the default memory allocator. The first memory allocator in the query should be generic and allow mapping to system memory, all following allocators should be ordered by preference with the preferred one first.

Returns

the allocator array size as a guint.

Retrieve the number of values currently stored in the pool array of the query's structure.

Returns

the pool array size as a guint.

Retrieve the number of values currently stored in the buffered-ranges array of the query's structure.

Returns

the range array size as a guint.

Retrieve the number of values currently stored in the scheduling mode array of the query's structure.

Returns

the scheduling mode array size as a guint.

Get the structure of a query.

Returns

the Structure of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed.

Check if self has scheduling mode set.

When checking if upstream supports pull mode, it is usually not enough to just check for GST_PAD_MODE_PULL with this function, you also want to check whether the scheduling flags returned by Query::parse_scheduling have the seeking flag set (meaning random access is supported, not only sequential pulls).

mode

the scheduling mode

Returns

true when mode is in the list of scheduling modes.

Check if self has scheduling mode set and flags is set in query scheduling flags.

mode

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 results of a bitrate query. See also Query::set_bitrate.

Feature: v1_16

nominal_bitrate

The resulting bitrate in bits per second

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

start_value

the storage for the start value, or None

stop_value

the storage for the stop value, or None

Parse an URI query, writing the URI into uri as a newly allocated string, if the respective parameters are non-None. Free the string with g_free after usage.

uri

the storage for the current URI (may be None)

Parse an URI query, writing the URI into uri as a newly allocated string, if the respective parameters are non-None. Free the string with g_free after usage.

uri

the storage for the redirect URI (may be None)

Parse an URI query, and set permanent to true if there is a redirection and it should be considered permanent. If a redirection is permanent, applications should update their internal storage of the URI, otherwise they should make all future requests to the original URI.

permanent

if the URI redirection is permanent (may be None)

Remove the metadata API at index of the metadata API array.

index

position in the metadata API array to remove

Remove the allocation param at index of the allocation param array.

index

position in the allocation param array to remove

Remove the allocation pool at index of the allocation pool array.

index

position in the allocation pool array to remove

Set result as the result for the self.

result

the result to set

Set the results of a bitrate query. The nominal bitrate is the average bitrate expected over the length of the stream as advertised in file headers (or similar).

Feature: v1_16

nominal_bitrate

the nominal bitrate in bits per second

Set 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

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

Decreases the refcount of the query. If the refcount reaches 0, the query will be freed.

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.

Modifies a pointer to a Query to point to a different Query. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old query is unreffed, the new one is reffed).

Either new_query or the Query pointed to by old_query may be None.

old_query

pointer to a pointer to a Query to be replaced.

new_query

pointer to a Query that will replace the query pointed to by old_query.

Returns

true if new_query was different from old_query

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.

Find a PluginFeature with name in self.

name

a PluginFeature name

Returns

a PluginFeature with its refcount incremented, use GstObjectExt::unref after usage.

MT safe.

Runs a filter against all plugins in the registry and returns a glib::List with the results. If the first flag is set, only the first match is returned (as a list with a single object). Every plugin is reffed; use Plugin::list_free after use, which will unref again.

filter

the filter to use

first

only return first match

user_data

user data passed to the filter function

Returns

a glib::List of Plugin. Use Plugin::list_free after usage.

MT safe.

Remove the feature from the registry.

MT safe.

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

info

a Structure, or None

Returns

the new Sample. Sample::unref after usage.

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

Returns

a new copy of self.

Get the buffer associated with self

Returns

the buffer of self or None when there is no buffer. The buffer remains valid as long as self is valid. If you need to hold on to it for longer than that, take a ref to the buffer with Buffer::ref.

Get the buffer list associated with self

Returns

the buffer list of self or None when there is no buffer list. The buffer list remains valid as long as self is valid. If you need to hold on to it for longer than that, take a ref to the buffer list with gst_mini_object_ref ().

Get the caps associated with self

Returns

the caps of self or None when there is no caps. The caps remain valid as long as self is valid. If you need to hold on to the caps for longer than that, take a ref to the caps with Caps::ref.

Get extra information associated with self.

Returns

the extra info of self. The info remains valid as long as self is valid.

Get the segment associated with self

Returns

the segment of self. The segment remains valid as long as self is valid.

Increases the refcount of the given sample by one.

Returns

self

Set the buffer associated with self. self must be writable.

Feature: v1_16

buffer

A Buffer

Set the buffer list associated with self. self must be writable.

buffer_list

a BufferList

Set the caps associated with self. self must be writable.

Feature: v1_16

caps

A Caps

Set the info structure associated with self. self must be writable, and info must not have a parent set already.

Feature: v1_16

info

A Structure

Set the segment associated with self. self must be writable.

Feature: v1_16

segment

A Segment

Decreases the refcount of the sample. If the refcount reaches 0, the sample will be freed.

The different scheduling flags.

if seeking is possible

if sequential access is recommended

if bandwidth is limited and buffering possible (since 1.2)

Flags to be used with Element::seek or Event::new_seek. All flags can be used together.

A non flushing seek might take some time to perform as the currently playing data in the pipeline will not be cleared.

An accurate seek might be slower for formats that don't have any indexes or timestamp markers in the stream. Specifying this flag might require a complete scan of the file in those cases.

When performing a segment seek: after the playback of the segment completes, no EOS will be emitted by the element that performed the seek, but a MessageType::SegmentDone message will be posted on the bus by the element. When this message is posted, it is possible to send a new seek event to continue playback. With this seek method it is possible to perform seamless looping or simple linear editing.

When only changing the playback rate and not the direction, the SeekFlags::InstantRateChange flag can be used for a non-flushing seek to signal that the rate change should be applied immediately. This requires special support in the seek handlers (e.g. demuxers) and any elements synchronizing to the clock, and in general can't work in all cases (for example UDP streaming where the delivery rate is controlled by a remote server). The instant-rate-change mode supports changing the trickmode-related GST_SEEK_ flags, but can't be used in conjunction with other seek flags that affect the new playback position - as the playback position will not be changing.

When doing fast forward (rate > 1.0) or fast reverse (rate < -1.0) trickmode playback, the SeekFlags::Trickmode flag can be used to instruct decoders and demuxers to adjust the playback rate by skipping frames. This can improve performance and decrease CPU usage because not all frames need to be decoded.

Beyond that, the SeekFlags::TrickmodeKeyUnits flag can be used to request that decoders skip all frames except key units, and SeekFlags::TrickmodeNoAudio flags can be used to request that audio decoders do no decoding at all, and simple output silence.

The SeekFlags::SnapBefore flag can be used to snap to the previous relevant location, and the SeekFlags::SnapAfter flag can be used to select the next relevant location. If SeekFlags::KeyUnit is specified, the relevant location is a keyframe. If both flags are specified, the nearest of these locations will be selected. If none are specified, the implementation is free to select whichever it wants.

The before and after here are in running time, so when playing backwards, the next location refers to the one that will played in next, and not the one that is located after in the actual source stream.

Also see part-seeking.txt in the GStreamer design documentation for more details on the meaning of these flags and the behaviour expected of elements that handle them.

no flag

flush pipeline

accurate position is requested, this might be considerably slower for some formats.

seek to the nearest keyframe. This might be faster but less accurate.

perform a segment seek.

when doing fast forward or fast reverse playback, allow elements to skip frames instead of generating all frames. (Since: 1.6)

Deprecated backward compatibility flag, replaced by SeekFlags::Trickmode

go to a location before the requested position, if SeekFlags::KeyUnit this means the keyframe at or before the requested position the one at or before the seek target.

go to a location after the requested position, if SeekFlags::KeyUnit this means the keyframe at of after the requested position.

go to a position near the requested position, if SeekFlags::KeyUnit this means the keyframe closest to the requested position, if both keyframes are at an equal distance, behaves like SeekFlags::SnapBefore.

when doing fast forward or fast reverse playback, request that elements only decode keyframes and skip all other content, for formats that have keyframes. (Since: 1.6)

when doing fast forward or fast reverse playback, request that audio decoder elements skip decoding and output only gap events or silence. (Since: 1.6)

When doing fast forward or fast reverse playback, request that elements only decode keyframes and forward predicted frames and skip all other content (for example B-Frames), for formats that have keyframes and forward predicted frames. (Since: 1.18)

Signals that a rate change should be applied immediately. Only valid if start/stop position are GST_CLOCK_TIME_NONE, the playback direction does not change and the seek is not flushing. (Since: 1.18)

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 format of the segment.

Checks for two segments being equal. Equality here is defined as perfect equality, including floating point values.

s1

a Segment structure.

Returns

true if the segments are equal, false otherwise.

Adjust the values in self so that offset is applied to all future running-time calculations.

format

the format of the segment.

offset

the offset to apply in the segment

Returns

true if the segment could be updated successfully. If false is returned, offset is not in self.

Convert running_time into a position in the segment so that Segment::to_running_time with that position returns running_time.

format

the format of the segment.

running_time

the running_time in the segment

Returns

the position in the segment for running_time. This function returns -1 when running_time is -1 or when it is not inside self.

Translate running_time to the segment position using the currently configured segment. Compared to Segment::position_from_running_time this function can return negative segment position.

This function is typically used by elements that need to synchronize buffers against the clock or each other.

running_time can be any value and the result of this function for values outside of the segment is extrapolated.

When 1 is returned, running_time resulted in a positive position returned in position.

When this function returns -1, the returned position was < 0, and the value in the position variable should be negated to get the real negative segment position.

format

the format of the segment.

running_time

the running-time

position

the resulting position in the segment

Returns

a 1 or -1 on success, 0 on failure.

Convert stream_time into a position in the segment so that Segment::to_stream_time with that position returns stream_time.

format

the format of the segment.

stream_time

the stream_time in the segment

Returns

the position in the segment for stream_time. This function returns -1 when stream_time is -1 or when it is not inside self.

Translate stream_time to the segment position using the currently configured segment. Compared to Segment::position_from_stream_time this function can return negative segment position.

This function is typically used by elements that need to synchronize buffers against the clock or each other.

stream_time can be any value and the result of this function for values outside of the segment is extrapolated.

When 1 is returned, stream_time resulted in a positive position returned in position.

When this function returns -1, the returned position should be negated to get the real negative segment position.

format

the format of the segment.

stream_time

the stream-time

position

the resulting position in the segment

Returns

a 1 or -1 on success, 0 on failure.

Adjust the start/stop and base values of self such that the next valid buffer will be one with running_time.

format

the format of the segment.

running_time

the running_time in the segment

Returns

true if the segment could be updated successfully. If false is returned, running_time is -1 or not in self.

Convert running_time into a position in the segment so that Segment::to_running_time with that position returns running_time.

Deprecated

Use Segment::position_from_running_time instead.

format

the format of the segment.

running_time

the running_time in the segment

Returns

the position in the segment for running_time. This function returns -1 when running_time is -1 or when it is not inside self.

Translate position to the total running time using the currently configured segment. Position is a value between self start and stop time.

This function is typically used by elements that need to synchronize to the global clock in a pipeline. The running time is a constantly increasing value starting from 0. When Segment::init is called, this value will reset to 0.

This function returns -1 if the position is outside of self start and stop.

format

the format of the segment.

position

the position in the segment

Returns

the position as the total running time or -1 when an invalid position was given.

Translate position to the total running time using the currently configured segment. Compared to Segment::to_running_time this function can return negative running-time.

This function is typically used by elements that need to synchronize buffers against the clock or each other.

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 running-time returned in running_time.

When this function returns -1, the returned running_time should be negated to get the real negative running time.

format

the format of the segment.

position

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

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.

Flags for the GstSegment structure. Currently mapped to the corresponding values of the seek flags.

no flags

reset the pipeline running_time to the segment running_time

perform skip playback (Since: 1.6)

Deprecated backward compatibility flag, replaced by SegmentFlags::Trickmode

send SEGMENT_DONE instead of EOS

Decode only keyframes, where possible (Since: 1.6)

Decode only keyframes or forward predicted frames, where possible (Since: 1.18)

Do not decode any audio, where possible (Since: 1.6)

Try to retrieve the minimum information available, which may be none on some platforms (Since: 1.18)

Try to retrieve as much information as possible, including source information when getting the stack trace

Feature: v1_12

The possible states an element can be in. States can be changed using Element::set_state and checked using Element::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::NullState::Playing is called an upwards state change and State::PlayingState::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 Element::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.

A high-level object representing a single stream. It might be backed, or not, by an actual flow of data in a pipeline (Pad).

A Stream does not care about data changes (such as decoding, encoding, parsing,...) as long as the underlying data flow corresponds to the same high-level flow (ex: a certain audio track).

A Stream contains all the information pertinent to a stream, such as stream-id, tags, caps, type, ...

Elements can subclass a Stream for internal usage (to contain information pertinent to streams of data).

Feature: v1_10

Implements

GstObjectExt, glib::object::ObjectExt

Create a new Stream for the given stream_id, caps, type_ and flags

Feature: v1_10

stream_id

the id for the new stream. If None, a new one will be automatically generated

caps

the Caps of the stream

type_

the StreamType of the stream

flags

the StreamFlags of the stream

Returns

The new Stream

Retrieve the caps for self, if any

Feature: v1_10

Returns

The Caps for self

Retrieve the current stream flags for self

Feature: v1_10

Returns

The StreamFlags for self

Returns the stream ID of self.

Feature: v1_10

Returns

the stream ID of self. Only valid during the lifetime of self.

Retrieve the stream type for self

Feature: v1_10

Returns

The StreamType for self

Retrieve the tags for self, if any

Feature: v1_10

Returns

The TagList for self

Set the caps for the Stream

Feature: v1_10

caps

a Caps

Set the flags for the self.

Feature: v1_10

flags

the flags to set on self

Set the stream type of self

Feature: v1_10

stream_type

the type to set on self

Set the tags for the Stream

Feature: v1_10

tags

a TagList

The Caps of the Stream.

The Caps of the Stream.

The unique identifier of the Stream. Can only be set at construction time.

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 StreamType of the Stream. Can only be set at construction time.

The TagList of the Stream.

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.

Feature: v1_10

Implements

GstObjectExt, glib::object::ObjectExt

Create a new StreamCollection.

Feature: v1_10

upstream_id

The stream id of the parent stream

Returns

The new StreamCollection.

Add the given stream to the self.

Feature: v1_10

stream

the Stream to add

Returns

true if the stream was properly added, else false

Get the number of streams this collection contains

Feature: v1_10

Returns

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.

This stream has no special attributes

This stream is a sparse stream (e.g. a subtitle stream), data may flow only in irregular intervals with large gaps in between.

This stream should be selected by default. This flag may be used by demuxers to signal that a stream should be selected by default in a playback scenario.

This stream should not be selected by default. This flag may be used by demuxers to signal that a stream should not be selected by default in a playback scenario, but only if explicitly selected by the user (e.g. an audio track for the hard of hearing or a director's commentary track).

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

StreamType describes a high level classification set for flows of data in Stream objects.

Note that this is a flag, and therefore users should not assume it will be a single value. Do not use the equality operator for checking whether a stream is of a certain type.

The stream is of unknown (unclassified) type.

The stream is of audio data

The stream carries video data

The stream is a muxed container type

The stream contains subtitle / subpicture data.

Feature: v1_10

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.

The serialization format

GstStructure serialization format serialize the GstStructure name, keys/GType/values in a comma separated list with the structure name as first field without value followed by separated key/value pairs in the form key=value, for example:

a-structure, key=value

The values type will be inferred if not explicitly specified with the (GTypeName)value syntax, for example the following struct will have one field called 'is-string' which has the string 'true' as a value:

a-struct, field-is-string=(string)true, field-is-boolean=true

Note: without specifying (string), field-is-string` type would have been inferred as boolean.

Note: we specified (string) as a type even if gchararray is the actual GType name as for convenience some well known types have been aliased or abbreviated.

To avoid specifying the type, you can give some hints to the "type system". For example to specify a value as a double, you should add a decimal (ie. 1 is an int while 1.0 is a double).

Note: when a structure is serialized with Structure::to_string, all values are explicitly typed.

Some types have special delimiters:

  • GstValueArray are inside curly brackets ({ and }). For example a-structure, array={1, 2, 3}
  • Ranges are inside brackets ([ and ]). For example a-structure, range=[1, 6, 2] 1 being the min value, 6 the maximum and 2 the step. To specify a GST_TYPE_INT64_RANGE you need to explicitly specify it like: a-structure, a-int64-range=(gint64) [1, 5]
  • GstValueList are inside "less and greater than" (< and >). For example `a-structure, list=<1, 2, 3>

Structures are delimited either by a null character \0 or a semicolumn ; the latter allowing to store multiple structures in the same string (see #GstCaps).

Quotes are used as "default" delimiters and can be used around any types that don't use other delimiters (for example a-struct, i=(int)"1"). They are use to allow adding spaces or special characters (such as delimiters, semicolumns, etc..) inside strings and you can use backslashes \ to escape characters inside them, for example:

a-struct, special="\"{[(;)]}\" can be used inside quotes"

They also allow for nested structure, such as:

a-struct, nested=(GstStructure)"nested-struct, nested=true"

Note

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

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.

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.

See Structure::set_name for constraints on the name parameter.

Free-function: gst_structure_free

name

name of new structure

firstfield

name of first field to set

varargs

variable argument list

Returns

a new Structure

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

struct2

a Structure

Returns

true if intersection would not be empty

Duplicates a Structure and all its fields and values.

Free-function: gst_structure_free

Returns

a new Structure.

Calls the provided function once for each field in the Structure. In contrast to Structure::foreach, the function may modify the fields. In contrast to Structure::map_in_place, the field is removed from the structure if false is returned from the function. The structure must be mutable.

func

a function to call for each field

user_data

private data

Fixate all values in self using gst_value_fixate. self will be modified in-place and should be writable.

Fixates a Structure by changing the given field with its fixated value.

field_name

a field in self

Returns

true if the structure field could be fixated

Fixates a Structure by changing the given field_name field to the given target boolean if that field is not fixed yet.

field_name

a field in self

target

the target value of the fixation

Returns

true if the structure could be fixated

Fixates a Structure by changing the given field to the nearest double to target that is a subset of the existing field.

field_name

a field in self

target

the target value of the fixation

Returns

true if the structure could be fixated

Fixates a Structure by changing the given field to the nearest fraction to target_numerator/target_denominator that is a subset of the existing field.

field_name

a field in self

target_numerator

The numerator of the target value of the fixation

target_denominator

The denominator of the target value of the fixation

Returns

true if the structure could be fixated

Fixates a Structure by changing the given field to the nearest integer to target that is a subset of the existing field.

field_name

a field in self

target

the target value of the fixation

Returns

true if the structure could be fixated

Fixates a Structure by changing the given field_name field to the given target string if that field is not fixed yet.

field_name

a field in self

target

the target value of the fixation

Returns

true if the structure could be fixated

Calls the provided function once for each field in the Structure. The function must not modify the fields. Also see Structure::map_in_place and Structure::filter_and_map_in_place.

func

a function to call for each field

user_data

private data

Returns

true if the supplied function returns true For each of the fields, false otherwise.

Frees a Structure and all its fields and values. The structure must not have a parent when this function is called.

Parses the variable arguments and reads fields from self accordingly. Variable arguments should be in the form field name, field type (as a GType), pointer(s) to a variable(s) to hold the return value(s). The last variable argument should be None.

For refcounted (mini)objects you will receive a new reference which you must release with a suitable _unref() when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either g_free or the suitable function for the boxed type.

first_fieldname

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

This is useful in language bindings where unknown gobject::Value types are not supported. This function will convert the GST_TYPE_ARRAY into a newly allocated gobject::ValueArray and return it through array. Be aware that this is slower then getting the gobject::Value directly.

Feature: v1_12

fieldname

the name of a field

array

a pointer to a gobject::ValueArray

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a GST_TYPE_ARRAY, this function returns false.

Sets the boolean pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

fieldname

the name of a field

value

a pointer to a gboolean to set

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a boolean, this function returns false.

Sets the clock time pointed to by value corresponding to the clock time of the given field. Caller is responsible for making sure the field exists and has the correct type.

fieldname

the name of a field

value

a pointer to a ClockTime to set

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a ClockTime, this function returns false.

Sets the date pointed to by value corresponding to the date of the given field. Caller is responsible for making sure the field exists and has the correct type.

On success value will point to a newly-allocated copy of the date which should be freed with glib::Date::free when no longer needed (note: this is inconsistent with e.g. Structure::get_string which doesn't return a copy of the string).

fieldname

the name of a field

value

a pointer to a glib::Date to set

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a data, this function returns false.

Sets the datetime pointed to by value corresponding to the datetime of the given field. Caller is responsible for making sure the field exists and has the correct type.

On success value will point to a reference of the datetime which should be unreffed with DateTime::unref when no longer needed (note: this is inconsistent with e.g. Structure::get_string which doesn't return a copy of the string).

fieldname

the name of a field

value

a pointer to a DateTime to set

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a data, this function returns false.

Sets the double pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

fieldname

the name of a field

value

a pointer to a gdouble to set

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a double, this function returns false.

Sets the int pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists, has the correct type and that the enumtype is correct.

fieldname

the name of a field

enumtype

the enum type of a field

value

a pointer to an int to set

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain an enum of the given type, this function returns false.

Finds the field with the given name, and returns the type of the value it contains. If the field is not found, G_TYPE_INVALID is returned.

fieldname

the name of the field

Returns

the gobject::Value of the field

Read the GstFlagSet flags and mask out of the structure into the provided pointers.

fieldname

the name of a field

value_flags

a pointer to a guint for the flags field

value_mask

a pointer to a guint for the mask field

Returns

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.

fieldname

the name of a field

value_numerator

a pointer to an int to set

value_denominator

a pointer to an int to set

Returns

true if the values could be set correctly. If there was no field with fieldname or the existing field did not contain a GstFraction, this function returns false.

Sets the int pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

fieldname

the name of a field

value

a pointer to an int to set

Returns

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.

Sets the gint64 pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

fieldname

the name of a field

value

a pointer to a gint64 to set

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a gint64, this function returns false.

This is useful in language bindings where unknown gobject::Value types are not supported. This function will convert the GST_TYPE_LIST into a newly allocated GValueArray and return it through array. Be aware that this is slower then getting the gobject::Value directly.

Feature: v1_12

fieldname

the name of a field

array

a pointer to a gobject::ValueArray

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a GST_TYPE_LIST, this function returns false.

Get the name of self as a string.

Returns

the name of the structure.

Get the name of self as a GQuark.

Returns

the quark representing the name of the structure.

Finds the field corresponding to fieldname, and returns the string contained in the field's value. Caller is responsible for making sure the field exists and has the correct type.

The string should not be modified, and remains valid until the next call to a gst_structure_*() function with the given structure.

fieldname

the name of a field

Returns

a pointer to the string or None when the field did not exist or did not contain a string.

Sets the uint pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

fieldname

the name of a field

value

a pointer to a uint to set

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a uint, this function returns false.

Sets the guint64 pointed to by value corresponding to the value of the given field. Caller is responsible for making sure the field exists and has the correct type.

fieldname

the name of a field

value

a pointer to a guint64 to set

Returns

true if the value could be set correctly. If there was no field with fieldname or the existing field did not contain a guint64, this function returns false.

Parses the variable arguments and reads fields from self accordingly. valist-variant of Structure::get. Look at the documentation of Structure::get for more details.

first_fieldname

the name of the first field to read

args

variable arguments

Returns

true, or false if there was a problem reading any of the fields

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.

For refcounted (mini)objects you will receive a new reference which you must release with a suitable _unref() when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either g_free or the suitable function for the boxed type.

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

args

variable arguments

Returns

true, or false if there was a problem reading any of the fields

Get the value of the field with GQuark field.

field

the glib::Quark of the field to get

Returns

the gobject::Value corresponding to the field with the given name identifier.

Check if self contains a field named field.

field

glib::Quark of the field name

Returns

true if the structure contains a field with the given name

Check if self contains a field named field and with GType type_.

field

glib::Quark of the field name

type_

the type of a value

Returns

true if the structure contains a field with the given name and type

Identical to gst_structure_set, except that field names are passed using the GQuark for the field name. This allows more efficient setting of the structure if the caller already knows the associated quark values. The last variable argument must be None.

fieldname

the GQuark for the name of the field to set

va_list form of Structure::id_set.

fieldname

the name of the field to set

varargs

variable arguments

Sets the field with the given GQuark field to value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed.

field

a glib::Quark representing a field

value

the new value of the field

Sets the field with the given GQuark field to value. If the field does not exist, it is created. If the field exists, the previous value is replaced and freed.

field

a glib::Quark representing a field

value

the new value of the field

Intersects self and struct2 and returns the intersection.

struct2

a Structure

Returns

Intersection of self and struct2

Tests if the two Structure are equal.

structure2

a Structure.

Returns

true if the two structures have the same name and field.

Checks if self is a subset of superset, i.e. has the same structure name and for all fields that are existing in superset, self has a value that is a subset of the value in superset.

superset

a potentially greater Structure

Returns

true if self is a subset of superset

Calls the provided function once for each field in the Structure. In contrast to Structure::foreach, the function may modify but not delete the fields. The structure must be mutable.

func

a function to call for each field

user_data

private data

Returns

true if the supplied function returns true For each of the fields, false otherwise.

Get the number of fields in the structure.

Returns

the number of fields in the structure

Get the name of the given field number, counting from 0 onwards.

index

the index to get the name of

Returns

the name of the given field number

Removes all fields in a GstStructure.

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.

Feature: v1_12

fieldname

the name of a field

array

a pointer to a gobject::ValueArray

This is useful in language bindings where unknown GValue types are not supported. This function will convert a array to GST_TYPE_LIST and set the field specified by fieldname. Be aware that this is slower then using GST_TYPE_LIST in a gobject::Value directly.

Feature: v1_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.

Atomically modifies a pointer to point to a new structure. The Structure oldstr_ptr is pointing to is freed and newstr is taken ownership over.

Either newstr and the value pointed to by oldstr_ptr may be None.

It is a programming error if both newstr and the value pointed to by oldstr_ptr refer to the same, non-None structure.

Feature: v1_18

oldstr_ptr

pointer to a place of a Structure to take

newstr

a new Structure

Returns

true if newstr was different from oldstr_ptr

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, ClockExtManual

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

Extra tag flags used when registering tags.

undefined flag

tag is meta data

tag is encoded

tag is decoded

number of tag flags

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 TagList::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

a new TagList. Free with TagList::unref when no longer needed.

Sets the values for the given tags using the specified mode.

mode

the mode to use

tag

tag

Sets the values for the given tags using the specified mode.

mode

the mode to use

tag

tag

var_args

tag / value pairs to set

Sets the GValues for the given tags using the specified mode.

mode

the mode to use

tag

tag

var_args

tag / GValue pairs to set

Sets the GValue for a given tag using the specified mode.

mode

the mode to use

tag

tag

value

GValue for this tag

Sets the GValues for the given tags using the specified mode.

mode

the mode to use

tag

tag

Creates a new TagList as a copy of the old self. The new taglist will have a refcount of 1, owned by the caller, and will be writable as a result.

Note that this function is the semantic equivalent of a TagList::ref followed by a gst_tag_list_make_writable. If you only want to hold on to a reference to the data, you should use TagList::ref.

When you are finished with the taglist, call TagList::unref on it.

Returns

the new TagList

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.

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.

Copies the first date for the given tag in the taglist into the variable pointed to by value. Free the date with glib::Date::free when it is no longer needed.

Free-function: g_date_free

tag

tag to read out

value

address of a GDate pointer variable to store the result into

Returns

true, if a date was copied, false if the tag didn't exist in the given list or if it was None.

Gets the date that is at the given index for the given tag in the given list and copies it into the variable pointed to by value. Free the date with glib::Date::free when it is no longer needed.

Free-function: g_date_free

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 or if it was None.

Copies the first datetime for the given tag in the taglist into the variable pointed to by value. Unref the date with DateTime::unref when it is no longer needed.

Free-function: gst_date_time_unref

tag

tag to read out

value

address of a DateTime pointer variable to store the result into

Returns

true, if a datetime was copied, false if the tag didn't exist in the given list or if it was None.

Gets the datetime that is at the given index for the given tag in the given list and copies it into the variable pointed to by value. Unref the datetime with DateTime::unref when it is no longer needed.

Free-function: gst_date_time_unref

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

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.

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.

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.

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.

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.

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.

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.

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.

Copies the first sample for the given tag in the taglist into the variable pointed to by sample. Free the sample with 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 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

true, if a value was copied, false if the tag didn't exist in the given list.

Checks how many value are stored in this tag list for the given tag.

tag

the tag to query

Returns

The number of tags stored

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.

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.

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

The GValue for the specified entry or None if the tag wasn't available or the tag doesn't have as many entries

Inserts the tags of the from list into the first list using the given mode.

from

list to merge from

mode

the mode to use

Checks if the given taglist is empty.

Returns

true if the taglist is empty, otherwise false.

Checks if the two given taglists are equal.

list2

a TagList.

Returns

true if the taglists are equal, otherwise false

Merges the two given lists into a new list. If one of the lists is None, a copy of the other is returned. If both lists are None, None is returned.

Free-function: gst_tag_list_unref

list2

second list to merge

mode

the mode to use

Returns

the new list

Get the number of tags in self.

Returns

The number of tags in self.

Get the name of the tag in self at index.

index

the index

Returns

The name of the tag at index.

Peeks at 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 doesn't need to be freed by the caller. The returned string is also guaranteed to be non-None and non-empty.

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.

Add a reference to a TagList mini object.

From this point on, until the caller calls TagList::unref or gst_tag_list_make_writable, it is guaranteed that the taglist object will not change. To use a TagList object, you must always have a refcount on it -- either the one made implicitly by e.g. TagList::new, or via taking one explicitly with this function.

Returns

the same TagList mini object.

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.

Unref a TagList, and and free all its memory when the refcount reaches 0.

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

GstTagScope specifies if a taglist applies to the complete medium or only to one single stream.

tags specific to this single stream

global tags for the complete medium

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

TagSetterExt, ElementExt, GstObjectExt, glib::object::ObjectExt, TagSetterExtManual, ElementExtManual

Trait containing all TagSetter methods.

Implementors

TagSetter

Adds the given tag / value pairs on the setter using the given merge mode. The list must be terminated with None.

mode

the mode to use

tag

tag to set

var_args

tag / value pairs to set

Adds the given tag / GValue pairs on the setter using the given merge mode. The list must be terminated with None.

mode

the mode to use

tag

tag to set

var_args

tag / GValue pairs to set

Adds the given tag / GValue pair on the setter using the given merge mode.

mode

the mode to use

tag

tag to set

value

GValue to set for the tag

Adds the given tag / GValue pairs on the setter using the given merge mode. The list must be terminated with None.

mode

the mode to use

tag

tag to set

Adds the given tag / value pairs on the setter using the given merge mode. The list must be terminated with None.

mode

the mode to use

tag

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.

Appends the TocEntry entry to self.

entry

A TocEntry

Find TocEntry with given uid in the self.

uid

UID to find TocEntry with.

Returns

TocEntry with specified uid from the self, or None if not found.

Gets the list of TocEntry of self.

Returns

A glib::List of TocEntry for entry

Returns

scope of self

Gets the tags for self.

Returns

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, ElementExtManual

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 information 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, PluginFeatureExtManual

Gets the list of all registered typefind factories. You must free the list using PluginFeature::list_free.

The returned factories are sorted by highest rank first, and then by factory name.

Free-function: gst_plugin_feature_list_free

Returns

the list of all registered TypeFindFactory.

Calls the GstTypeFindFunction associated with this factory.

find

a properly setup TypeFind entry. The get_data and suggest_type members must be set.

Gets the Caps associated with a typefind factory.

Returns

the Caps associated with this factory

Gets the extensions associated with a TypeFindFactory. The returned array should not be changed. If you need to change stuff in it, you should copy it using g_strdupv. This function may return None to indicate a 0-length list.

Returns

a None-terminated array of extensions associated with this factory

Check whether the factory has a typefind function. Typefind factories without typefind functions are a last-effort fallback mechanism to e.g. assume a certain media type based on the file extension.

Returns

true if the factory has a typefind functions set, otherwise false

The probability of the typefind function. Higher values have more certainty in doing a reliable typefind.

type undetected.

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.

An application can use the following functions to quickly get an element that handles the given URI for reading or writing (Element::make_from_uri).

Source and Sink plugins should implement this interface when possible.

Implements

URIHandlerExt

Trait containing all URIHandler methods.

Implementors

URIHandler

Gets the list of protocols supported by self. This list may not be modified.

Returns

the supported protocols. Returns None if the self isn't implemented properly, or the self doesn't support any protocols.

Gets the currently handled URI.

Returns

the URI currently handled by the self. Returns None if there are no URI currently handled. The returned string must be freed with g_free when no longer needed.

Gets the type of the given URI handler

Returns

the URIType of the URI handler. Returns URIType::Unknown if the self isn't implemented correctly.

Tries to set the URI of the given handler.

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.