GES.Clip¶
- Subclasses:
Methods¶
- Inherited:
GES.Container (6), GES.TimelineElement (38), GObject.Object (37), GES.Extractable (3), GES.MetaContainer (40)
- Structs:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Virtual Methods¶
|
|
|
Properties¶
- Inherited:
Name |
Type |
Flags |
Short Description |
---|---|---|---|
r/en |
A limit on the duration of the clip |
||
r/en |
The |
||
r/w/c |
Formats supported by the clip |
Signals¶
Fields¶
Name |
Type |
Access |
Description |
---|---|---|---|
parent |
r |
Class Details¶
- class GES.Clip(**kwargs)¶
- Bases:
- Abstract:
Yes
- Structure:
GES.Clip
-s are the core objects of aGES.Layer
. Each clip may exist in a single layer but may control severalGES.TrackElement
-s that span severalGES.Track
-s. A clip will ensure that all its children share the sameGES.TimelineElement
:start
andGES.TimelineElement
:duration
in their tracks, which will match theGES.TimelineElement
:start
andGES.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 withGES.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 useGES.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 theGES.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 setGES.TrackElement
:track
after this process. For example, if the timeline does not have a track of the correspondingGES.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 aGES.UriClip
, but you only want it to create a subset of these types, you should set theGES.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’sGES.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 sameGES.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 usingGES.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 theGES.TimelineElement
:in-point
of its core children to be the same value if theirGES.TrackElement
:has-internal-source
is set toTrue
.The
GES.TimelineElement
:max-duration
of the clip is the minimumGES.TimelineElement
:max-duration
of its core children. If you set its value to anything other than its current value, this will also set theGES.TimelineElement
:max-duration
of all its core children to the same value if theirGES.TrackElement
:has-internal-source
is set toTrue
. As a special case, whilst a clip does not yet have any core children, itsGES.TimelineElement
:max-duration
may be set to indicate what its value will be once they are created.- Effects
Some subclasses (
GES.SourceClip
andGES.BaseEffectClip
) may also allow their objects to have additional non-coreGES.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 usingGES.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 usingGES.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 aGES.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 beGES.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 aGES.BaseEffectClip
will refuse time effects, but aGES.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 theGES.TimelineElement
:duration
to shrink such that a clip’sGES.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 finiteGES.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.TrackElement.set_auto_clamp_control_sources
(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 errorif (!ges_timeline_elemnet_edit_full (GES_TIMELINE_ELEMENT (clip), -1,
GES.EditMode.EDIT_TRIM
,GES.Edge.END
, new_end, &error)) // handle errorfor (tmp = children; tmp; tmp = tmp->next)
GES.TrackElement.set_auto_clamp_control_sources
(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 itsGES.Asset
:extractable-type
- Returns:
The newly created element, or
None
if an error occurred.- Return type:
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:
child (
GES.TrackElement
) – A child of selftrack (
GES.Track
) – The track to add child to
- Raises:
- 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:
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 addindex (
int
) – The index to add effect at, or -1 to add at the highest, seeGES.Clip.get_top_effect_index
for more information
- Raises:
- Returns:
True
if effect was successfully added to self at index.- Return type:
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 toTrue
(such asGES.SourceClip
andGES.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
orNone
) – The track to search in, orNone
to search in all trackstype (
GObject.GType
) – The type of track element to search for, orG_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:
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). SeeGES.Clip.find_track_elements
() if you wish to find all such elements.
- find_track_elements(track, track_type, type)[source]¶
- Parameters:
track (
GES.Track
orNone
) – The track to search in, orNone
to search in all trackstrack_type (
GES.TrackType
) – The track-type of the track element to search for, orGES.TrackType.UNKNOWN
to match any track typetype (
GObject.GType
) – The type of track element to search for, orGObject.TYPE_NONE
to match any type
- 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:
Finds the
GES.TrackElement
-s controlled by the clip that match the given criteria. If track is given asNone
and track_type is given asGES.TrackType.UNKNOWN
, then the search will match all elements in any track, including those with no track, and of anyGES.TrackElement
:track-type
. Otherwise, if track is notNone
, but track_type isGES.TrackType.UNKNOWN
, then only the track elements in track are searched for. Otherwise, if track_type is notGES.TrackType.UNKNOWN
, but track isNone
, then only the track elements whoseGES.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’sGES.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:
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:
child (
GES.TrackElement
) – AnGES.TrackElement
:active
child of self with aGES.TrackElement
:track
timeline_time (
int
) – A time in the timeline time coordinates
- Raises:
- 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:
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 theGES.TimelineElement
:in-point
of child to if you set theGES.TimelineElement
:start
of self to timeline_time and wanted to keep the content of child currently found at the currentGES.TimelineElement
:start
of self at the same timeline position. If this would be negative, the conversion fails. This is useful for determining whatGES.TimelineElement
:in-point
would result from aGES.EditMode.EDIT_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
orGES.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_supported_formats()[source]¶
- Returns:
The
GES.TrackType
-s supported by self.- Return type:
Gets the
GES.Clip
:supported-formats
of the clip.
- get_timeline_time_from_internal_time(child, internal_time)[source]¶
- Parameters:
child (
GES.TrackElement
) – AnGES.TrackElement
:active
child of self with aGES.TrackElement
:track
internal_time (
int
) – A time in the internal time coordinates of child
- Raises:
- 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:
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 theGES.TimelineElement
:start
of self to if you set theGES.TimelineElement
:in-point
of child to internal_time and wanted to keep the content of child currently found at the currentGES.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 aGES.EditMode.EDIT_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
() forGES.EditMode.EDIT_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 theGES.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, orGES.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:
- 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:
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:
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:
- get_top_effects()[source]¶
- Returns:
A list of all
GES.BaseEffect
-s that have been added to self.- Return type:
Gets the
GES.BaseEffect
-s that have been added to the clip. The returned list is ordered by their internal index in the clip. SeeGES.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:
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:
- Returns:
True
if self was successfully moved to layer.- Return type:
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:
- Returns:
True
if effect was successfully added to self at index.- Return type:
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
) – TheGES.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 movenewindex (
int
) – The index for effect in self
- Returns:
True
if effect was successfully moved to newindex.- Return type:
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 movenewindex (
int
) – The index for effect in self
- Raises:
- Returns:
True
if effect was successfully moved to newindex.- Return type:
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:
effect (
GES.BaseEffect
) –newpriority (
int
) –
- Return type:
- 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:
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:
- Returns:
The newly created clip resulting from the splitting self, or
None
if self can’t be split.- Return type:
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, whoseGES.TimelineElement
:start
matches the split position andGES.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 additionalGES.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 subGES.Project
, which only contains this clip (and its effects), and in the original layer create two neighbouringGES.UriClip
-s that reference this sub-project, but at a differentGES.TimelineElement
:in-point
.New in version 1.18.
- do_create_track_element(type) virtual¶
- Parameters:
type (
GES.TrackType
) – AGES.TrackType
to create aGES.TrackElement
for- Returns:
The
GES.TrackElement
created by clip, orNone
if clip can not provide a track element for the given type or an error occurred.- Return type:
Method to create the core
GES.TrackElement
of a clip of this class. If a clip of this class may create several track elements per track type, this should be left asNone
, and GESClipClass::create_track_elements should be used instead. Otherwise, you should implement this class method and leave GESClipClass::create_track_elements as the default implementation
- do_create_track_elements(type) virtual¶
- Parameters:
type (
GES.TrackType
) – AGES.TrackType
to createGES.TrackElement
-s for- Returns:
A list of the
GES.TrackElement
-s created by clip for the given type, orNone
if no track elements are created or an error occurred.- Return type:
Method to create the (multiple) core
GES.TrackElement
-s of a clip of this class. If GESClipClass::create_track_element is implemented, this should be kept as the default implementation
Property Details¶
- GES.Clip.props.duration_limit¶
- Name:
duration-limit
- Type:
- Default Value:
18446744073709551615
- Flags:
The maximum
GES.TimelineElement
:duration
that can be *currently* set for the clip, taking into account theGES.TimelineElement
:in-point
,GES.TimelineElement
:max-duration
,GES.TrackElement
:active
, andGES.TrackElement
:track
properties of its children, as well as any time effects. If there is no limit, this will be set toGst.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, itsGES.TimelineElement
:duration
will be set to the new limit.New in version 1.18.
- GES.Clip.props.layer¶
- Name:
layer
- Type:
- Default Value:
- Flags:
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:
- Default Value:
- Flags:
The
GES.TrackType
-s that the clip supports, which it can createGES.TrackElement
-s for. Note that this can be a combination ofGES.TrackType
flags to indicate support for severalGES.TrackElement
:track-type
elements.