GES.TrackElement

g GES.Extractable GES.Extractable GES.TimelineElement GES.TimelineElement GES.Extractable->GES.TimelineElement GES.MetaContainer GES.MetaContainer GES.MetaContainer->GES.TimelineElement GES.TrackElement GES.TrackElement GES.TimelineElement->GES.TrackElement GObject.GInterface GObject.GInterface GObject.GInterface->GES.Extractable GObject.GInterface->GES.MetaContainer GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->GES.TimelineElement GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned

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

Description

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

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

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.