Caps

class Caps(*args, **kwargs)

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

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

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

A Caps can be constructed with the following code fragment:

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

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

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

Be aware that until 1.20 the Caps / Structure serialization into string had limited support for nested Caps / Structure fields. It could only support one level of nesting. Using more levels would lead to unexpected behavior when using serialization features, such as to_string() or value_serialize() and their counterparts.

Constructors

class Caps
classmethod new_any() → Caps

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

classmethod new_empty() → Caps

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

classmethod new_empty_simple(media_type: str) → Caps

Creates a new Caps that contains one Structure with name media_type.

Parameters:

media_type – the media type of the structure

Methods

class Caps
append(caps2: Caps) → None

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

Parameters:

caps2 – the Caps to append

append_structure(structure: Structure) → None

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

Parameters:

structure – the Structure to append

append_structure_full(structure: Structure, features: CapsFeatures | None = None) → None

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

Added in version 1.2.

Parameters:
can_intersect(caps2: Caps) → bool

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

Parameters:

caps2 – a Caps to intersect

filter_and_map_in_place(func: Callable[[...], bool], *user_data: Any) → None

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

Added in version 1.6.

Parameters:

  • func – a function to call for each field

  • user_data – private data

fixate() → Caps

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

This function takes ownership of caps and will call caps_make_writable() on it so you must not use caps afterwards unless you keep an additional reference to it with gst_caps_ref().

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

Calling this function with ANY caps is not allowed.

foreach(func: Callable[[...], bool], *user_data: Any) → bool

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

Added in version 1.6.

Parameters:

  • func – a function to call for each field

  • user_data – private data

from_string(string: str) → Caps | None

Converts caps from a string representation.

The implementation of serialization up to 1.20 would lead to unexpected results when there were nested Caps / Structure deeper than one level.

Parameters:

string – a string to convert to Caps

get_features(index: int) → CapsFeatures | None

Finds the features in caps at index, and returns it.

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

Added in version 1.2.

Parameters:

index – the index of the structure

get_size() → int

Gets the number of structures contained in caps.

get_structure(index: int) → Structure

Finds the structure in caps at index, and returns it.

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

Parameters:

index – the index of the structure

intersect(caps2: Caps) → Caps

Creates a new Caps that contains all the formats that are common to both caps1 and caps2. Defaults to ZIG_ZAG mode.

Parameters:

caps2 – a Caps to intersect

intersect_full(caps2: Caps, mode: CapsIntersectMode) → Caps

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

Parameters:

  • caps2 – a Caps to intersect

  • mode – The intersection algorithm/mode to use

is_always_compatible(caps2: Caps) → bool

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

Parameters:

caps2 – the Caps to test

is_any() → bool

Determines if caps represents any media format.

is_empty() → bool

Determines if caps represents no media formats.

is_equal(caps2: Caps) → bool

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

Parameters:

caps2 – another Caps

is_equal_fixed(caps2: Caps) → bool

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

Parameters:

caps2 – the Caps to test

is_fixed() → bool

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

is_strictly_equal(caps2: Caps) → bool

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

Parameters:

caps2 – another Caps

is_subset(superset: Caps) → bool

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

Parameters:

superset – a potentially greater Caps

is_subset_structure(structure: Structure) → bool

Checks if structure is a subset of caps. See is_subset() for more information.

Parameters:

structure – a potential Structure subset of caps

is_subset_structure_full(structure: Structure, features: CapsFeatures | None = None) → bool

Checks if structure is a subset of caps. See is_subset() for more information.

Added in version 1.2.

Parameters:
map_in_place(func: Callable[[...], bool], *user_data: Any) → bool

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

Added in version 1.6.

Parameters:

  • func – a function to call for each field

  • user_data – private data

merge(caps2: Caps) → Caps

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

Parameters:

caps2 – the Caps to merge in

merge_structure(structure: Structure) → Caps

Appends structure to caps if it is not already expressed by caps.

Parameters:

structure – the Structure to merge

merge_structure_full(structure: Structure, features: CapsFeatures | None = None) → Caps

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

Added in version 1.2.

Parameters:
normalize() → Caps

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

This function takes ownership of caps and will call caps_make_writable() on it so you must not use caps afterwards unless you keep an additional reference to it with gst_caps_ref().

remove_structure(idx: int) → None

Removes the structure with the given index from the list of structures contained in caps.

Parameters:

idx – Index of the structure to remove

serialize(flags: SerializeFlags) → str

Converts caps to a string representation. This string representation can be converted back to a Caps by from_string().

This prints the caps in human readable form.

This version of the caps serialization function introduces support for nested structures and caps but the resulting strings won’t be parsable with GStreamer prior to 1.20 unless GST_SERIALIZE_FLAG_BACKWARD_COMPAT is passed as flag.

Added in version 1.20.

Parameters:

flags – a SerializeFlags

set_features(index: int, features: CapsFeatures | None = None) → None

Sets the features for the structure at index.

Added in version 1.2.

Parameters:

  • index – the index of the structure

  • features – the CapsFeatures to set

set_features_simple(features: CapsFeatures | None = None) → None

Sets the features for all the structures of caps.

Added in version 1.16.

Parameters:

features – the CapsFeatures to set

set_value(field: str, value: Any) → None

Sets the given field on all structures of caps to the given value. This is a convenience function for calling set_value() on all structures of caps.

Parameters:

  • field – name of the field to set

  • value – value to set the field to

simplify() → Caps

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

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

This method does not preserve the original order of caps.

subtract(subtrahend: Caps) → Caps

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

Parameters:

subtrahend – Caps to subtract

to_string() → str

Converts caps to a string representation. This string representation can be converted back to a Caps by from_string().

For debugging purposes its easier to do something like this:

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

This prints the caps in human readable form.

The implementation of serialization up to 1.20 would lead to unexpected results when there were nested Caps / Structure deeper than one level.

truncate() → Caps

Discards all but the first structure from caps. Useful when fixating.

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

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

Fields

class Caps
mini_object

The parent type