GES.Clip

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

Methods

Inherited:GES.Container (6), GES.TimelineElement (38), GObject.Object (37), GES.Extractable (3), GES.MetaContainer (40)
Structs:GObject.ObjectClass (5)
  add_asset (asset)
  add_child_to_track (child, track)
  add_top_effect (effect, index)
  find_track_element (track, type)
  find_track_elements (track, track_type, type)
  get_duration_limit ()
  get_internal_time_from_timeline_time (child, timeline_time)
  get_layer ()
  get_supported_formats ()
  get_timeline_time_from_internal_time (child, internal_time)
  get_timeline_time_from_source_frame (frame_number)
  get_top_effect_index (effect)
  get_top_effect_position (effect)
  get_top_effects ()
  move_to_layer (layer)
  move_to_layer_full (layer)
  remove_top_effect (effect)
  set_supported_formats (supportedformats)
  set_top_effect_index (effect, newindex)
  set_top_effect_index_full (effect, newindex)
  set_top_effect_priority (effect, newpriority)
  split (position)
  split_full (position)

Properties

Inherited:GES.Container (1), GES.TimelineElement (9)
Name Type Flags Short Description
duration-limit int r/en A limit on the duration of the clip
layer GES.Layer r/en The GES.Layer where this clip is being used.
supported-formats GES.TrackType r/w/c Formats supported by the clip

Fields

Inherited:GES.Container (2), GES.TimelineElement (3), GObject.Object (1), GES.MetaContainer (1)
Name Type Access Description
parent GES.Container r  

Class Details

class GES.Clip(**kwargs)
Bases:GES.Container
Abstract:Yes
Structure:GES.ClipClass

GES.Clip-s are the core objects of a GES.Layer. Each clip may exist in a single layer but may control several GES.TrackElement-s that span several GES.Track-s. A clip will ensure that all its children share the same GES.TimelineElement :start and GES.TimelineElement :duration in their tracks, which will match the GES.TimelineElement :start and GES.TimelineElement :duration of the clip itself. Therefore, changing the timing of the clip will change the timing of the children, and a change in the timing of a child will change the timing of the clip and subsequently all its siblings. As such, a clip can be treated as a singular object in its layer.

For most uses of a GES.Timeline, it is often sufficient to only interact with GES.Clip-s directly, which will take care of creating and organising the elements of the timeline’s tracks.

Core Children

In more detail, clips will usually have some *core* GES.TrackElement children, which are created by the clip when it is added to a layer in a timeline. The type and form of these core children will depend on the clip’s subclass. You can use GES.TrackElement.is_core() to determine whether a track element is considered such a core track element. Note, if a core track element is part of a clip, it will always be treated as a core *child* of the clip. You can connect to the GES.Container ::child-added signal to be notified of their creation.

When a child is added to a clip, the timeline will select its tracks using GES.Timeline ::select-tracks-for-object. Note that it may be the case that the child will still have no set GES.TrackElement :track after this process. For example, if the timeline does not have a track of the corresponding GES.Track :track-type. A clip can safely contain such children, which may have their track set later, although they will play no functioning role in the timeline in the meantime.

If a clip may create track elements with various GES.TrackElement :track-type(s), such as a GES.UriClip, but you only want it to create a subset of these types, you should set the GES.Clip :supported-formats of the clip to the subset of types. This should be done *before* adding the clip to a layer.

If a clip will produce several core elements of the same GES.TrackElement :track-type, you should connect to the timeline’s GES.Timeline ::select-tracks-for-object signal to coordinate which tracks each element should land in. Note, no two core children within a clip can share the same GES.Track, so you should not select the same track for two separate core children. Provided you stick to this rule, it is still safe to select several tracks for the same core child, the core child will be copied into the additional tracks. You can manually add the child to more tracks later using GES.Clip.add_child_to_track(). If you do not wish to use a core child, you can always select no track.

The GES.TimelineElement :in-point of the clip will control the GES.TimelineElement :in-point of its core children to be the same value if their GES.TrackElement :has-internal-source is set to True.

The GES.TimelineElement :max-duration of the clip is the minimum GES.TimelineElement :max-duration of its core children. If you set its value to anything other than its current value, this will also set the GES.TimelineElement :max-duration of all its core children to the same value if their GES.TrackElement :has-internal-source is set to True. As a special case, whilst a clip does not yet have any core children, its GES.TimelineElement :max-duration may be set to indicate what its value will be once they are created.

Effects

Some subclasses (GES.SourceClip and GES.BaseEffectClip) may also allow their objects to have additional non-core GES.BaseEffect-s elements as children. These are additional effects that are applied to the output data of the core elements. They can be added to the clip using GES.Clip.add_top_effect(), which will take care of adding the effect to the timeline’s tracks. The new effect will be placed between the clip’s core track elements and its other effects. As such, the newly added effect will be applied to any source data **before** the other existing effects. You can change the ordering of effects using GES.Clip.set_top_effect_index().

Tracks are selected for top effects in the same way as core children. If you add a top effect to a clip before it is part of a timeline, and later add the clip to a timeline, the track selection for the top effects will occur just after the track selection for the core children. If you add a top effect to a clip that is already part of a timeline, the track selection will occur immediately. Since a top effect must be applied on top of a core child, if you use GES.Timeline ::select-tracks-for-object, you should ensure that the added effects are destined for a GES.Track that already contains a core child.

In addition, if the core child in the track is not GES.TrackElement :active, then neither can any of its effects be GES.TrackElement :active. Therefore, if a core child is made in-active, all of the additional effects in the same track will also become in-active. Similarly, if an effect is set to be active, then the core child will also become active, but other effects will be left alone. Finally, if an active effect is added to the track of an in-active core child, it will become in-active as well. Note, in contrast, setting a core child to be active, or an effect to be in-active will *not* change the other children in the same track.

### Time Effects

Some effects also change the timing of their data (see GES.BaseEffect for what counts as a time effect). Note that a GES.BaseEffectClip will refuse time effects, but a GES.Source will allow them.

When added to a clip, time effects may adjust the timing of other children in the same track. Similarly, when changing the order of effects, making them (in)-active, setting their time property values or removing time effects. These can cause the GES.Clip :duration-limit to change in value. However, if such an operation would ever cause the GES.TimelineElement :duration to shrink such that a clip’s GES.Source is totally overlapped in the timeline, the operation would be prevented. Note that the same can happen when adding non-time effects with a finite GES.TimelineElement :max-duration.

Therefore, when working with time effects, you should – more so than usual – not assume that setting the properties of the clip’s children will succeed. In particular, you should use GES.TimelineElement.set_child_property_full() when setting the time properties.

If you wish to preserve the *internal* duration of a source in a clip during these time effect operations, you can do something like the following.

```c void do_time_effect_change (GES.Clip * clip) { GLib.List *tmp, *children; GES.TrackElement *source; GstClockTime source_outpoint; GstClockTime new_end; GLib.Error *error = None;

// choose some active source in a track to preserve the internal // duration of source = ges_clip_get_track_element (clip, None, GES_TYPE_SOURCE);

// note its current internal end time source_outpoint = GES.Clip.get_internal_time_from_timeline_time ( clip, source, GES_TIMELINE_ELEMENT_END (clip), None);

// handle invalid out-point

// stop the children’s control sources from clamping when their // out-point changes with a change in the time effects children = GES.Container.get_children (GES_CONTAINER (clip), False);

for (tmp = children; tmp; tmp = tmp->next) ges_track_element_set_auto_clamp_control_source (tmp->data, False);

// add time effect, or set their children properties, or move them around … // user can make sure that if a time effect changes one source, we should // also change the time effect for another source. E.g. if // “GstVideorate::rate” is set to 2.0, we also set “GstPitch::rate” to // 2.0

// Note the duration of the clip may have already changed if the // duration-limit of the clip dropped below its current value

new_end = GES.Clip.get_timeline_time_from_internal_time ( clip, source, source_outpoint, &error); // handle error

if (!ges_timeline_elemnet_edit_full (GES_TIMELINE_ELEMENT (clip), -1, GES.EditMode.TRIM, GES.Edge.END, new_end, &error)) // handle error

for (tmp = children; tmp; tmp = tmp->next) ges_track_element_set_auto_clamp_control_source (tmp->data, True);

g_list_free_full (children, Gst.Object.unref); Gst.Object.unref (source); } ```

add_asset(asset)[source]
Parameters:asset (GES.Asset) – An asset with #GES_TYPE_TRACK_ELEMENT as its GES.Asset :extractable-type
Returns:The newly created element, or None if an error occurred.
Return type:GES.TrackElement or None

Extracts a GES.TrackElement from an asset and adds it to the clip. This can be used to add effects that derive from the asset to the clip, but this method is not intended to be used to create the core elements of the clip.

add_child_to_track(child, track)[source]
Parameters:
Raises:

GLib.Error

Returns:

The element that was added to track, either child or a copy of child, or None if the element could not be added.

Return type:

GES.TrackElement

Adds the track element child of the clip to a specific track.

If the given child is already in another track, this will create a copy of the child, add it to the clip, and add this copy to the track.

You should only call this whilst a clip is part of a GES.Timeline, and for tracks that are in the same timeline.

This method is an alternative to using the GES.Timeline ::select-tracks-for-object signal, but can be used to complement it when, say, you wish to copy a clip’s children from one track into a new one.

When the child is a core child, it must be added to a track that does not already contain another core child of the same clip. If it is not a core child (an additional effect), then it must be added to a track that already contains one of the core children of the same clip.

This method can also fail if the adding the track element to the track would break a configuration rule of the corresponding GES.Timeline, such as causing three sources to overlap at a single time, or causing a source to completely overlap another in the same track.

New in version 1.18.

add_top_effect(effect, index)[source]
Parameters:
  • effect (GES.BaseEffect) – A top effect to add
  • index (int) – The index to add effect at, or -1 to add at the highest
Raises:

GLib.Error

Returns:

True if effect was successfully added to self at index.

Return type:

bool

Add a top effect to a clip at the given index.

Unlike using GES.Container.add(), this allows you to set the index in advance. It will also check that no error occurred during the track selection for the effect.

Note, only subclasses of GES.ClipClass that have #GES_CLIP_CLASS_CAN_ADD_EFFECTS set to True (such as GES.SourceClip and GES.BaseEffectClip) can have additional top effects added.

Note, if the effect is a time effect, this may be refused if the clip would not be able to adapt itself once the effect is added.

New in version 1.18.

find_track_element(track, type)[source]
Parameters:
  • track (GES.Track or None) – The track to search in, or None to search in all tracks
  • type (GObject.GType) – The type of track element to search for, or G_TYPE_NONE to match any type
Returns:

The element controlled by self, in track, and of the given type, or None if no such element could be found.

Return type:

GES.TrackElement or None

Finds an element controlled by the clip. If track is given, then only the track elements in track are searched for. If type is given, then this function searches for a track element of the given type.

Note, if multiple track elements in the clip match the given criteria, this will return the element amongst them with the highest GES.TimelineElement :priority (numerically, the smallest). See GES.Clip.find_track_elements() if you wish to find all such elements.

find_track_elements(track, track_type, type)[source]
Parameters:
Returns:

A list of all the GES.TrackElement-s controlled by self, in track or of the given track_type, and of the given type.

Return type:

[GES.TrackElement]

Finds the GES.TrackElement-s controlled by the clip that match the given criteria. If track is given as None and track_type is given as GES.TrackType.UNKNOWN, then the search will match all elements in any track, including those with no track, and of any GES.TrackElement :track-type. Otherwise, if track is not None, but track_type is GES.TrackType.UNKNOWN, then only the track elements in track are searched for. Otherwise, if track_type is not GES.TrackType.UNKNOWN, but track is None, then only the track elements whose GES.TrackElement :track-type matches track_type are searched for. Otherwise, when both are given, the track elements that match **either** criteria are searched for. Therefore, if you wish to only find elements in a specific track, you should give the track as track, but you should not give the track’s GES.Track :track-type as track_type because this would also select elements from other tracks of the same type.

You may also give type to _further_ restrict the search to track elements of the given type.

get_duration_limit()[source]
Returns:The duration-limit of self.
Return type:int

Gets the GES.Clip :duration-limit of the clip.

New in version 1.18.

get_internal_time_from_timeline_time(child, timeline_time)[source]
Parameters:
Raises:

GLib.Error

Returns:

The time in the internal coordinates of child corresponding to timeline_time, or Gst.CLOCK_TIME_NONE if the conversion could not be performed.

Return type:

int

Convert the timeline time to an internal source time of the child. This will take any time effects placed on the clip into account (see GES.BaseEffect for what time effects are supported, and how to declare them in GES).

When timeline_time is above the GES.TimelineElement :start of self, this will return the internal time at which the content that appears at timeline_time in the output of the timeline is created in child. For example, if timeline_time corresponds to the current seek position, this would let you know which part of a media file is being read.

This will be done assuming the clip has an indefinite end, so the internal time may be beyond the current out-point of the child, or even its GES.TimelineElement :max-duration.

If, instead, timeline_time is below the current GES.TimelineElement :start of self, this will return what you would need to set the GES.TimelineElement :in-point of child to if you set the GES.TimelineElement :start of self to timeline_time and wanted to keep the content of child currently found at the current GES.TimelineElement :start of self at the same timeline position. If this would be negative, the conversion fails. This is useful for determining what GES.TimelineElement :in-point would result from a GES.EditMode.TRIM to timeline_time.

Note that whilst a clip has no time effects, this second return is equivalent to finding the internal time at which the content that appears at timeline_time in the timeline can be found in child if it had indefinite extent in both directions. However, with non-linear time effects this second return will be more distinct.

In either case, the returned time would be appropriate to use for the GES.TimelineElement :in-point or GES.TimelineElement :max-duration of the child.

See GES.Clip.get_timeline_time_from_internal_time(), which performs the reverse.

New in version 1.18.

get_layer()[source]
Returns:The layer self is in, or None if self is not in any layer.
Return type:GES.Layer or None

Gets the GES.Clip :layer of the clip.

get_supported_formats()[source]
Returns:The GES.TrackType-s supported by self.
Return type:GES.TrackType

Gets the GES.Clip :supported-formats of the clip.

get_timeline_time_from_internal_time(child, internal_time)[source]
Parameters:
Raises:

GLib.Error

Returns:

The time in the timeline coordinates corresponding to internal_time, or Gst.CLOCK_TIME_NONE if the conversion could not be performed.

Return type:

int

Convert the internal source time from the child to a timeline time. This will take any time effects placed on the clip into account (see GES.BaseEffect for what time effects are supported, and how to declare them in GES).

When internal_time is above the GES.TimelineElement :in-point of child, this will return the timeline time at which the internal content found at internal_time appears in the output of the timeline’s track. For example, this would let you know where in the timeline a particular scene in a media file would appear.

This will be done assuming the clip has an indefinite end, so the timeline time may be beyond the end of the clip, or even breaking its GES.Clip :duration-limit.

If, instead, internal_time is below the current GES.TimelineElement :in-point of child, this will return what you would need to set the GES.TimelineElement :start of self to if you set the GES.TimelineElement :in-point of child to internal_time and wanted to keep the content of child currently found at the current GES.TimelineElement :start of self at the same timeline position. If this would be negative, the conversion fails. This is useful for determining what position to use in a GES.EditMode.TRIM if you wish to trim to a specific point in the internal content, such as a particular scene in a media file.

Note that whilst a clip has no time effects, this second return is equivalent to finding the timeline time at which the content of child at internal_time would be found in the timeline if it had indefinite extent in both directions. However, with non-linear time effects this second return will be more distinct.

In either case, the returned time would be appropriate to use in GES.TimelineElement.edit() for GES.EditMode.TRIM, and similar, if you wish to use a particular internal point as a reference. For example, you could choose to end a clip at a certain internal ‘out-point’, similar to the GES.TimelineElement :in-point, by translating the desired end time into the timeline coordinates, and using this position to trim the end of a clip.

See GES.Clip.get_internal_time_from_timeline_time(), which performs the reverse, or GES.Clip.get_timeline_time_from_source_frame() which does the same conversion, but using frame numbers.

New in version 1.18.

get_timeline_time_from_source_frame(frame_number)[source]
Parameters:frame_number (int) – The frame number to get the corresponding timestamp of in the timeline coordinates
Raises:GLib.Error
Returns:The timestamp corresponding to frame_number in the core children of self, in the timeline coordinates, or Gst.CLOCK_TIME_NONE if the conversion could not be performed.
Return type:int

Convert the source frame number to a timeline time. This acts the same as GES.Clip.get_timeline_time_from_internal_time() using the core children of the clip and using the frame number to specify the internal position, rather than a timestamp.

The returned timeline time can be used to seek or edit to a specific frame.

Note that you can get the frame timestamp of a particular clip asset with GES.ClipAsset.get_frame_time().

New in version 1.18.

get_top_effect_index(effect)[source]
Parameters:effect (GES.BaseEffect) – The effect we want to get the index of
Returns:The index of effect in self, or -1 if something went wrong.
Return type:int

Gets the internal index of an effect in the clip. The index of effects in a clip will run from 0 to n-1, where n is the total number of effects. If two effects share the same GES.TrackElement :track, the effect with the numerically lower index will be applied to the source data **after** the other effect, i.e. output data will always flow from a higher index effect to a lower index effect.

get_top_effect_position(effect)[source]
Parameters:effect (GES.BaseEffect) –
Return type:int
get_top_effects()[source]
Returns:A list of all GES.BaseEffect-s that have been added to self.
Return type:[GES.TrackElement]

Gets the GES.BaseEffect-s that have been added to the clip. The returned list is ordered by their internal index in the clip. See GES.Clip.get_top_effect_index().

move_to_layer(layer)[source]
Parameters:layer (GES.Layer) – The new layer
Returns:True if self was successfully moved to layer.
Return type:bool

See GES.Clip.move_to_layer_full(), which also gives an error.

move_to_layer_full(layer)[source]
Parameters:layer (GES.Layer) – The new layer
Raises:GLib.Error
Returns:True if self was successfully moved to layer.
Return type:bool

Moves a clip to a new layer. If the clip already exists in a layer, it is first removed from its current layer before being added to the new layer.

New in version 1.18.

remove_top_effect(effect)[source]
Parameters:effect (GES.BaseEffect) – The top effect to remove
Raises:GLib.Error
Returns:True if effect was successfully added to self at index.
Return type:bool

Remove a top effect from the clip.

Note, if the effect is a time effect, this may be refused if the clip would not be able to adapt itself once the effect is removed.

New in version 1.18.

set_supported_formats(supportedformats)[source]
Parameters:supportedformats (GES.TrackType) – The GES.TrackType-s supported by self

Sets the GES.Clip :supported-formats of the clip. This should normally only be called by subclasses, which should be responsible for updating its value, rather than the user.

set_top_effect_index(effect, newindex)[source]
Parameters:
  • effect (GES.BaseEffect) – An effect within self to move
  • newindex (int) – The index for effect in self
Returns:

True if effect was successfully moved to newindex.

Return type:

bool

See GES.Clip.set_top_effect_index_full(), which also gives an error.

set_top_effect_index_full(effect, newindex)[source]
Parameters:
  • effect (GES.BaseEffect) – An effect within self to move
  • newindex (int) – The index for effect in self
Raises:

GLib.Error

Returns:

True if effect was successfully moved to newindex.

Return type:

bool

Set the index of an effect within the clip. See GES.Clip.get_top_effect_index(). The new index must be an existing index of the clip. The effect is moved to the new index, and the other effects may be shifted in index accordingly to otherwise maintain the ordering.

New in version 1.18.

set_top_effect_priority(effect, newpriority)[source]
Parameters:
Return type:

bool

split(position)[source]
Parameters:position (int) – The timeline position at which to perform the split
Returns:The newly created clip resulting from the splitting self, or None if self can’t be split.
Return type:GES.Clip or None

See GES.Clip.split_full(), which also gives an error.

split_full(position)[source]
Parameters:position (int) – The timeline position at which to perform the split, between the start and end of the clip
Raises:GLib.Error
Returns:The newly created clip resulting from the splitting self, or None if self can’t be split.
Return type:GES.Clip or None

Splits a clip at the given timeline position into two clips. The clip must already have a GES.Clip :layer.

The original clip’s GES.TimelineElement :duration is reduced such that its end point matches the split position. Then a new clip is created in the same layer, whose GES.TimelineElement :start matches the split position and GES.TimelineElement :duration will be set such that its end point matches the old end point of the original clip. Thus, the two clips together will occupy the same positions in the timeline as the original clip did.

The children of the new clip will be new copies of the original clip’s children, so it will share the same sources and use the same operations.

The new clip will also have its GES.TimelineElement :in-point set so that any internal data will appear in the timeline at the same time. Thus, when the timeline is played, the playback of data should appear the same. This may be complicated by any additional GES.Effect-s that have been placed on the original clip that depend on the playback time or change the data consumption rate of sources. This method will attempt to translate these effects such that the playback appears the same. In such complex situations, you may get a better result if you place the clip in a separate sub GES.Project, which only contains this clip (and its effects), and in the original layer create two neighbouring GES.UriClip-s that reference this sub-project, but at a different GES.TimelineElement :in-point.

New in version 1.18.

do_create_track_element(type) virtual
Parameters:type (GES.TrackType) – A GES.TrackType to create a GES.TrackElement for
Returns:The GES.TrackElement created by clip, or None if clip can not provide a track element for the given type or an error occurred.
Return type:GES.TrackElement or None
do_create_track_elements(type) virtual
Parameters:type (GES.TrackType) – A GES.TrackType to create GES.TrackElement-s for
Returns:A list of the GES.TrackElement-s created by clip for the given type, or None if no track elements are created or an error occurred.
Return type:[GES.TrackElement]

Property Details

GES.Clip.props.duration_limit
Name:duration-limit
Type:int
Default Value:18446744073709551615
Flags:READABLE, EXPLICIT_NOTIFY

The maximum GES.TimelineElement :duration that can be *currently* set for the clip, taking into account the GES.TimelineElement :in-point, GES.TimelineElement :max-duration, GES.TrackElement :active, and GES.TrackElement :track properties of its children, as well as any time effects. If there is no limit, this will be set to Gst.CLOCK_TIME_NONE.

Note that whilst a clip has no children in any tracks, the limit will be unknown, and similarly set to Gst.CLOCK_TIME_NONE.

If the duration-limit would ever go below the current GES.TimelineElement :duration of the clip due to a change in the above variables, its GES.TimelineElement :duration will be set to the new limit.

New in version 1.18.

GES.Clip.props.layer
Name:layer
Type:GES.Layer
Default Value:None
Flags:READABLE, EXPLICIT_NOTIFY

The layer this clip lies in.

If you want to connect to this property’s GObject.Object ::notify signal, you should connect to it with g_signal_connect_after() since the signal emission may be stopped internally.

GES.Clip.props.supported_formats
Name:supported-formats
Type:GES.TrackType
Default Value:GES.TrackType.AUDIO | GES.TrackType.VIDEO
Flags:READABLE, WRITABLE, CONSTRUCT

The GES.TrackType-s that the clip supports, which it can create GES.TrackElement-s for. Note that this can be a combination of GES.TrackType flags to indicate support for several GES.TrackElement :track-type elements.