GES.TrackElement¶

Subclasses:: GES.Operation, GES.Source

Methods¶

Inherited:: GES.TimelineElement (38), GObject.Object (37), GES.Extractable (3), GES.MetaContainer (40)
Structs:: GObject.ObjectClass (5)

	`add_children_props` (element, wanted_categories, blacklist, whitelist)
	`clamp_control_source` (property_name)
	`edit` (layers, mode, edge, position)
	`get_all_control_bindings` ()
	`get_auto_clamp_control_sources` ()
	`get_control_binding` (property_name)
	`get_element` ()
	`get_gnlobject` ()
	`get_nleobject` ()
	`get_track` ()
	`get_track_type` ()
	`has_internal_source` ()
	`is_active` ()
	`is_core` ()
	`list_children_properties` ()
	`lookup_child` (prop_name)
	`remove_control_binding` (property_name)
	`set_active` (active)
	`set_auto_clamp_control_sources` (auto_clamp)
	`set_control_source` (source, property_name, binding_type)
	`set_has_internal_source` (has_internal_source)
	`set_track_type` (type)

Virtual Methods¶

Inherited:: GES.TimelineElement (18), GObject.Object (7), GES.Extractable (3)

	`do_active_changed` (active)
	`do_changed` ()
	`do_create_element` ()
	`do_create_gnl_object` ()
	`do_lookup_child` (prop_name)

Properties¶

Inherited:: GES.TimelineElement (9)

Name	Type	Flags	Short Description
`active`	`bool`	r/w/en	Use object in output
`auto-clamp-control-sources`	`bool`	r/w/en	Whether to automatically update the control sources with a change in in-point or out-point
`has-internal-source`	`bool`	r/w/en	Whether the element has some internal source of stream data
`track`	`GES.Track`	r	The track the object is in
`track-type`	`GES.TrackType`	r/w/c/en	The track type of the object

Signals¶

Inherited:: GES.TimelineElement (3), GObject.Object (1), GES.MetaContainer (1)

Name	Short Description
`control-binding-added`	This is emitted when a control binding is added to a child property of the track element.
`control-binding-removed`	This is emitted when a control binding is removed from a child property of the track element.

Fields¶

Inherited:: GES.TimelineElement (3), GObject.Object (1), GES.MetaContainer (1)

Name	Type	Access
active	`bool`	r
asset	`GES.Asset`	r
parent	`GES.TimelineElement`	r

Class Details¶

class GES.TrackElement(**kwargs)¶

Bases:: GES.TimelineElement
Abstract:: Yes
Structure:: GES.TrackElementClass

A GES.TrackElement is a GES.TimelineElement that specifically belongs to a single GES.Track of its GES.TimelineElement :timeline. Its GES.TimelineElement :start and GES.TimelineElement :duration specify its temporal extent in the track. Specifically, a track element wraps some nleobject, such as an #nlesource or #nleoperation, which can be retrieved with GES.TrackElement.get_nleobject(), and its GES.TimelineElement :start, GES.TimelineElement :duration, GES.TimelineElement :in-point, GES.TimelineElement :priority and GES.TrackElement :active properties expose the corresponding nleobject properties. When a track element is added to a track, its nleobject is added to the corresponding #nlecomposition that the track wraps.

Most users will not have to work directly with track elements since a GES.Clip will automatically create track elements for its timeline’s tracks and take responsibility for updating them. The only track elements that are not automatically created by clips, but a user is likely to want to create, are GES.Effect-s.

Control Bindings for Children Properties

You can set up control bindings for a track element child property using GES.TrackElement.set_control_source(). A #GstTimedValueControlSource should specify the timed values using the internal source coordinates (see GES.TimelineElement). By default, these will be updated to lie between the GES.TimelineElement :in-point and out-point of the element. This can be switched off by setting GES.TrackElement :auto-clamp-control-sources to False.

add_children_props(element, wanted_categories, blacklist, whitelist)[source]¶

Parameters:

element (Gst.Element) – The child object to retrieve properties from
wanted_categories ([str] or None) – An array of element factory “klass” categories to whitelist, or None to accept all categories
blacklist ([str] or None) – A blacklist of element factory names, or None to not blacklist any element factory
whitelist ([str] or None) – A whitelist of element property names, or None to whitelist all writeable properties

Adds all the properties of a Gst.Element that match the criteria as children properties of the track element. If the name of element's Gst.ElementFactory is not in blacklist, and the factory’s Gst.ELEMENT_METADATA_KLASS contains at least one member of wanted_categories (e.g. Gst.ELEMENT_FACTORY_KLASS_DECODER), then all the properties of element that are also in whitelist are added as child properties of self using GES.TimelineElement.add_child_property().

This is intended to be used by subclasses when constructing.

clamp_control_source(property_name)[source]¶

Parameters:: property_name (str) – The name of the child property to clamp the control source of

Clamp the #GstTimedValueControlSource for the specified child property to lie between the GES.TimelineElement :in-point and out-point of the element. The out-point is the #GES_TIMELINE_ELEMENT_END of the element translated from the timeline coordinates to the internal source coordinates of the element.

If the property does not have a #GstTimedValueControlSource set by GES.TrackElement.set_control_source(), nothing happens. Otherwise, if a timed value for the control source lies before the in-point of the element, or after its out-point, then it will be removed. At the in-point and out-point times, a new interpolated value will be placed.

New in version 1.18.

edit(layers, mode, edge, position)[source]¶

Parameters:

layers ([GES.Layer] or None) – A whitelist of layers where the edit can be performed, None allows all layers in the timeline
mode (GES.EditMode) – The edit mode
edge (GES.Edge) – The edge of self where the edit should occur
position (int) – The edit position: a new location for the edge of self (in nanoseconds)

Returns:

True if the edit of self completed, False on failure.

Return type:

bool

Edits the element within its track.

Deprecated since version 1.18: use GES.TimelineElement.edit instead.

get_all_control_bindings()[source]¶

Returns:: A hash table containing all child-property-name/control-binding pairs for self.
Return type:: {str: Gst.ControlBinding}

Get all the control bindings that have been created for the children properties of the track element using GES.TrackElement.set_control_source(). The keys used in the returned hash table are the child property names that were passed to GES.TrackElement.set_control_source(), and their values are the corresponding created Gst.ControlBinding.

get_auto_clamp_control_sources()[source]¶

Returns:: Whether the control sources for the child properties of self are automatically clamped.
Return type:: bool

Gets GES.TrackElement :auto-clamp-control-sources.

New in version 1.18.

get_control_binding(property_name)[source]¶

Parameters:: property_name (str) – The name of the child property to return the control binding of
Returns:: The control binding that was created for the specified child property of self, or None if property_name does not correspond to any control binding.
Return type:: Gst.ControlBinding or None

Gets the control binding that was created for the specified child property of the track element using GES.TrackElement.set_control_source(). The given property_name must be the same name of the child property that was passed to GES.TrackElement.set_control_source().

get_element()[source]¶

Returns:: The Gst.Element being controlled by the nleobject that self wraps.
Return type:: Gst.Element or None

Get the Gst.Element that the track element’s underlying nleobject controls.

get_gnlobject()[source]¶

Returns:: The GNonLin object this object is controlling.
Return type:: Gst.Element

Get the GNonLin object this object is controlling.

Deprecated since version ???: use GES.TrackElement.get_nleobject instead.

get_nleobject()[source]¶

Returns:: The nleobject that self wraps.
Return type:: Gst.Element

Get the nleobject that this element wraps.

New in version 1.6.

get_track()[source]¶

Returns:: The track that self belongs to, or None if it does not belong to a track.
Return type:: GES.Track or None

Get the GES.TrackElement :track for the element.

get_track_type()[source]¶

Returns:: The track-type of self.
Return type:: GES.TrackType

Gets the GES.TrackElement :track-type for the element.

has_internal_source()[source]¶

Returns:: True if self can have its ‘internal time’ properties set.
Return type:: bool

Gets GES.TrackElement :has-internal-source for the element.

New in version 1.18.

is_active()[source]¶

Returns:: True if self is active in its track.
Return type:: bool

Gets GES.TrackElement :active for the element.

is_core()[source]¶

Returns:: True if element is a core track element.
Return type:: bool

Get whether the given track element is a core track element. That is, it was created by the create_track_elements GES.ClipClass method for some GES.Clip.

Note that such a track element can only be added to a clip that shares the same GES.Asset as the clip that created it. For example, you are allowed to move core children between clips that resulted from GES.Container.ungroup(), but you could not move the core child from a GES.UriClip to a GES.TitleClip or another GES.UriClip with a different GES.UriClip :uri.

Moreover, if a core track element is added to a clip, it will always be added as a core child. Therefore, if this returns True, then element will be a core child of its parent clip.

New in version 1.18.

list_children_properties()[source]¶

Returns:: An array of GObject.ParamSpec which should be freed after use or None if something went wrong.
Return type:: [GObject.ParamSpec]

Gets an array of GObject.ParamSpec for all configurable properties of the children of self.

Deprecated since version ???: Use GES.TimelineElement.list_children_properties

lookup_child(prop_name)[source]¶

Parameters:

prop_name (str) – Name of the property to look up. You can specify the name of the class as such: “ClassName::property-name”, to guarantee that you get the proper GObject.ParamSpec in case various Gst.Element-s contain the same property name. If you don’t do so, you will get the first element found, having this property and the and the corresponding GObject.ParamSpec.

Returns:

True if element and pspec could be found. False otherwise. In that case the values for pspec and element are not modified. Unref element after usage.

element:: pointer to a Gst.Element that takes the real object to set property on
pspec:: pointer to take the specification describing the property

Return type:

(bool, element: Gst.Element, pspec: GObject.ParamSpec)

Looks up which element and pspec would be effected by the given name. If various contained elements have this property name you will get the first one, unless you specify the class name in name.

Deprecated since version ???: Use GES.TimelineElement.lookup_child

remove_control_binding(property_name)[source]¶

Parameters:: property_name (str) – The name of the child property to remove the control binding from
Returns:: True if the control binding was removed from the specified child property of self, or False if an error occurred.
Return type:: bool

Removes the Gst.ControlBinding that was created for the specified child property of the track element using GES.TrackElement.set_control_source(). The given property_name must be the same name of the child property that was passed to GES.TrackElement.set_control_source().

set_active(active)[source]¶

Parameters:: active (bool) – Whether self should be active in its track
Returns:: True if the property was *toggled*.
Return type:: bool

Sets GES.TrackElement :active for the element.

set_auto_clamp_control_sources(auto_clamp)[source]¶

Parameters:: auto_clamp (bool) – Whether to automatically clamp the control sources for the child properties of self

Sets GES.TrackElement :auto-clamp-control-sources. If set to True, this will immediately clamp all the control sources.

New in version 1.18.

set_control_source(source, property_name, binding_type)[source]¶

Parameters:

source (Gst.ControlSource) – The control source to bind the child property to
property_name (str) – The name of the child property to control
binding_type (str) – The type of binding to create (“direct” or “direct-absolute”)

Returns:

True if the specified child property could be bound to source, or False if an error occurred.

Return type:

bool

Creates a Gst.ControlBinding for the specified child property of the track element using the given control source. The given property_name should refer to an existing child property of the track element, as used in GES.TimelineElement.lookup_child().

If binding_type is “direct”, then the control binding is created with gst_direct_control_binding_new() using the given control source. If binding_type is “direct-absolute”, it is created with gst_direct_control_binding_new_absolute() instead.

set_has_internal_source(has_internal_source)[source]¶

Parameters:: has_internal_source (bool) – Whether the self should be allowed to have its ‘internal time’ properties set.
Returns:: False if has_internal_source is forbidden for self and True in any other case.
Return type:: bool

Sets GES.TrackElement :has-internal-source for the element. If this is set to False, this method will also set the GES.TimelineElement :in-point of the element to 0 and its GES.TimelineElement :max-duration to Gst.CLOCK_TIME_NONE.

New in version 1.18.

set_track_type(type)[source]¶

Parameters:: type (GES.TrackType) – The new track-type for self

Sets the GES.TrackElement :track-type for the element.

do_active_changed(active) virtual¶

Parameters:: active (bool) – Whether the element is active or not inside the #nlecomposition

Notify when the GES.TrackElement :active property changes

do_changed() virtual¶

do_create_element() virtual¶

Returns:: the Gst.Element that the underlying nleobject controls.
Return type:: Gst.Element

do_create_gnl_object() virtual¶

Returns:: the #NLEObject to use in the #nlecomposition
Return type:: Gst.Element

do_lookup_child(prop_name) virtual¶

Parameters:

prop_name (str) – Name of the property to look up. You can specify the name of the class as such: “ClassName::property-name”, to guarantee that you get the proper GObject.ParamSpec in case various Gst.Element-s contain the same property name. If you don’t do so, you will get the first element found, having this property and the and the corresponding GObject.ParamSpec.

Returns:

True if element and pspec could be found. False otherwise. In that case the values for pspec and element are not modified. Unref element after usage.

element:: pointer to a Gst.Element that takes the real object to set property on
pspec:: pointer to take the specification describing the property

Return type:

(bool, element: Gst.Element, pspec: GObject.ParamSpec)

Looks up which element and pspec would be effected by the given name. If various contained elements have this property name you will get the first one, unless you specify the class name in name.

Deprecated since version 1.14: Use GES.TimelineElement.lookup_child

Signal Details¶

GES.TrackElement.signals.control_binding_added(track_element, control_binding)¶

Signal Name:

control-binding-added

Flags:

RUN_FIRST

Parameters:

track_element (GES.TrackElement) – The object which received the signal
control_binding (Gst.ControlBinding) – The control binding that has been added

This is emitted when a control binding is added to a child property of the track element.

GES.TrackElement.signals.control_binding_removed(track_element, control_binding)¶

Signal Name:

control-binding-removed

Flags:

RUN_FIRST

Parameters:

track_element (GES.TrackElement) – The object which received the signal
control_binding (Gst.ControlBinding) – The control binding that has been removed

This is emitted when a control binding is removed from a child property of the track element.

Property Details¶

GES.TrackElement.props.active¶

Name:: active
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the effect of the element should be applied in its GES.TrackElement :track. If set to False, it will not be used in the output of the track.

GES.TrackElement.props.auto_clamp_control_sources¶

Name:: auto-clamp-control-sources
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the control sources on the element (see GES.TrackElement.set_control_source()) will be automatically updated whenever the GES.TimelineElement :in-point or out-point of the element change in value.

See GES.TrackElement.clamp_control_source() for how this is done per control source.

Default value: True

New in version 1.18.

GES.TrackElement.props.has_internal_source¶

Name:: has-internal-source
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

This property is used to determine whether the ‘internal time’ properties of the element have any meaning. In particular, unless this is set to True, the GES.TimelineElement :in-point and GES.TimelineElement :max-duration can not be set to any value other than the default 0 and Gst.CLOCK_TIME_NONE, respectively.

If an element has some *internal* *timed* source Gst.Element that it reads stream data from as part of its function in a GES.Track, then you’ll likely want to set this to True to allow the GES.TimelineElement :in-point and GES.TimelineElement :max-duration to be set.

The default value is determined by the GES.TrackElementClass default_has_internal_source class property. For most GES.SourceClass-es, this will be True, with the exception of those that have a potentially *static* source, such as GES.ImageSourceClass and GES.TitleSourceClass. Otherwise, this will usually be False.

For most GES.Operation-s you will likely want to leave this set to False. The exception may be for an operation that reads some stream data from some private internal source as part of manipulating the input data from the usual linked upstream GES.TrackElement.

For example, you may want to set this to True for a GES.TrackType.VIDEO operation that wraps a #textoverlay that reads from a subtitle file and places its text on top of the received video data. The GES.TimelineElement :in-point of the element would be used to shift the initial seek time on the #textoverlay away from 0, and the GES.TimelineElement :max-duration could be set to reflect the time at which the subtitle file runs out of data.

Note that GES can not support track elements that have both internal content and manipulate the timing of their data streams (time effects).

New in version 1.18.

GES.TrackElement.props.track¶

Name:: track
Type:: GES.Track
Default Value:: None
Flags:: READABLE

The track that this element belongs to, or None if it does not belong to a track.

GES.TrackElement.props.track_type¶

Name:: track-type
Type:: GES.TrackType
Default Value:: GES.TrackType.UNKNOWN
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

The track type of the element, which determines the type of track the element can be added to (see GES.Track :track-type). This should correspond to the type of data that the element can produce or process.