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.
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.