Timeline
Object Hierarchy:
Description:
public class Timeline : Bin, Extractable, MetaContainer, ChildProxy
Timeline is the central object for any multimedia timeline.
A timeline is composed of a set of Track-s and a set of Layer-s, which are added to the timeline using add_track and append_layer, respectively.
The contained tracks define the supported types of the timeline and provide the media output. Essentially, each track provides an additional source Pad.
Most usage of a timeline will likely only need a single AudioTrack and/or a single VideoTrack. You can create such a timeline with Timeline.audio_video. After this, you are unlikely to need to work with the tracks directly.
A timeline's layers contain Clip-s, which in turn control the creation of TrackElement-s, which are added to the timeline's tracks. See select_tracks_for_object if you wish to have more control over which track a clip's elements are added to.
The layers are ordered, with higher priority layers having their content prioritised in the tracks. This ordering can be changed using move_layer.
Editing
See TimelineElement for the various ways the elements of a timeline can be edited.
If you change the timing or ordering of a timeline's TimelineElement-s, then these changes will not actually be taken into account in the output of the timeline's tracks until the commit method is called. This allows you to move its elements around, say, in response to an end user's mouse dragging, with little expense before finalising their effect on the produced data.
Overlaps and Auto-Transitions
There are certain restrictions placed on how Source-s may overlap in a Track that belongs to a timeline. These will be enforced by GES, so the user will not need to keep track of them, but they should be aware that certain edits will be refused as a result if the overlap rules would be broken.
Consider two Source-s, `A` and `B`, with start times `startA` and `startB`, and end times `endA` and `endB`, respectively. The start time refers to their start, and the end time is their start + duration. These two sources *overlap* if:
+ they share the same track (non
null), which belongs to the timeline; + they share the same GES_TIMELINE_ELEMENT_LAYER_PRIORITY;
and + `startA < endB` and `startB < endA `.
Note that when `startA = endB` or `startB = endA` then the two sources will *touch* at their edges, but are not considered overlapping.
If, in addition, `startA < startB < endA`, then we can say that the end of `A` overlaps the start of `B`.
If, instead, `startA <= startB` and `endA >= endB`, then we can say that `A` fully overlaps `B`.
The overlap rules for a timeline are that:
- One source cannot fully overlap another source.
- A source can only overlap the end of up to one other source at its start.
- A source can only overlap the start of up to one other source at its end.
The last two rules combined essentially mean that at any given timeline position, only up to two Source-s may overlap at that position. So triple or more overlaps are not allowed.
If you switch on auto_transition, then at any moment when the end of one source (the first source) overlaps the start of another (the second source), a TransitionClip will be automatically created for the pair in the same layer and it will cover their overlap. If the two elements are edited in a way such that the end of the first source no longer overlaps the start of the second, the transition will be automatically removed from the timeline. However, if the two sources still overlap at the same edges after the edit, then the same transition object will be kept, but with its timing and layer adjusted accordingly.
NOTE: if you know what you are doing and want to be in full control of the timeline layout, you can disable the edit APIs with disable_edit_apis.
Saving
To save/load a timeline, you can use the load_from_uri and save_to_uri methods that use the default format.
Playing
A timeline is a Bin with a source Pad for each of its tracks, which you can fetch with get_pad_for_track. You will likely want to link these to some compatible sink Element-s to be able to play or capture the content of the timeline.
You can use a Pipeline to easily preview/play the timeline's content, or render it to a file.