GES.TimelineElement

g GES.Extractable GES.Extractable GES.TimelineElement GES.TimelineElement GES.Extractable->GES.TimelineElement GES.MetaContainer GES.MetaContainer GES.MetaContainer->GES.TimelineElement 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.Container, GES.TrackElement

Methods

Inherited:

GObject.Object (37), GES.Extractable (3), GES.MetaContainer (40)

Structs:

GObject.ObjectClass (5)

add_child_property (pspec, child)

copy (deep)

edit (layers, new_layer_priority, mode, edge, position)

edit_full (new_layer_priority, mode, edge, position)

get_child_property (property_name)

get_child_property_by_pspec (pspec)

get_duration ()

get_inpoint ()

get_layer_priority ()

get_max_duration ()

get_name ()

get_natural_framerate ()

get_parent ()

get_priority ()

get_start ()

get_timeline ()

get_toplevel_parent ()

get_track_types ()

list_children_properties ()

lookup_child (prop_name)

paste (paste_position)

remove_child_property (pspec)

ripple (start)

ripple_end (end)

roll_end (end)

roll_start (start)

set_child_property (property_name, value)

set_child_property_by_pspec (pspec, value)

set_child_property_full (property_name, value)

set_duration (duration)

set_inpoint (inpoint)

set_max_duration (maxduration)

set_name (name)

set_parent (parent)

set_priority (priority)

set_start (start)

set_timeline (timeline)

trim (start)

Virtual Methods

Inherited:

GObject.Object (7), GES.Extractable (3)

do_deep_copy (copy)

do_get_layer_priority ()

do_get_natural_framerate ()

do_get_track_types ()

do_lookup_child (prop_name)

do_ripple (start)

do_ripple_end (end)

do_roll_end (end)

do_roll_start (start)

do_set_child_property (child, pspec, value)

do_set_child_property_full (child, pspec, value)

do_set_duration (duration)

do_set_inpoint (inpoint)

do_set_max_duration (maxduration)

do_set_parent (parent)

do_set_priority (priority)

do_set_start (start)

do_trim (start)

Properties

Name

Type

Flags

Short Description

duration

int

r/w/en

The play duration

in-point

int

r/w/en

The in-point

max-duration

int

r/w/c/en

The maximum duration of the object

name

str

r/w/c

The name of the timeline object

parent

GES.TimelineElement

r/w

The parent container of the object

priority

int

r/w

The priority of the object deprecated

serialize

bool

r/w

Whether the element should be serialized

start

int

r/w/en

The position in the timeline

timeline

GES.Timeline

r/w/en

The timeline the object is in

Signals

Inherited:

GObject.Object (1), GES.MetaContainer (1)

Name

Short Description

child-property-added

Emitted when the element has a new child property registered.

child-property-removed

Emitted when the element has a child property unregistered.

deep-notify

Emitted when a child of the element has one of its registered properties set.

Fields

Inherited:

GObject.Object (1), GES.MetaContainer (1)

Name

Type

Access

Description

asset

GES.Asset

r

The GES.Asset from which the object has been extracted

duration

int

r

The GES.TimelineElement :duration of the element

inpoint

int

r

The GES.TimelineElement :in-point of the element

maxduration

int

r

The GES.TimelineElement :max-duration of the element

name

str

r

The GES.TimelineElement :name of the element

parent

GES.TimelineElement

r

The GES.TimelineElement :parent of the element

parent_instance

GObject.InitiallyUnowned

r

priority

int

r

The GES.TimelineElement :priority of the element

start

int

r

The GES.TimelineElement :start of the element

timeline

GES.Timeline

r

The GES.TimelineElement :timeline of the element

Class Details

class GES.TimelineElement(**kwargs)
Bases:

GObject.InitiallyUnowned, GES.Extractable, GES.MetaContainer

Abstract:

Yes

Structure:

GES.TimelineElementClass

A GES.TimelineElement will have some temporal extent in its corresponding GES.TimelineElement :timeline, controlled by its GES.TimelineElement :start and GES.TimelineElement :duration. This determines when its content will be displayed, or its effect applied, in the timeline. Several objects may overlap within a given GES.Timeline, in which case their GES.TimelineElement :priority is used to determine their ordering in the timeline. Priority is mostly handled internally by GES.Layer-s and GES.Clip-s.

A timeline element can have a GES.TimelineElement :parent, such as a GES.Clip, which is responsible for controlling its timing.

Editing

Elements can be moved around in their GES.TimelineElement :timeline by setting their GES.TimelineElement :start and GES.TimelineElement :duration using GES.TimelineElement.set_start() and GES.TimelineElement.set_duration(). Additionally, which parts of the underlying content are played in the timeline can be adjusted by setting the GES.TimelineElement :in-point using GES.TimelineElement.set_inpoint(). The library also provides GES.TimelineElement.edit(), with various GES.EditMode-s, which can adjust these properties in a convenient way, as well as introduce similar changes in neighbouring or later elements in the timeline.

However, a timeline may refuse a change in these properties if they would place the timeline in an unsupported configuration. See GES.Timeline for its overlap rules.

Additionally, an edit may be refused if it would place one of the timing properties out of bounds (such as a negative time value for GES.TimelineElement :start, or having insufficient internal content to last for the desired GES.TimelineElement :duration).

Time Coordinates

There are three main sets of time coordinates to consider when using timeline elements:

  • Timeline coordinates: these are the time coordinates used in the output of the timeline in its GES.Track-s. Each track share the same coordinates, so there is only one set of coordinates for the timeline. These extend indefinitely from 0. The times used for editing (including setting GES.TimelineElement :start and GES.TimelineElement :duration) use these coordinates, since these define when an element is present and for how long the element lasts for in the timeline.

  • Internal source coordinates: these are the time coordinates used internally at the element’s output. This is only really defined for GES.TrackElement-s, where it refers to time coordinates used at the final source pad of the wrapped Gst.Element-s. However, these coordinates may also be used in a GES.Clip in reference to its children. In particular, these are the coordinates used for GES.TimelineElement :in-point and GES.TimelineElement :max-duration.

  • Internal sink coordinates: these are the time coordinates used internally at the element’s input. A GES.Source has no input, so these would be undefined. Otherwise, for most GES.TrackElement-s these will be the same set of coordinates as the internal source coordinates because the element does not change the timing internally. Only GES.BaseEffect can support elements where these are different. See GES.BaseEffect for more information.

You can determine the timeline time for a given internal source time in a GES.Track in a GES.Clip using GES.Clip.get_timeline_time_from_internal_time(), and vice versa using GES.Clip.get_internal_time_from_timeline_time(), for the purposes of editing and setting timings properties.

Children Properties

If a timeline element owns another Gst.Object and wishes to expose some of its properties, it can do so by registering the property as one of the timeline element’s children properties using GES.TimelineElement.add_child_property(). The registered property of the child can then be read and set using the GES.TimelineElement.get_child_property() and GES.TimelineElement.set_child_property() methods, respectively. Some sub-classed objects will be created with pre-registered children properties; for example, to expose part of an underlying Gst.Element that is used internally. The registered properties can be listed with GES.TimelineElement.list_children_properties().

add_child_property(pspec, child)[source]
Parameters:
Returns:

True if the property was successfully registered.

Return type:

bool

Register a property of a child of the element to allow it to be written with GES.TimelineElement.set_child_property() and read with GES.TimelineElement.get_child_property(). A change in the property will also appear in the GES.TimelineElement ::deep-notify signal.

pspec should be unique from other children properties that have been registered on self.

copy(deep)[source]
Parameters:

deep (bool) – Whether the copy is needed for pasting

Returns:

The newly create element, copied from self.

Return type:

GES.TimelineElement

Create a copy of self. All the properties of self are copied into a new element, with the exception of GES.TimelineElement :parent, GES.TimelineElement :timeline and GES.TimelineElement :name. Other data, such the list of a GES.Container's children, is **not** copied.

If deep is True, then the new element is prepared so that it can be used in GES.TimelineElement.paste() or GES.Timeline.paste_element(). In the case of copying a GES.Container, this ensures that the children of self will also be pasted. The new element should not be used for anything else and can only be used **once** in a pasting operation. In particular, the new element itself is not an actual ‘deep’ copy of self, but should be thought of as an intermediate object used for a single paste operation.

edit(layers, new_layer_priority, 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.

  • new_layer_priority (int) – The priority/index of the layer self should be moved to. -1 means no move

  • 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) in the timeline coordinates

Returns:

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

Return type:

bool

See GES.TimelineElement.edit_full(), which also gives an error.

Note that the layers argument is currently ignored, so you should just pass None.

New in version 1.18.

edit_full(new_layer_priority, mode, edge, position)[source]
Parameters:
  • new_layer_priority (int) – The priority/index of the layer self should be moved to. -1 means no move

  • 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) in the timeline coordinates

Raises:

GLib.Error

Returns:

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

Return type:

bool

Edits the element within its timeline by adjusting its GES.TimelineElement :start, GES.TimelineElement :duration or GES.TimelineElement :in-point, and potentially doing the same for other elements in the timeline. See GES.EditMode for details about each edit mode. An edit may fail if it would place one of these properties out of bounds, or if it would place the timeline in an unsupported configuration.

Note that if you act on a GES.TrackElement, this will edit its parent GES.Clip instead. Moreover, for any GES.TimelineElement, if you select GES.Edge.NONE for GES.EditMode.EDIT_NORMAL or GES.EditMode.RIPPLE, this will edit the toplevel instead, but still in such a way as to make the GES.TimelineElement :start of self reach the edit position.

Note that if the element’s timeline has a GES.Timeline :snapping-distance set, then the edit position may be snapped to the edge of some element under the edited element.

new_layer_priority can be used to switch self, and other elements moved by the edit, to a new layer. New layers may be be created if the the corresponding layer priority/index does not yet exist for the timeline.

New in version 1.18.

get_child_property(property_name)[source]
Parameters:

property_name (str) – The name of the child property to get

Returns:

True if the property was found and copied to value.

value:

The return location for the value

Return type:

(bool, value: GObject.Value)

Gets the property of a child of the element.

property_name can either be in the format “prop-name” or “TypeName::prop-name”, where “prop-name” is the name of the property to get (as used in g_object_get()), and “TypeName” is the type name of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is useful when two children of different types share the same property name.

The first child found with the given “prop-name” property that was registered with GES.TimelineElement.add_child_property() (and of the type “TypeName”, if it was given) will have the corresponding property copied into value.

Note that ges_timeline_element_get_child_properties() may be more convenient for C programming.

get_child_property_by_pspec(pspec)[source]
Parameters:

pspec (GObject.ParamSpec) – The specification of a registered child property to get

Returns:

The return location for the value

Return type:

value: GObject.Value

Gets the property of a child of the element. Specifically, the property corresponding to the pspec used in GES.TimelineElement.add_child_property() is copied into value.

get_duration()[source]
Returns:

The duration of self (in nanoseconds).

Return type:

int

Gets the GES.TimelineElement :duration for the element.

get_inpoint()[source]
Returns:

The in-point of self (in nanoseconds).

Return type:

int

Gets the GES.TimelineElement :in-point for the element.

get_layer_priority()[source]
Returns:

The priority of the layer self is in, or GES.TIMELINE_ELEMENT_NO_LAYER_PRIORITY if self does not exist in a layer.

Return type:

int

Gets the priority of the layer the element is in. A GES.Group may span several layers, so this would return the highest priority (numerically, the smallest) amongst them.

New in version 1.16.

get_max_duration()[source]
Returns:

The max-duration of self (in nanoseconds).

Return type:

int

Gets the GES.TimelineElement :max-duration for the element.

get_name()[source]
Returns:

The name of self.

Return type:

str or None

Gets the GES.TimelineElement :name for the element.

get_natural_framerate()[source]
Returns:

Whether self has a natural framerate or not, framerate_n and framerate_d will be set to, respectively, 0 and -1 if it is not the case.

framerate_n:

The framerate numerator

framerate_d:

The framerate denominator

Return type:

(bool, framerate_n: int, framerate_d: int)

Get the “natural” framerate of self. This is to say, for example for a GES.VideoUriSource the framerate of the source.

Note that a GES.AudioSource may also have a natural framerate if it derives from the same GES.SourceClip asset as a GES.VideoSource, and its value will be that of the video source. For example, if the uri of a GES.UriClip points to a file that contains both a video and audio stream, then the corresponding GES.AudioUriSource will share the natural framerate of the corresponding GES.VideoUriSource.

New in version 1.18.

get_parent()[source]
Returns:

The parent of self, or None if self has no parent.

Return type:

GES.TimelineElement or None

Gets the GES.TimelineElement :parent for the element.

get_priority()[source]
Returns:

The priority of self.

Return type:

int

Gets the GES.TimelineElement :priority for the element.

get_start()[source]
Returns:

The start of self (in nanoseconds).

Return type:

int

Gets the GES.TimelineElement :start for the element.

get_timeline()[source]
Returns:

The timeline of self, or None if self has no timeline.

Return type:

GES.Timeline or None

Gets the GES.TimelineElement :timeline for the element.

get_toplevel_parent()[source]
Returns:

The toplevel parent of self.

Return type:

GES.TimelineElement

Gets the toplevel GES.TimelineElement :parent of the element.

get_track_types()[source]
Returns:

The track types that self supports.

Return type:

GES.TrackType

Gets the track types that the element can interact with, i.e. the type of GES.Track it can exist in, or will create GES.TrackElement-s for.

New in version 1.6.0.

list_children_properties()[source]
Returns:

An array of GObject.ParamSpec corresponding to the child properties of self, or None if something went wrong.

Return type:

[GObject.ParamSpec]

Get a list of children properties of the element, which is a list of all the specifications passed to GES.TimelineElement.add_child_property().

lookup_child(prop_name)[source]
Parameters:

prop_name (str) – The name of a child property

Returns:

True if a child corresponding to the property was found, in which case child and pspec are set.

child:

The return location for the found child

pspec:

The return location for the specification of the child property

Return type:

(bool, child: GObject.Object, pspec: GObject.ParamSpec)

Looks up a child property of the element.

prop_name can either be in the format “prop-name” or “TypeName::prop-name”, where “prop-name” is the name of the property to look up (as used in g_object_get()), and “TypeName” is the type name of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is useful when two children of different types share the same property name.

The first child found with the given “prop-name” property that was registered with GES.TimelineElement.add_child_property() (and of the type “TypeName”, if it was given) will be passed to child, and the registered specification of this property will be passed to pspec.

paste(paste_position)[source]
Parameters:

paste_position (int) – The position in the timeline element should be pasted to, i.e. the GES.TimelineElement :start value for the pasted element.

Returns:

The newly created element, or None if pasting fails.

Return type:

GES.TimelineElement or None

Paste an element inside the same timeline and layer as self. self **must** be the return of GES.TimelineElement.copy() with deep=TRUE, and it should not be changed before pasting. self is not placed in the timeline, instead a new element is created, alike to the originally copied element. Note that the originally copied element must stay within the same timeline and layer, at both the point of copying and pasting.

Pasting may fail if it would place the timeline in an unsupported configuration.

After calling this function element should not be used. In particular, element can **not** be pasted again. Instead, you can copy the returned element and paste that copy (although, this is only possible if the paste was successful).

See also GES.Timeline.paste_element().

New in version 1.6.0.

remove_child_property(pspec)[source]
Parameters:

pspec (GObject.ParamSpec) – The specification for the property to remove

Returns:

True if the property was successfully un-registered for self.

Return type:

bool

Remove a child property from the element. pspec should be a specification that was passed to GES.TimelineElement.add_child_property(). The corresponding property will no longer be registered as a child property for the element.

ripple(start)[source]
Parameters:

start (int) – The new start time of self in ripple mode

Returns:

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

Return type:

bool

Edits the start time of an element within its timeline in ripple mode. See GES.TimelineElement.edit() with GES.EditMode.RIPPLE and GES.Edge.NONE.

ripple_end(end)[source]
Parameters:

end (int) – The new end time of self in ripple mode

Returns:

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

Return type:

bool

Edits the end time of an element within its timeline in ripple mode. See GES.TimelineElement.edit() with GES.EditMode.RIPPLE and GES.Edge.END.

roll_end(end)[source]
Parameters:

end (int) – The new end time of self in roll mode

Returns:

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

Return type:

bool

Edits the end time of an element within its timeline in roll mode. See GES.TimelineElement.edit() with GES.EditMode.ROLL and GES.Edge.END.

roll_start(start)[source]
Parameters:

start (int) – The new start time of self in roll mode

Returns:

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

Return type:

bool

Edits the start time of an element within its timeline in roll mode. See GES.TimelineElement.edit() with GES.EditMode.ROLL and GES.Edge.START.

set_child_property(property_name, value)[source]
Parameters:
  • property_name (str) – The name of the child property to set

  • value (GObject.Value) – The value to set the property to

Returns:

True if the property was found and set.

Return type:

bool

See GES.TimelineElement.set_child_property_full(), which also gives an error.

Note that ges_timeline_element_set_child_properties() may be more convenient for C programming.

set_child_property_by_pspec(pspec, value)[source]
Parameters:

Sets the property of a child of the element. Specifically, the property corresponding to the pspec used in GES.TimelineElement.add_child_property() is set to value.

set_child_property_full(property_name, value)[source]
Parameters:
  • property_name (str) – The name of the child property to set

  • value (GObject.Value) – The value to set the property to

Raises:

GLib.Error

Returns:

True if the property was found and set.

Return type:

bool

Sets the property of a child of the element.

property_name can either be in the format “prop-name” or “TypeName::prop-name”, where “prop-name” is the name of the property to set (as used in g_object_set()), and “TypeName” is the type name of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is useful when two children of different types share the same property name.

The first child found with the given “prop-name” property that was registered with GES.TimelineElement.add_child_property() (and of the type “TypeName”, if it was given) will have the corresponding property set to value. Other children that may have also matched the property name (and type name) are left unchanged!

New in version 1.18.

set_duration(duration)[source]
Parameters:

duration (int) – The desired duration in its timeline

Returns:

True if duration could be set for self.

Return type:

bool

Sets GES.TimelineElement :duration for the element.

Whilst the element is part of a GES.Timeline, this is the same as editing the element with GES.TimelineElement.edit() under GES.EditMode.EDIT_TRIM with GES.Edge.END. In particular, the GES.TimelineElement :duration of the element may be snapped to a different timeline time difference from the one given. In addition, setting may fail if it would place the timeline in an unsupported configuration, or the element does not have enough internal content to last the desired duration.

set_inpoint(inpoint)[source]
Parameters:

inpoint (int) – The in-point, in internal time coordinates

Returns:

True if inpoint could be set for self.

Return type:

bool

Sets GES.TimelineElement :in-point for the element. If the new in-point is above the current GES.TimelineElement :max-duration of the element, this method will fail.

set_max_duration(maxduration)[source]
Parameters:

maxduration (int) – The maximum duration, in internal time coordinates

Returns:

True if maxduration could be set for self.

Return type:

bool

Sets GES.TimelineElement :max-duration for the element. If the new maximum duration is below the current GES.TimelineElement :in-point of the element, this method will fail.

set_name(name)[source]
Parameters:

name (str or None) – The name self should take

Returns:

True if name or a generated name for self could be set.

Return type:

bool

Sets the GES.TimelineElement :name for the element. If None is given for name, then the library will instead generate a new name based on the type name of the element, such as the name “uriclip3” for a GES.UriClip, and will set that name instead.

If self already has a GES.TimelineElement :timeline, you should not call this function with name set to None.

You should ensure that, within each GES.Timeline, every element has a unique name. If you call this function with name as None, then the library should ensure that the set generated name is unique from previously **generated** names. However, if you choose a name that interferes with the naming conventions of the library, the library will attempt to ensure that the generated names will not conflict with the chosen name, which may lead to a different name being set instead, but the uniqueness between generated and user-chosen names is not guaranteed.

set_parent(parent)[source]
Parameters:

parent (GES.TimelineElement) –

Returns:

True if parent could be set for self.

Return type:

bool

Sets the GES.TimelineElement :parent for the element.

This is used internally and you should normally not call this. A GES.Container will set the GES.TimelineElement :parent of its children in GES.Container.add() and GES.Container.remove().

Note, if parent is not None, self must not already have a parent set. Therefore, if you wish to switch parents, you will need to call this function twice: first to set the parent to None, and then to the new parent.

If parent is not None, you must ensure it already has a (non-floating) reference to self before calling this.

set_priority(priority)[source]
Parameters:

priority (int) – The priority

Returns:

True if priority could be set for self.

Return type:

bool

Sets the priority of the element within the containing layer.

Deprecated since version 1.10: All priority management is done by GES itself now. To set GES.Effect priorities GES.Clip.set_top_effect_index should be used.

set_start(start)[source]
Parameters:

start (int) – The desired start position of the element in its timeline

Returns:

True if start could be set for self.

Return type:

bool

Sets GES.TimelineElement :start for the element. If the element has a parent, this will also move its siblings with the same shift.

Whilst the element is part of a GES.Timeline, this is the same as editing the element with GES.TimelineElement.edit() under GES.EditMode.EDIT_NORMAL with GES.Edge.NONE. In particular, the GES.TimelineElement :start of the element may be snapped to a different timeline time from the one given. In addition, setting may fail if it would place the timeline in an unsupported configuration.

set_timeline(timeline)[source]
Parameters:

timeline (GES.Timeline) –

Returns:

True if timeline could be set for self.

Return type:

bool

Sets the GES.TimelineElement :timeline of the element.

This is used internally and you should normally not call this. A GES.Clip will have its GES.TimelineElement :timeline set through its GES.Layer. A GES.Track will similarly take care of setting the GES.TimelineElement :timeline of its GES.TrackElement-s. A GES.Group will adopt the same GES.TimelineElement :timeline as its children.

If timeline is None, this will stop its current GES.TimelineElement :timeline from tracking it, otherwise timeline will start tracking self. Note, in the latter case, self must not already have a timeline set. Therefore, if you wish to switch timelines, you will need to call this function twice: first to set the timeline to None, and then to the new timeline.

trim(start)[source]
Parameters:

start (int) – The new start time of self in trim mode

Returns:

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

Return type:

bool

Edits the start time of an element within its timeline in trim mode. See GES.TimelineElement.edit() with GES.EditMode.EDIT_TRIM and GES.Edge.START.

do_deep_copy(copy) virtual
Parameters:

copy (GES.TimelineElement) –

Prepare copy for pasting as a copy of self. At least by copying the children properties of self into copy.

do_get_layer_priority() virtual
Returns:

The priority of the layer self is in, or GES.TIMELINE_ELEMENT_NO_LAYER_PRIORITY if self does not exist in a layer.

Return type:

int

Gets the priority of the layer the element is in. A GES.Group may span several layers, so this would return the highest priority (numerically, the smallest) amongst them.

New in version 1.16.

do_get_natural_framerate() virtual
Returns:

Whether self has a natural framerate or not, framerate_n and framerate_d will be set to, respectively, 0 and -1 if it is not the case.

framerate_n:

The framerate numerator

framerate_d:

The framerate denominator

Return type:

(bool, framerate_n: int, framerate_d: int)

Get the “natural” framerate of self. This is to say, for example for a GES.VideoUriSource the framerate of the source.

Note that a GES.AudioSource may also have a natural framerate if it derives from the same GES.SourceClip asset as a GES.VideoSource, and its value will be that of the video source. For example, if the uri of a GES.UriClip points to a file that contains both a video and audio stream, then the corresponding GES.AudioUriSource will share the natural framerate of the corresponding GES.VideoUriSource.

New in version 1.18.

do_get_track_types() virtual
Returns:

The track types that self supports.

Return type:

GES.TrackType

Gets the track types that the element can interact with, i.e. the type of GES.Track it can exist in, or will create GES.TrackElement-s for.

New in version 1.6.0.

do_lookup_child(prop_name) virtual
Parameters:

prop_name (str) – The name of a child property

Returns:

True if a child corresponding to the property was found, in which case child and pspec are set.

child:

The return location for the found child

pspec:

The return location for the specification of the child property

Return type:

(bool, child: GObject.Object, pspec: GObject.ParamSpec)

Looks up a child property of the element.

prop_name can either be in the format “prop-name” or “TypeName::prop-name”, where “prop-name” is the name of the property to look up (as used in g_object_get()), and “TypeName” is the type name of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is useful when two children of different types share the same property name.

The first child found with the given “prop-name” property that was registered with GES.TimelineElement.add_child_property() (and of the type “TypeName”, if it was given) will be passed to child, and the registered specification of this property will be passed to pspec.

do_ripple(start) virtual
Parameters:

start (int) – The new start time of self in ripple mode

Returns:

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

Return type:

bool

Edits the start time of an element within its timeline in ripple mode. See GES.TimelineElement.edit() with GES.EditMode.RIPPLE and GES.Edge.NONE.

do_ripple_end(end) virtual
Parameters:

end (int) – The new end time of self in ripple mode

Returns:

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

Return type:

bool

Edits the end time of an element within its timeline in ripple mode. See GES.TimelineElement.edit() with GES.EditMode.RIPPLE and GES.Edge.END.

do_roll_end(end) virtual
Parameters:

end (int) – The new end time of self in roll mode

Returns:

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

Return type:

bool

Edits the end time of an element within its timeline in roll mode. See GES.TimelineElement.edit() with GES.EditMode.ROLL and GES.Edge.END.

do_roll_start(start) virtual
Parameters:

start (int) – The new start time of self in roll mode

Returns:

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

Return type:

bool

Edits the start time of an element within its timeline in roll mode. See GES.TimelineElement.edit() with GES.EditMode.ROLL and GES.Edge.START.

do_set_child_property(child, pspec, value) virtual
Parameters:

Method for setting the child property given by pspec on child to value. Default implementation will use GObject.Object.set_property().

New in version 1.16.

do_set_child_property_full(child, pspec, value) virtual
Parameters:
Return type:

bool

Similar to set_child_property, except setting can fail, with the error being optionally set. Default implementation will call set_child_property and return True.

New in version 1.18.

do_set_duration(duration) virtual
Parameters:

duration (int) – The desired duration in its timeline

Returns:

True if duration could be set for self.

Return type:

bool

Sets GES.TimelineElement :duration for the element.

Whilst the element is part of a GES.Timeline, this is the same as editing the element with GES.TimelineElement.edit() under GES.EditMode.EDIT_TRIM with GES.Edge.END. In particular, the GES.TimelineElement :duration of the element may be snapped to a different timeline time difference from the one given. In addition, setting may fail if it would place the timeline in an unsupported configuration, or the element does not have enough internal content to last the desired duration.

do_set_inpoint(inpoint) virtual
Parameters:

inpoint (int) – The in-point, in internal time coordinates

Returns:

True if inpoint could be set for self.

Return type:

bool

Sets GES.TimelineElement :in-point for the element. If the new in-point is above the current GES.TimelineElement :max-duration of the element, this method will fail.

do_set_max_duration(maxduration) virtual
Parameters:

maxduration (int) – The maximum duration, in internal time coordinates

Returns:

True if maxduration could be set for self.

Return type:

bool

Sets GES.TimelineElement :max-duration for the element. If the new maximum duration is below the current GES.TimelineElement :in-point of the element, this method will fail.

do_set_parent(parent) virtual
Parameters:

parent (GES.TimelineElement) –

Returns:

True if parent could be set for self.

Return type:

bool

Sets the GES.TimelineElement :parent for the element.

This is used internally and you should normally not call this. A GES.Container will set the GES.TimelineElement :parent of its children in GES.Container.add() and GES.Container.remove().

Note, if parent is not None, self must not already have a parent set. Therefore, if you wish to switch parents, you will need to call this function twice: first to set the parent to None, and then to the new parent.

If parent is not None, you must ensure it already has a (non-floating) reference to self before calling this.

do_set_priority(priority) virtual
Parameters:

priority (int) – The priority

Returns:

True if priority could be set for self.

Return type:

bool

Sets the priority of the element within the containing layer.

Deprecated since version 1.10: All priority management is done by GES itself now. To set GES.Effect priorities GES.Clip.set_top_effect_index should be used.

do_set_start(start) virtual
Parameters:

start (int) – The desired start position of the element in its timeline

Returns:

True if start could be set for self.

Return type:

bool

Sets GES.TimelineElement :start for the element. If the element has a parent, this will also move its siblings with the same shift.

Whilst the element is part of a GES.Timeline, this is the same as editing the element with GES.TimelineElement.edit() under GES.EditMode.EDIT_NORMAL with GES.Edge.NONE. In particular, the GES.TimelineElement :start of the element may be snapped to a different timeline time from the one given. In addition, setting may fail if it would place the timeline in an unsupported configuration.

do_trim(start) virtual
Parameters:

start (int) – The new start time of self in trim mode

Returns:

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

Return type:

bool

Edits the start time of an element within its timeline in trim mode. See GES.TimelineElement.edit() with GES.EditMode.EDIT_TRIM and GES.Edge.START.

Signal Details

GES.TimelineElement.signals.child_property_added(timeline_element, prop_object, prop)
Signal Name:

child-property-added

Flags:

RUN_FIRST

Parameters:

Emitted when the element has a new child property registered. See GES.TimelineElement.add_child_property().

Note that some GES elements will be automatically created with pre-registered children properties. You can use GES.TimelineElement.list_children_properties() to list these.

New in version 1.18.

GES.TimelineElement.signals.child_property_removed(timeline_element, prop_object, prop)
Signal Name:

child-property-removed

Flags:

RUN_FIRST

Parameters:
  • timeline_element (GES.TimelineElement) – The object which received the signal

  • prop_object (GObject.Object) – The child whose property has been unregistered

  • prop (GObject.ParamSpec) – The specification for the property that has been unregistered

Emitted when the element has a child property unregistered. See GES.TimelineElement.remove_child_property().

New in version 1.18.

GES.TimelineElement.signals.deep_notify(timeline_element, prop_object, prop)
Signal Name:

deep-notify

Flags:

RUN_FIRST, NO_RECURSE, DETAILED, NO_HOOKS

Parameters:

Emitted when a child of the element has one of its registered properties set. See GES.TimelineElement.add_child_property(). Note that unlike GObject.Object ::notify, a child property name can not be used as a signal detail.

Property Details

GES.TimelineElement.props.duration
Name:

duration

Type:

int

Default Value:

18446744073709551615

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The duration that the element is in effect for in the timeline (a time difference in nanoseconds using the time coordinates of the timeline). For example, for a source element, this would determine for how long it should output its internal content for. For an operation element, this would determine for how long its effect should be applied to any source content.

GES.TimelineElement.props.in_point
Name:

in-point

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The initial offset to use internally when outputting content (in nanoseconds, but in the time coordinates of the internal content).

For example, for a GES.VideoUriSource that references some media file, the “internal content” is the media file data, and the in-point would correspond to some timestamp in the media file. When playing the timeline, and when the element is first reached at timeline-time GES.TimelineElement :start, it will begin outputting the data from the timestamp in-point **onwards**, until it reaches the end of its GES.TimelineElement :duration in the timeline.

For elements that have no internal content, this should be kept as 0.

GES.TimelineElement.props.max_duration
Name:

max-duration

Type:

int

Default Value:

18446744073709551615

Flags:

READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

The full duration of internal content that is available (a time difference in nanoseconds using the time coordinates of the internal content).

This will act as a cap on the GES.TimelineElement :in-point of the element (which is in the same time coordinates), and will sometimes be used to limit the GES.TimelineElement :duration of the element in the timeline.

For example, for a GES.VideoUriSource that references some media file, this would be the length of the media file.

For elements that have no internal content, or whose content is indefinite, this should be kept as Gst.CLOCK_TIME_NONE.

GES.TimelineElement.props.name
Name:

name

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT

The name of the element. This should be unique within its timeline.

GES.TimelineElement.props.parent
Name:

parent

Type:

GES.TimelineElement

Default Value:

None

Flags:

READABLE, WRITABLE

The parent container of the element.

GES.TimelineElement.props.priority
Name:

priority

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE

The priority of the element.

Deprecated since version 1.10: Priority management is now done by GES itself.

GES.TimelineElement.props.serialize
Name:

serialize

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

Whether the element should be serialized.

GES.TimelineElement.props.start
Name:

start

Type:

int

Default Value:

0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The starting position of the element in the timeline (in nanoseconds and in the time coordinates of the timeline). For example, for a source element, this would determine the time at which it should start outputting its internal content. For an operation element, this would determine the time at which it should start applying its effect to any source content.

GES.TimelineElement.props.timeline
Name:

timeline

Type:

GES.Timeline

Default Value:

None

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The timeline that the element lies within.