gst.c.types

Alias for #GstMapInfo to be used with g_auto():

void my_func(GstBuffer *buf)
{
 g_auto(GstBufferMapInfo) map = GST_MAP_INFO_INIT;
 if (!gst_buffer_map(buf, &map, GST_MAP_READWRITE))
   return;
 ...
 // No need to call gst_buffer_unmap()
}

#GstMapInfo cannot be used with g_auto() because it is ambiguous whether it needs to be unmapped using [gst.buffer.Buffer.unmap] or [gst.memory.Memory.unmap].

See also #GstMemoryMapInfo.

A datatype to hold the handle to an outstanding sync or async clock callback.

A datatype to hold a time, measured in nanoseconds.

A datatype to hold a time difference, measured in nanoseconds.

A type defining the type of an element factory.

Alias for #GstMapInfo to be used with g_auto():

void my_func(GstMemory *mem)
{
 g_auto(GstMemoryMapInfo) map = GST_MAP_INFO_INIT;
 if (!gst_memory_map(mem, &map, GST_MAP_READWRITE))
   return;
 ...
 // No need to call gst_memory_unmap()
}

#GstMapInfo cannot be used with g_auto() because it is ambiguous whether it needs to be unmapped using [gst.buffer.Buffer.unmap] or [gst.memory.Memory.unmap].

See also #GstBufferMapInfo.

Flags for allocators.

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

A set of flags that can be provided to the [gst.buffer.Buffer.copyInto] function to specify which items should be copied.

A set of buffer flags used to describe properties of a #GstBuffer.

Additional flags to control the allocation of a buffer

The different types of buffering methods.

The standard flags that a bus may have.

The result values for a GstBusSyncHandler.

Extra flags for a caps.

Modes of caps intersection

[gst.types.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.

[gst.types.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.

The type of the clock entry

The capabilities of this clock

The return value of a clock operation.

The different kind of clocks.

Core errors are errors inside the core GStreamer library.

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

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

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.

The standard flags that an element may have.

#GstEventType 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 #GstStructure. Specific custom events are distinguished by the name of the structure.

#GstEventTypeFlags indicate the aspects of the different #GstEventType values. You can get the type flags of a #GstEventType with the [gst.global.eventTypeGetFlags] function.

The result of passing data to a pad.

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

Standard predefined formats

The different flags that can be set on #GST_EVENT_GAP events. See [gst.event.Event.setGapFlags] for details.

The result of a #GstIteratorItemFunction.

The result of [gst.iterator.Iterator.next].

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

Flags used when locking miniobjects

Flags used when mapping memory

Flags for wrapped memory.

The different message types that are available.

Extra metadata flags.

Flags for the mini object

The standard flags that an gstobject may have.

The direction of a pad.

Pad state flags

The amount of checking to be done when linking pads. @GST_PAD_LINK_CHECK_CAPS and @GST_PAD_LINK_CHECK_TEMPLATE_CAPS are mutually exclusive. If both are specified, expensive but safe @GST_PAD_LINK_CHECK_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 ([gst.types.PadLinkCheck.Default]) or the regular methods for linking the pads.

Result values from gst_pad_link and friends.

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.

Indicates when this pad will become available.

Different return values for the #GstPadProbeCallback.

The different probing types that can occur. When either one of @GST_PAD_PROBE_TYPE_IDLE or @GST_PAD_PROBE_TYPE_BLOCK is used, the probe will be a blocking probe.

Flags for the padtemplate

The different parsing errors that can occur.

Parsing options.

Pipeline flags

Flags used in connection with [gst.plugin.Plugin.addDependency].

The plugin loading errors

The plugin loading state

The type of a [gst.types.MessageType.Progress]. The progress messages inform the application of the status of asynchronous tasks.

The result of a #GstPromise

The different types of QoS events that can be given to the [gst.event.Event.newQos] method.

Standard predefined Query types

#GstQueryTypeFlags indicate the aspects of the different #GstQueryType values. You can get the type flags of a #GstQueryType with the [gst.global.queryTypeGetFlags] function.

Element priority ranks. Defines the order in which the autoplugger (or similar rank-picking mechanisms, such as e.g. [gst.element.Element.makeFromUri]) 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 #GstPluginFeature. Any value is valid, including values bigger than @GST_RANK_PRIMARY.

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.

The different scheduling flags.

The different search modes.

Flags to be used with [gst.element.Element.seek] or [gst.event.Event.newSeek]. 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 [gst.types.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 [gst.types.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 [gst.types.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 [gst.types.SeekFlags.TrickmodeKeyUnits] flag can be used to request that decoders skip all frames except key units, and [gst.types.SeekFlags.TrickmodeNoAudio] flags can be used to request that audio decoders do no decoding at all, and simple output silence.

The [gst.types.SeekFlags.SnapBefore] flag can be used to snap to the previous relevant location, and the [gst.types.SeekFlags.SnapAfter] flag can be used to select the next relevant location. If [gst.types.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.

The different types of seek events. When constructing a seek event with [gst.event.Event.newSeek] or when doing gst_segment_do_seek ().

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

The possible states an element can be in. States can be changed using [gst.element.Element.setState] and checked using [gst.element.Element.getState].

These are the different state changes an element goes through. [gst.types.State.Null] ⇒ [gst.types.State.Playing] is called an upwards state change and [gst.types.State.Playing] ⇒ [gst.types.State.Null] a downwards state change.

The possible return values from a state change function such as [gst.element.Element.setState]. Only @GST_STATE_CHANGE_FAILURE is a real failure.

Stream errors are for anything related to the stream being processed: format errors, media type errors, ... They're typically used by decoders, demuxers, converters, ...

The type of a [gst.types.MessageType.StreamStatus]. The stream status messages inform the application of new streaming threads and their status.

#GstStreamType describes a high level classification set for flows of data in #GstStream 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 type of a [gst.types.MessageType.StructureChange].

Extra tag flags used when registering tags.

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 [gst.tag_setter.TagSetter.mergeTags] / [gst.tag_setter.TagSetter.addTags] or a [gst.types.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.

GstTagScope specifies if a taglist applies to the complete medium or only to one single stream.

The different states a task can be in

The different types of TOC entries (see #GstTocEntry).

There are two types of TOC entries: alternatives or parts in a sequence.

How a #GstTocEntry should be repeated. By default, entries are played a single time.

The scope of a TOC.

Flag that describe the value. These flags help applications processing the logs to understand the values.

Tracing record will contain fields that contain a measured value or extra meta-data. One such meta data are values that tell where a measurement was taken. This enumerating declares to which scope such a meta data field relates to. If it is e.g. [gst.types.TracerValueScope.Pad], then each of the log events may contain values for different #GstPads.

The probability of the typefind function. Higher values have more certainty in doing a reliable typefind.

Different URI-related errors that can occur.

The different types of URI direction.

Parameters to control the allocation of memory

Memory is usually created by allocators with a [gst.allocator.Allocator.alloc] method call. When null is used as the allocator, the default allocator will be used.

New allocators can be registered with [gst.allocator.Allocator.register]. Allocators are identified by name and can be retrieved with [gst.allocator.Allocator.find]. [gst.allocator.Allocator.setDefault] can be used to change the default allocator.

New memory can be created with [gst.memory.Memory.newWrapped] that wraps the memory allocated elsewhere.

The #GstAllocator is used to create new memory.

The #GstAtomicQueue object implements a queue that can be used from multiple threads without performing any blocking operations.

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

A new #GstBin is created with [gst.bin.Bin.new_]. Use a #GstPipeline 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 [gst.bin.Bin.add]. You can remove elements with [gst.bin.Bin.remove].

An element can be retrieved from a bin with [gst.bin.Bin.getByName], using the elements name. [gst.bin.Bin.getByNameRecurseUp] 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 [gst.bin.Bin.iterateElements]. Various other iterators exist to retrieve the elements in a bin.

[gst.object.ObjectWrap.unref] is used to drop your reference to the bin.

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

A #GstBin internally intercepts every #GstMessage posted by its children and implements the following default behaviour for each of them:

• [gst.types.MessageType.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.types.MessageType.SegmentStart]: Just collected and never forwarded upwards.

The messages are used to decide when all elements have completed playback of their segment.

• [gst.types.MessageType.SegmentDone]: Is posted by #GstBin when all elements that posted

a SEGMENT_START have posted a SEGMENT_DONE.

• [gst.types.MessageType.DurationChanged]: 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.types.MessageType.StreamStart] message, signaling the active start of a (new) stream.

• [gst.types.MessageType.ClockLost]: 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.types.MessageType.ClockProvide]: 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 to the application but is forwarded to the parent of the bin.

• OTHERS: posted upwards.

A #GstBin implements the following default behaviour for answering to a #GstQuery:

• [gst.types.QueryType.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.types.QueryType.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 #GstBin will by default forward any event sent to it to all sink ( [gst.types.EventTypeFlags.Upstream] ) or source ( [gst.types.EventTypeFlags.Downstream] ) 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.

Subclasses can override #GstBinClass::add_element and #GstBinClass::remove_element to update the list of children in the bin.

The #GstBinClass::handle_message method can be overridden to implement custom message handling.

#GstBinClass::deep_element_added will be called when a new element has been added to any bin inside this bin, so it will also be called if a new child was added to a sub-bin of this bin. #GstBin implementations that override this message should chain up to the parent class implementation so the #GstBin::deep-element-added signal is emitted on all parents.

A fundamental type that describes a 64-bit bitmask

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 #GstMemory blocks that the buffer contains.

Buffers are usually created with [gst.buffer.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.

`` C 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 [gst.buffer.Buffer.newAllocate] to create a buffer with preallocated data of a given size.

Buffers can contain a list of #GstMemory objects. You can retrieve how many memory objects with [gst.buffer.Buffer.nMemory] and you can get a pointer to memory with [gst.buffer.Buffer.peekMemory]

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 #GstClockTime values).

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

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

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

To efficiently create a smaller buffer out of an existing one, you can use [gst.buffer.Buffer.copyRegion]. 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 #GstBufferFlags flag is set.

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

Arbitrary extra metadata can be set on a buffer with [gst.buffer.Buffer.addMeta]. Metadata can be retrieved with [gst.buffer.Buffer.getMeta]. See also #GstMeta.

An element should either unref the buffer or push it out on a src pad using [gst.pad.Pad.push] (see #GstPad).

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

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

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

Buffer lists are an object containing a list of buffers.

Buffer lists are created with [gst.buffer_list.BufferList.new_] and filled with data using [gst.buffer_list.BufferList.insert].

Buffer lists can be pushed on a srcpad with [gst.pad.Pad.pushList]. 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.

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

A #GstBufferPool is created with [gst.buffer_pool.BufferPool.new_].

Once a pool is created, it needs to be configured. A call to [gst.buffer_pool.BufferPool.getConfig] returns the current configuration structure from the pool. With [gst.buffer_pool.BufferPool.configSetParams] and [gst.buffer_pool.BufferPool.configSetAllocator] 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 [gst.buffer_pool.BufferPool.configAddOption]. The available options can be retrieved with [gst.buffer_pool.BufferPool.getOptions]. Some options allow for additional configuration properties to be set.

After the configuration structure has been configured, [gst.buffer_pool.BufferPool.setConfig] updates the configuration in the pool. This can fail when the configuration structure is not accepted.

After the pool has been configured, it can be activated with [gst.buffer_pool.BufferPool.setActive]. This will preallocate the configured resources in the pool.

When the pool is active, [gst.buffer_pool.BufferPool.acquireBuffer] can be used to retrieve a buffer from the pool.

Buffers allocated from a bufferpool will automatically be returned to the pool with [gst.buffer_pool.BufferPool.releaseBuffer] when their refcount drops to 0.

The bufferpool can be deactivated again with [gst.buffer_pool.BufferPool.setActive]. All further [gst.buffer_pool.BufferPool.acquireBuffer] calls will return an error. When all buffers are returned to the pool they will be freed.

Parameters passed to the [gst.buffer_pool.BufferPool.acquireBuffer] function to control the allocation of the buffer.

The default implementation ignores the @start and @stop members but other implementations can use this extra information to decide what buffer to return.

The #GstBufferPool class.

The #GstBus is an object responsible for delivering #GstMessage packets in a first-in first-out way from the streaming threads (see #GstTask) 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 #GSource based notifications. This makes it possible to handle the delivery in the glib #GMainLoop.

The #GSource callback function [gst.bus.Bus.asyncSignalFunc] can be used to convert all bus messages into signal emissions.

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

The bus can be polled with the [gst.bus.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 [gst.bus.Bus.pop] the messages from the bus to handle them. Alternatively the application can register an asynchronous bus function using [gst.bus.Bus.addWatchFull] or [gst.bus.Bus.addWatch]. This function will install a #GSource 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 [gst.bus.Bus.setSyncHandler] 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 #GstPipeline has one bus.

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

GStreamer bus class.

Interface for an array of bytes. It is expected to be subclassed to implement @resize virtual method using language native array implementation, such as GLib's #GByteArray, C++'s std::vector<uint8_t> or Rust's Vec<u8>.

@resize implementation could allocate more than requested to avoid repeated reallocations. It can return false, or be set to null, in the case the array cannot grow.

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

Caps are exposed on #GstPadTemplate to describe all possible types a given pad can handle. They are also stored in the #GstRegistry along with a description of the #GstElement.

Caps are exposed on the element pads using the [gst.pad.Pad.queryCaps] pad function. This function describes the possible types that the pad can handle or produce at runtime.

A #GstCaps can be constructed with the following code fragment:

`` C 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 #GstCaps is fixed when it has no fields with ranges or lists. Use [gst.caps.Caps.isFixed] 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 until 1.20 the #GstCaps / #GstStructure serialization into string had limited support for nested #GstCaps / #GstStructure fields. It could only support one level of nesting. Using more levels would lead to unexpected behavior when using serialization features, such as [gst.caps.Caps.toString_] or [gst.global.valueSerialize] and their counterparts.

#GstCapsFeatures can optionally be set on a #GstCaps to add requirements for additional features for a specific #GstStructure. Caps structures with the same name but with a non-equal set of caps features are not compatible. If a pad supports multiple sets of features it has to add multiple equal structures with different feature sets to the caps.

Empty #GstCapsFeatures are equivalent with the #GstCapsFeatures that only contain #GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY. ANY #GstCapsFeatures as created by [gst.caps_features.CapsFeatures.newAny] are equal to any other #GstCapsFeatures and can be used to specify that any #GstCapsFeatures would be supported, e.g. for elements that don't touch buffer memory. #GstCaps with ANY #GstCapsFeatures are considered non-fixed and during negotiation some #GstCapsFeatures have to be selected.

Examples for caps features would be the requirement of a specific #GstMemory types or the requirement of having a specific #GstMeta on the buffer. Features are given as a string of the format memory:GstMemoryTypeName or meta:GstMetaAPIName.

This interface abstracts handling of property sets for elements with children. Imagine elements such as mixers or polyphonic generators. They all have multiple #GstPad or some kind of voice objects. Another use case are container elements like #GstBin. 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 [gst.child_proxy.ChildProxy.get] and [gst.child_proxy.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 #GstChildProxy interface.

#GstChildProxy interface.

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

The #GstClock returns a monotonically increasing time with the method [gst.clock.Clock.getTime]. 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 #GST_EVENT_SEGMENT events and the element's base time, see #GstPipeline.

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

One first needs to create a #GstClockID for the periodic or single shot notification using [gst.clock.Clock.newSingleShotId] or [gst.clock.Clock.newPeriodicId].

To perform a blocking wait for the specific time of the #GstClockID use [gst.clock.Clock.idWait]. To receive a callback when the specific time is reached in the clock use [gst.clock.Clock.idWaitAsync]. Both these calls can be interrupted with the [gst.clock.Clock.idUnschedule] call. If the blocking wait is unscheduled a return value of #GST_CLOCK_UNSCHEDULED is returned.

Periodic callbacks scheduled async will be repeatedly called automatically until they are unscheduled. To schedule a sync periodic callback, [gst.clock.Clock.idWait] 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 #GstClockID that has been unscheduled cannot be used again for any wait operation, a new #GstClockID should be created and the old unscheduled one should be destroyed with [gst.clock.Clock.idUnref].

It is possible to perform a blocking wait on the same #GstClockID from multiple threads. However, registering the same #GstClockID 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 #GstClockID, 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 #GstClockID has to keep a handle to the #GstClockID 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 #GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be slaved to another #GstClock with [gst.clock.Clock.setMaster]. 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 [gst.clock.Clock.setCalibration]. This feature is mostly useful for plugins that have an internal clock but must operate with another clock selected by the #GstPipeline. They can track the offset and rate difference of their internal clock relative to the master clock by using the [gst.clock.Clock.getCalibration] function.

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

GStreamer clock class. Override the vmethods to implement the clock functionality.

All pending timeouts or periodic notifies are converted into an entry. Note that GstClockEntry should be treated as an opaque structure. It must not be extended or allocated using a custom allocator.

#GstContext 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 [gst.element.Element.setContext], which will then be propagated to all child elements. Elements can handle these in #GstElementClass::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.types.QueryType.Context] for the context
3. Query upstream with [gst.types.QueryType.Context] for the context
4. Post a [gst.types.MessageType.NeedContext] message on the bus with the required

context types and afterwards check if a usable context was set now

1. Create a context by itself and post a [gst.types.MessageType.HaveContext] message

on the bus.

Bins will catch [gst.types.MessageType.NeedContext] 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.

#GstContext can be persistent. A persistent #GstContext is kept in elements when they reach [gst.types.State.Null], non-persistent ones will be removed. Also, a non-persistent context won't override a previous persistent context set to an element.

A base class for value mapping objects that attaches control sources to #GObject properties. Such an object is taking one or more #GstControlSource instances, combines them and maps the resulting value to the type and value range of the bound property.

The class structure of #GstControlBinding.

The #GstControlSource is a base class for control value sources that could be used to get timestamp-value pairs. A control source essentially is a function over time.

A #GstControlSource is used by first getting an instance of a specific control-source, creating a binding for the control-source to the target property of the element and then adding the binding to the element. The binding will convert the data types and value range to fit to the bound property.

For implementing a new #GstControlSource one has to implement #GstControlSourceGetValue and #GstControlSourceGetValueArray functions. These are then used by [gst.control_source.ControlSource.controlSourceGetValue] and [gst.control_source.ControlSource.controlSourceGetValueArray] to get values for specific timestamps.

The class structure of #GstControlSource.

Extra custom metadata. The @structure field is the same as returned by [gst.custom_meta.CustomMeta.getStructure].

Since 1.24 it can be serialized using [gst.meta.Meta.serialize] and [gst.meta.Meta.deserialize], but only if the #GstStructure does not contain any fields that cannot be serialized, see [gst.types.SerializeFlags.Strict].

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

Date information is handled using the [proleptic Gregorian calendar].

Provides basic creation functions and accessor functions to its fields.

[proleptic Gregorian calendar]: https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar

This is the struct that describes the categories. Once initialized with #GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore.

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

#GstDevice are created by #GstDeviceProvider objects which can be aggregated by #GstDeviceMonitor objects.

The class structure for a #GstDevice object.

Applications should create a #GstDeviceMonitor when they want to probe, list and monitor devices of a specific type. The #GstDeviceMonitor will create the appropriate #GstDeviceProvider objects and manage them. It will then post messages on its #GstBus 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;
 }

Opaque device monitor class structure.

A #GstDeviceProvider 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 #GstDeviceProvider subclass is a singleton, a plugin should normally provide a single subclass for all devices.

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

The structure of the base #GstDeviceProviderClass

#GstDeviceProviderFactory is used to create instances of device providers. A GstDeviceProviderfactory can be added to a #GstPlugin as it is also a #GstPluginFeature.

Use the [gst.device_provider_factory.DeviceProviderFactory.find] and [gst.device_provider_factory.DeviceProviderFactory.get] functions to create device provider instances or use [gst.device_provider_factory.DeviceProviderFactory.getByName] as a convenient shortcut.

The opaque #GstDeviceProviderFactoryClass data structure.

A fundamental type that describes a #gdouble range

#GstDynamicTypeFactory is used to represent a type that can be automatically loaded the first time it is used. For example, a non-standard type for use in caps fields.

In general, applications and plugins don't need to use the factory beyond registering the type in a plugin init function. Once that is done, the type is stored in the registry, and ready as soon as the registry is loaded.

Registering a type for dynamic loading

static gboolean
plugin_init (GstPlugin * plugin)
{
 return gst_dynamic_type_register (plugin, GST_TYPE_CUSTOM_CAPS_FIELD);
}

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 #GstElement subclasses.

The name of a #GstElement 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 #GstPad). These pads link to pads on other elements. #GstBuffer flow between these linked pads. A #GstElement has a #GList of #GstPad structures for all their input (or sink) and output (or source) pads. Core and plug-in writers can add and remove pads with [gst.element.Element.addPad] and [gst.element.Element.removePad].

An existing pad of an element can be retrieved by name with [gst.element.Element.getStaticPad]. A new dynamic pad can be created using [gst.element.Element.requestPad] with a #GstPadTemplate. An iterator of all pads can be retrieved with [gst.element.Element.iteratePads].

Elements can be linked through their pads. If the link is straightforward, use the [gst.element.Element.link] convenience function to link two elements, or [gst.element.Element.linkMany] for more elements in a row. Use [gst.element.Element.linkFiltered] to link two elements constrained by a specified set of #GstCaps. For finer control, use [gst.element.Element.linkPads] and [gst.element.Element.linkPadsFiltered] to specify the pads to link on each element by name.

Each element has a state (see #GstState). You can get and set the state of an element with [gst.element.Element.getState] and [gst.element.Element.setState]. Setting a state triggers a #GstStateChange. To get a string representation of a #GstState, use [gst.element.Element.stateGetName].

You can get and set a #GstClock on an element using [gst.element.Element.getClock] and [gst.element.Element.setClock]. Some elements can provide a clock for the pipeline if the #GST_ELEMENT_FLAG_PROVIDE_CLOCK flag is set. With the [gst.element.Element.provideClock] method one can retrieve the clock provided by such an element. Not all elements require a clock to operate correctly. If the #GST_ELEMENT_FLAG_REQUIRE_CLOCK() flag is set, a clock should be set on the element with [gst.element.Element.setClock].

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

GStreamer element class. Override the vmethods to implement the element functionality.

#GstElementFactory is used to create instances of elements. A GstElementFactory can be added to a #GstPlugin as it is also a #GstPluginFeature.

Use the [gst.element_factory.ElementFactory.find] and [gst.element_factory.ElementFactory.create] functions to create element instances or use [gst.element_factory.ElementFactory.make] as a convenient shortcut.

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

Using an element factory

#include <gst/gst.h>

 GstElement *src;
 GstElementFactory *srcfactory;

 gst_init (&argc, &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);
 ...

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 [gst.element.Element.sendEvent] and elements will use [gst.pad.Pad.sendEvent] or [gst.pad.Pad.pushEvent]. The event should be unreffed with gst_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 null 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 [gst.event.Event.newSeek] 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");
 ...

A fundamental type that describes a 32-bit flag bitfield, with 32-bit mask indicating which of the bits in the field are explicitly set.

A format definition

A fundamental type that describes a fraction of an integer numerator over an integer denominator

A fundamental type that describes a #GstFractionRange range

GhostPads are useful when organizing pipelines with #GstBin 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 #GstElement. 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, [gst.ghost_pad.GhostPad.new_] is the function to use to get a ghost-pad. Otherwise one can use [gst.ghost_pad.GhostPad.newNoTarget] to create the ghost-pad and use [gst.ghost_pad.GhostPad.setTarget] to establish the association later on.

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

A fundamental type that describes a #gint64 range

A fundamental type that describes a #gint range

A GstIterator is used to retrieve multiple objects from another object in a threadsafe way.

Various GStreamer objects provide access to their internal structures using an iterator.

Note that if calling a GstIterator function results in your code receiving a refcounted object (with, say, [gobject.value.Value.getObject]), the refcount for that object will not be increased. Your code is responsible for taking a reference if it wants to continue using it later.

The basic use pattern of an iterator is as follows:

GstIterator *it = _get_iterator(object);
 GValue item = G_VALUE_INIT;
 done = FALSE;
 while (!done) {
   switch (gst_iterator_next (it, &item)) {
     case GST_ITERATOR_OK:
       ...get/use/change item here...
       g_value_reset (&item);
       break;
     case GST_ITERATOR_RESYNC:
       ...rollback changes to items...
       gst_iterator_resync (it);
       break;
     case GST_ITERATOR_ERROR:
       ...wrong parameters were given...
       done = TRUE;
       break;
     case GST_ITERATOR_DONE:
       done = TRUE;
       break;
   }
 }
 g_value_unset (&item);
 gst_iterator_free (it);

A structure containing the result of a map operation such as [gst.memory.Memory.map]. It contains the data and size.

#GstMapInfo cannot be used with g_auto() because it is ambiguous whether it needs to be unmapped using [gst.buffer.Buffer.unmap] or [gst.memory.Memory.unmap]. Instead, #GstBufferMapInfo and #GstMemoryMapInfo can be used in that case.

GstMemory is a lightweight refcounted object that wraps a region of memory. They are typically used to manage the data of a #GstBuffer.

A GstMemory object has an allocated region of memory of maxsize. The maximum size does not change during the lifetime of the memory object. The memory also has an offset and size property that specifies the valid range of memory in the allocated region.

Memory is usually created by allocators with a [gst.allocator.Allocator.alloc] method call. When null is used as the allocator, the default allocator will be used.

New allocators can be registered with [gst.allocator.Allocator.register]. Allocators are identified by name and can be retrieved with [gst.allocator.Allocator.find]. [gst.allocator.Allocator.setDefault] can be used to change the default allocator.

New memory can be created with [gst.memory.Memory.newWrapped] that wraps the memory allocated elsewhere.

Refcounting of the memory block is performed with gst_memory_ref() and gst_memory_unref().

The size of the memory can be retrieved and changed with [gst.memory.Memory.getSizes] and [gst.memory.Memory.resize] respectively.

Getting access to the data of the memory is performed with [gst.memory.Memory.map]. The call will return a pointer to offset bytes into the region of memory. After the memory access is completed, [gst.memory.Memory.unmap] should be called.

Memory can be copied with [gst.memory.Memory.copy], which will return a writable copy. [gst.memory.Memory.share] will create a new memory block that shares the memory with an existing memory block at a custom offset and with a custom size.

Memory can be efficiently merged when [gst.memory.Memory.isSpan] returns true.

Messages are implemented as a subclass of #GstMiniObject with a generic #GstStructure 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 #GstBus.

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

gst_bus_post (bus, gst_message_new_eos());

A #GstElement usually posts messages on the bus provided by the parent container using [gst.element.Element.postMessage].

The #GstMeta structure should be included as the first member of a #GstBuffer metadata structure. The structure defines the API of the metadata and should be accessible to all elements using the metadata.

A metadata API is registered with [gst.meta.Meta.apiTypeRegister] which takes a name for the metadata API and some tags associated with the metadata. With [gst.meta.Meta.apiTypeHasTag] one can check if a certain metadata API contains a given tag.

Multiple implementations of a metadata API can be registered. To implement a metadata API, [gst.meta.Meta.register] should be used. This function takes all parameters needed to create, free and transform metadata along with the size of the metadata. The function returns a #GstMetaInfo structure that contains the information for the implementation of the API.

A specific implementation can be retrieved by name with [gst.meta.Meta.getInfo].

See #GstBuffer for how the metadata can be added, retrieved and removed from buffers.

The #GstMetaInfo provides information about a specific metadata structure.

Extra data passed to a "gst-copy" transform #GstMetaTransformFunction.

#GstMiniObject is a simple structure that can be used to implement refcounted types.

Subclasses will include #GstMiniObject as the first member in their structure and then call [gst.mini_object.MiniObject.init_] to initialize the #GstMiniObject fields.

[gst.mini_object.MiniObject.ref_] and [gst.mini_object.MiniObject.unref] increment and decrement the refcount respectively. When the refcount of a mini-object reaches 0, the dispose function is called first and when this returns true, the free function of the miniobject is called.

A copy can be made with [gst.mini_object.MiniObject.copy].

[gst.mini_object.MiniObject.isWritable] will return true when the refcount of the object is exactly 1 and there is no parent or a single parent exists and is writable itself, meaning the current caller has the only reference to the object. [gst.mini_object.MiniObject.makeWritable] will return a writable version of the object, which might be a new copy when the refcount was not 1.

Opaque data can be associated with a #GstMiniObject with [gst.mini_object.MiniObject.setQdata] and [gst.mini_object.MiniObject.getQdata]. The data is meant to be specific to the particular object and is not automatically copied with [gst.mini_object.MiniObject.copy] or similar methods.

A weak reference can be added and remove with [gst.mini_object.MiniObject.weakRef] and [gst.mini_object.MiniObject.weakUnref] respectively.

GStreamer base object class.

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

#GstObject 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 #GstObject which is #GObject (e.g. [gobject.object.ObjectWrap.ref_] becomes [gst.object.ObjectWrap.ref_]).

Since #GstObject derives from #GInitiallyUnowned, it also inherits the floating reference. Be aware that functions such as [gst.bin.Bin.add] and [gst.element.Element.addPad] take ownership of the floating reference.

In contrast to #GObject instances, #GstObject adds a name property. The functions [gst.object.ObjectWrap.setName] and [gst.object.ObjectWrap.getName] 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 #GstElement? 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 #GstControlSource.

csource = gst_interpolation_control_source_new (); g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);

• Attach the #GstControlSource 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

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

Pads have a #GstPadDirection, source pads produce data, sink pads consume data.

Pads are typically created from a #GstPadTemplate with [gst.pad.Pad.newFromTemplate] and are then added to a #GstElement. 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 [gst.pad.Pad.new_], which takes a direction and a name as an argument. If the name is null, then a guaranteed unique name will be assigned to it.

A #GstElement 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 #GstElement that owns the pad.

After two pads are retrieved from an element by [gst.element.Element.getStaticPad], the pads can be linked with [gst.pad.Pad.link]. (For quick links, you can also use [gst.element.Element.link], which will make the obvious link for you if it's straightforward.). Pads can be unlinked again with [gst.pad.Pad.unlink]. [gst.pad.Pad.getPeer] can be used to check what the pad is linked to.

Before dataflow is possible on the pads, they need to be activated with [gst.pad.Pad.setActive].

[gst.pad.Pad.query] and [gst.pad.Pad.peerQuery] can be used to query various properties of the pad and the stream.

To send a #GstEvent on a pad, use [gst.pad.Pad.sendEvent] and [gst.pad.Pad.pushEvent]. Some events will be sticky on the pad, meaning that after they pass on the pad they can be queried later with [gst.pad.Pad.getStickyEvent] and [gst.pad.Pad.stickyEventsForeach]. [gst.pad.Pad.getCurrentCaps] and [gst.pad.Pad.hasCurrentCaps] are convenience functions to query the current sticky CAPS event on a pad.

GstElements will use [gst.pad.Pad.push] and [gst.pad.Pad.pullRange] 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 [gst.pad.Pad.addProbe]. [gst.pad.Pad.isBlocked] can be used to check if a block probe is installed on the pad. [gst.pad.Pad.isBlocking] checks if the blocking probe is currently blocking the pad. [gst.pad.Pad.removeProbe] is used to remove a previously installed probe and unblock blocking probes if any.

Pad have an offset that can be retrieved with [gst.pad.Pad.getOffset]. This offset will be applied to the running_time of all data passing over the pad. [gst.pad.Pad.setOffset] can be used to change the offset.

Convenience functions exist to start, pause and stop the task on a pad with [gst.pad.Pad.startTask], [gst.pad.Pad.pauseTask] and [gst.pad.Pad.stopTask] respectively.

Info passed in the #GstPadProbeCallback.

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 #GstCaps attached to it to describe the media type they are capable of dealing with. [gst.pad_template.PadTemplate.getCaps] 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 #GstPadPresence 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 #GstPadTemplate 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 [gst.element.Element.requestPadSimple] call to instantiate a pad from this template.

Padtemplates can be created with [gst.pad_template.PadTemplate.new_] or with gst_static_pad_template_get (), which creates a #GstPadTemplate from a #GstStaticPadTemplate that can be filled with the convenient GST_STATIC_PAD_TEMPLATE() macro.

A padtemplate can be used to create a pad (see [gst.pad.Pad.newFromTemplate] 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 (&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, &my_template);
 }

A fundamental type that describes a #GParamSpec for arrays of values

A fundamental type that describes a #GParamSpec for fractional properties

A GParamSpec derived structure for arrays of values.

A GParamSpec derived structure that contains the meta data for fractional properties.

The #GstParentBufferMeta is a #GstMeta which can be attached to a #GstBuffer to hold a reference to another buffer that is only released when the child #GstBuffer is released.

Typically, #GstParentBufferMeta is used when the child buffer is directly using the #GstMemory of the parent buffer, and wants to prevent the parent buffer from being returned to a buffer pool until the #GstMemory is available for re-use.

Opaque structure.

A #GstPipeline is a special #GstBin used as the toplevel container for the filter graph. The #GstPipeline will manage the selection and distribution of a global #GstClock as well as provide a #GstBus to the application.

[gst.pipeline.Pipeline.new_] is used to create a pipeline. when you are done with the pipeline, use [gst.object.ObjectWrap.unref] to free its resources including all added #GstElement objects (if not otherwise referenced).

Elements are added and removed from the pipeline using the #GstBin methods like [gst.bin.Bin.add] and [gst.bin.Bin.remove] (see #GstBin).

Before changing the state of the #GstPipeline (see #GstElement) a #GstBus should be retrieved with [gst.pipeline.Pipeline.getBus]. This #GstBus should then be used to receive #GstMessage from the elements in the pipeline. Listening to the #GstBus is necessary for retrieving error messages from the #GstPipeline and otherwise the #GstPipeline might stop without any indication, why. Furthermore, the #GstPipeline posts messages even if nobody listens on the #GstBus, which will pile up and use up memory.

By default, a #GstPipeline will automatically flush the pending #GstBus messages when going to the NULL state to ensure that no circular references exist when no messages are read from the #GstBus. This behaviour can be changed with [gst.pipeline.Pipeline.setAutoFlushBus].

When the #GstPipeline 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 #GST_STATE_CHANGE_NO_PREROLL from the [gst.element.Element.setState] 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 #GstSystemClock is used.

The clock selection can be controlled with the [gst.pipeline.Pipeline.useClock] method, which will enforce a given clock on the pipeline. With [gst.pipeline.Pipeline.autoClock] the default clock selection algorithm can be restored.

A #GstPipeline 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 [gst.element.Element.setStartTime] method.

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

A plugin should export a symbol gst_plugin_desc that is a struct of type #GstPluginDesc. the plugin loader will check the version of the core library the plugin was linked against and will create a new #GstPlugin. It will then call the #GstPluginInitFunc function that was provided in the gst_plugin_desc.

Once you have a handle to a #GstPlugin (e.g. from the #GstRegistry), you can add any object that subclasses #GstPluginFeature.

Usually plugins are always automatically loaded so you don't need to call [gst.plugin.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 [gst.plugin.Plugin.load] can be needed to bring the plugin into memory.

A plugin should export a variable of this type called plugin_desc. The plugin loader will use the data provided there to initialize the plugin.

The @licence parameter must be one of: LGPL, GPL, QPL, GPL/QPL, MPL, BSD, MIT/X11, Proprietary, unknown.

This is a base class for anything that can be added to a #GstPlugin.

A #GstPoll keeps track of file descriptors much like fd_set (used with select ()) or a struct pollfd array (used with poll ()). Once created with [gst.poll.Poll.new_], the set can be used to wait for file descriptors to be readable and/or writable. It is possible to make this wait be controlled by specifying true for the @controllable flag when creating the set (or later calling [gst.poll.Poll.setControllable]).

New file descriptors are added to the set using [gst.poll.Poll.addFd], and removed using [gst.poll.Poll.removeFd]. Controlling which file descriptors should be waited for to become readable and/or writable are done using [gst.poll.Poll.fdCtlRead], [gst.poll.Poll.fdCtlWrite] and [gst.poll.Poll.fdCtlPri].

Use [gst.poll.Poll.wait] to wait for the file descriptors to actually become readable and/or writable, or to timeout if no file descriptor is available in time. The wait can be controlled by calling [gst.poll.Poll.restart] and [gst.poll.Poll.setFlushing].

Once the file descriptor set has been waited for, one can use [gst.poll.Poll.fdHasClosed] to see if the file descriptor has been closed, [gst.poll.Poll.fdHasError] to see if it has generated an error, [gst.poll.Poll.fdCanRead] to see if it is possible to read from the file descriptor, and [gst.poll.Poll.fdCanWrite] to see if it is possible to write to it.

A file descriptor object.

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 [gst.preset.Preset.getPropertyNames]. 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 [gst.preset.Preset.savePreset] and [gst.preset.Preset.deletePreset] to null. Applications can use [gst.preset.Preset.isEditable] 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".

#GstPreset interface.

The #GstPromise object implements the container for values that may be available later. i.e. a Future or a Promise in

As with all Future/Promise-like functionality, there is the concept of the producer of the value and the consumer of the value.

A #GstPromise is created with [gst.promise.Promise.new_] by the consumer and passed to the producer to avoid thread safety issues with the change callback. A #GstPromise can be replied to with a value (or an error) by the producer with [gst.promise.Promise.reply]. The exact value returned is defined by the API contract of the producer and null may be a valid reply. [gst.promise.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 @GST_PROMISE_RESULT_EXPIRED state set by a call to [gst.promise.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 #GstBus. A callback can also be installed at #GstPromise creation for result changes with [gst.promise.Promise.newWithChangeFunc]. 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 #GstPromise starts out with a #GstPromiseResult of [gst.types.PromiseResult.Pending] and only ever transitions once into one of the other #GstPromiseResult's.

In order to support multi-threaded code, [gst.promise.Promise.reply], [gst.promise.Promise.interrupt] and [gst.promise.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 [gst.promise.Promise.reply] and [gst.promise.Promise.interrupt] cannot be called

after [gst.promise.Promise.expire]

1. That [gst.promise.Promise.reply] and [gst.promise.Promise.interrupt]

cannot be called twice.

The change function set with [gst.promise.Promise.newWithChangeFunc] is called directly from either the [gst.promise.Promise.reply], [gst.promise.Promise.interrupt] or [gst.promise.Promise.expire] and can be called from an arbitrary thread. #GstPromise using APIs can restrict this to a single thread or a subset of threads but that is entirely up to the API that uses #GstPromise.

Metadata type that holds information about a sample from a protection-protected track, including the information needed to decrypt it (if it is encrypted).

Queries can be performed on pads ([gst.pad.Pad.query]) and elements ([gst.element.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, &duration);
   g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration));
 } else {
   g_print ("duration query failed...");
 }
 gst_query_unref (query);

#GstReferenceTimestampMeta can be used to attach alternative timestamps and possibly durations to a #GstBuffer. These are generally not according to the pipeline clock and could be e.g. the NTP timestamp when the media was captured.

The reference is stored as a #GstCaps in @reference. Examples of valid references would be

• timestamp/x-drivername-stream: for timestamps that are locally

generated by some driver named drivername when generating the stream, e.g. based on a frame counter

• timestamp/x-ntp, host=pool.ntp.org, port=123: for timestamps based on a

specific NTP server. Note that the host/port parameters might not always be given.

• timestamp/x-ptp, version=IEEE1588-2008, domain=1: for timestamps based

on a given PTP clock.

• timestamp/x-unix: for timestamps based on the UNIX epoch according to

the local clock.

Since 1.24 it can be serialized using [gst.meta.Meta.serialize] and [gst.meta.Meta.deserialize].

One registry holds the metadata of a set of plugins.

The #GstRegistry object is a list of plugins and some functions for dealing with them. Each #GstPlugin 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/.

$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 [gst.types.PluginFlags.Cached] bit. These plugins are removed at the end of initialization.

A #GstSample is a small object containing data, a type, timing and extra arbitrary information.

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 [gst.segment.Segment.init_], which takes a #GstFormat 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 [gst.segment.Segment.doSeek] 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 #GstSegment to track the playback region, update the segment fields with the information from the newsegment event. The [gst.segment.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, [gst.segment.Segment.toRunningTime] 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, [gst.segment.Segment.toStreamTime] 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).

The #GstSharedTaskPool object.

The #GstSharedTaskPoolClass object.

Data structure to initialize #GstCaps from a string description usually used in conjunction with GST_STATIC_CAPS() and [gst.static_caps.StaticCaps.get] to instantiate a #GstCaps.

Structure describing the #GstStaticPadTemplate.

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

A #GstStream 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 #GstStream contains all the information pertinent to a stream, such as stream-id, tags, caps, type, ...

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

GstStream class structure

A collection of #GstStream that are available.

A #GstStreamCollection 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 %[gst.stream_collection.StreamCollection.getStream]

Once posted, a #GstStreamCollection is immutable. Updates are made by sending a new #GstStreamCollection message, which may or may not share some of the #GstStream 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 #GstStreamCollection.

Applications can activate streams from a collection by using the #GST_EVENT_SELECT_STREAMS event on a pipeline, bin or element.

GstStreamCollection class structure

A #GstStructure 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 #GstStructure also has a name. The name starts with a letter and can be filled by letters, numbers and any of "/-_.:".

#GstStructure is used by various GStreamer subsystems to store information in a flexible and extensible way. A #GstStructure does not have a refcount because it usually is part of a higher level object such as #GstCaps, #GstMessage, #GstEvent, #GstQuery. It provides a means to enforce mutability using the refcount of the parent with the [gst.structure.Structure.setParentRefcount] method.

A #GstStructure can be created with [gst.structure.Structure.newEmpty] or [gst.structure.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 [gst.structure.Structure.setValue] or [gst.structure.Structure.set].

Field values can be retrieved with [gst.structure.Structure.getValue] or the more convenient gst_structure_get_*() functions.

Fields can be removed with [gst.structure.Structure.removeField] or [gst.structure.Structure.removeFields].

Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not allowed. Strings may be null 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

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 [harfbuzz.types.int] while 1.0 is a double).

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 semicolon ; 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:
CODEBLOCK2
They also allow for nested structure, such as:
CODEBLOCK3
Since 1.20, nested structures and caps can be specified using brackets ([ and ]`, for example:

a-struct, nested=[nested-struct, nested=true]

note: [gst.structure.Structure.toString_] won't use that syntax for backward

compatibility reason, [gst.structure.Structure.serializeFull] has been added for that purpose.

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.

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

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. [gst.tag_setter.TagSetter.mergeTags] or [gst.tag_setter.TagSetter.addTags]. Also consider setting the #GstTagMergeMode 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 [gst.types.State.Paused].

Elements implementing the #GstTagSetter 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);

#GstTagSetterInterface interface.

#GstTask is used by #GstElement and #GstPad to provide the data passing threads in a #GstPipeline.

A #GstPad will typically start a #GstTask to push or pull data to/from the peer pads. Most source elements start a #GstTask to push data. In some cases a demuxer element can start a #GstTask to pull data from a peer element. This is typically done when the demuxer can perform random access on the upstream peer element for improved performance.

Although convenience functions exist on #GstPad to start/pause/stop tasks, it might sometimes be needed to create a #GstTask manually if it is not related to a #GstPad.

Before the #GstTask can be run, it needs a #GRecMutex that can be set with [gst.task.Task.setLock].

The task can be started, paused and stopped with [gst.task.Task.start], [gst.task.Task.pause] and [gst.task.Task.stop] respectively or with the [gst.task.Task.setState] function.

A #GstTask will repeatedly call the #GstTaskFunction with the user data that was provided when creating the task with [gst.task.Task.new_]. While calling the function it will acquire the provided lock. The provided lock is released when the task pauses or stops.

Stopping a task with [gst.task.Task.stop] will not immediately make sure the task is not running anymore. Use [gst.task.Task.join] to make sure the task is completely stopped and the thread is stopped.

After creating a #GstTask, use [gst.object.ObjectWrap.unref] to free its resources. This can only be done when the task is not running anymore.

Task functions can send a #GstMessage to send out-of-band data to the application. The application can receive messages from the #GstBus in its mainloop.

For debugging purposes, the task will configure its object name as the thread name on Linux. Please note that the object name should be configured before the task is started; changing the object name after the task has been started, has no effect on the thread name.

This object provides an abstraction for creating threads. The default implementation uses a regular GThreadPool to start tasks.

Subclasses can be made to create custom threads.

The #GstTaskPoolClass object.

Structure for storing a timestamp and a value.

#GstToc functions are used to create/free #GstToc and #GstTocEntry structures. Also they are used to convert #GstToc into #GstStructure and vice versa.

#GstToc 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 #GstToc structure which represents root contents of the source. You can also attach TOC-specific tags to it. Then fill it with #GstTocEntry entries by appending them to the #GstToc using [gst.toc.Toc.appendEntry], and appending subentries to a #GstTocEntry using [gst.toc_entry.TocEntry.appendSubEntry].

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 [gst.event.Event.newToc] to create a new TOC #GstEvent, and [gst.event.Event.parseToc] to parse received TOC event. Use [gst.event.Event.newTocSelect] to create a new TOC select #GstEvent, and [gst.event.Event.parseTocSelect] to parse received TOC select event. The same rule for the #GstMessage: [gst.message.Message.newToc] to create new TOC #GstMessage, and [gst.message.Message.parseToc] 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).

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 [gst.toc_setter.TocSetter.setToc].

Elements implementing the #GstTocSetter interface can extend existing TOC by getting extend UID for that (you can use [gst.toc.Toc.findEntry] to retrieve it) with any TOC entries received from downstream.

#GstTocSetterInterface interface.

Tracing modules will subclass #GstTracer and register through [gst.tracer.Tracer.register]. Modules can attach to various hook-types - see [gst.global.tracingRegisterHook]. When invoked they receive hook specific contextual data, which they must not modify.

Use [gst.tracer_factory.TracerFactory.getList] to get a list of tracer factories known to GStreamer.

Tracing modules will create instances of this class to announce the data they will log and create a log formatter.

The following functions allow you to detect the media type of an unknown stream.

These functions allow querying information about registered typefind functions. How to create and register these functions is described in the section <link linkend="gstreamer-Writing-typefind-functions"> "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 >= 0 && offset + size <= find->size) {
     return find->data + offset;
   }
   return NULL;
 }
 static void
 my_suggest (gpointer data, guint probability, GstCaps *caps)
 {
   MyTypeFind *find = (MyTypeFind *) data;
   if (probability > find->probability) {
     find->probability = probability;
     gst_caps_replace (&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, &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, &gst_find);
   }
   g_list_free (type_list);
   return find.caps;
 };

The #GstURIHandler is an interface that is implemented by Source and Sink #GstElement 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 ([gst.element.Element.makeFromUri]).

Source and Sink plugins should implement this interface when possible.

Any #GstElement using this interface should implement these methods.

A #GstUri object can be used to parse and split a URI string into its constituent parts. Two #GstUri objects can be joined to make a new #GstUri using the algorithm described in RFC3986.

A fundamental type that describes an ordered list of #GValue

A fundamental type that describes an unordered list of #GValue

VTable for the #GValue @type.