Struct gstreamer_editing_services::Timeline

#[repr(transparent)]
pub struct Timeline { /* private fields */ }

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 TimelineExt::add_track() and TimelineExt::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 gst::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 new_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 TimelineExt::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 TimelineExt::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 None), 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:

1. One source cannot fully overlap another source.
2. A source can only overlap the end of up to one other source at its start.
3. 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 ges_timeline_disable_edit_apis.

Saving

To save/load a timeline, you can use the TimelineExt::load_from_uri() and TimelineExt::save_to_uri() methods that use the default format.

Playing

A timeline is a gst::Bin with a source gst::Pad for each of its tracks, which you can fetch with TimelineExt::pad_for_track(). You will likely want to link these to some compatible sink gst::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.

Properties

auto-transition

Whether to automatically create a transition whenever two Source-s overlap in a track of the timeline. See auto-transition if you want this to only happen in some layers.

Readable | Writeable

duration

The current duration (in nanoseconds) of the timeline. A timeline ‘starts’ at time 0, so this is the maximum end time of all of its TimelineElement-s.

Readable

snapping-distance

The distance (in nanoseconds) at which a TimelineElement being moved within the timeline should snap one of its Source-s with another Source-s edge. See EditMode for which edges can snap during an edit. 0 means no snapping.

Readable | Writeable

Bin

async-handling

If set to true, the bin will handle asynchronous state changes. This should be used only if the bin subclass is modifying the state of its children on its own.

Readable | Writeable

message-forward

Forward all children messages, even those that would normally be filtered by the bin. This can be interesting when one wants to be notified of the EOS state of individual elements, for example.

The messages are converted to an ELEMENT message with the bin as the source. The structure of the message is named GstBinForwarded and contains a field named message that contains the original forwarded GstMessage.

Readable | Writeable

Object

name

Readable | Writeable | Construct

parent

The parent of the object. Please note, that when changing the ‘parent’ property, we don’t emit notify and deep-notify signals due to locking issues. In some cases one can use element-added or element-removed signals on the parent to achieve a similar effect.

Readable | Writeable

Signals

commited

This signal will be emitted once the changes initiated by TimelineExt::commit() have been executed in the backend. Use TimelineExt::commit_sync() if you do not want to have to connect to this signal.

group-added

Will be emitted after the group is added to to the timeline. This can happen when grouping with ges_container_group, or by adding containers to a newly created group.

Note that this should not be emitted whilst a timeline is being loaded from its Project asset. You should connect to the project’s loaded signal if you want to know which groups were created for the timeline.

group-removed

Will be emitted after the group is removed from the timeline through ges_container_ungroup. Note that group will no longer contain its former children, these are held in children.

Note that if a group is emptied, then it will no longer belong to the timeline, but this signal will not be emitted in such a case.

layer-added

Will be emitted after the layer is added to the timeline.

Note that this should not be emitted whilst a timeline is being loaded from its Project asset. You should connect to the project’s loaded signal if you want to know which layers were created for the timeline.

layer-removed

Will be emitted after the layer is removed from the timeline.

select-element-track

Simplified version of select-tracks-for-object which only allows track_element to be added to a single Track.

select-tracks-for-object

This will be emitted whenever the timeline needs to determine which tracks a clip’s children should be added to. The track element will be added to each of the tracks given in the return. If a track element is selected to go into multiple tracks, it will be copied into the additional tracks, under the same clip. Note that the copy will not keep its properties or state in sync with the original.

Connect to this signal once if you wish to control which element should be added to which track. Doing so will overwrite the default behaviour, which adds track_element to all tracks whose track-type includes the track_element’s track-type.

Note that under the default track selection, if a clip would produce multiple core children of the same TrackType, it will choose one of the core children arbitrarily to place in the corresponding tracks, with a warning for the other core children that are not placed in the track. For example, this would happen for a UriClip that points to a file that contains multiple audio streams. If you wish to choose the stream, you could connect to this signal, and use, say, UriSourceAssetExt::stream_info() to choose which core source to add.

When a clip is first added to a timeline, its core elements will be created for the current tracks in the timeline if they have not already been created. Then this will be emitted for each of these core children to select which tracks, if any, they should be added to. It will then be called for any non-core children in the clip.

In addition, if a new track element is ever added to a clip in a timeline (and it is not already part of a track) this will be emitted to select which tracks the element should be added to.

Finally, as a special case, if a track is added to the timeline after it already contains clips, then it will request the creation of the clips’ core elements of the corresponding type, if they have not already been created, and this signal will be emitted for each of these newly created elements. In addition, this will also be released for all other track elements in the timeline’s clips that have not yet been assigned a track. However, in this final case, the timeline will only check whether the newly added track appears in the track list. If it does appear, the track element will be added to the newly added track. All other tracks in the returned track list are ignored.

In this latter case, track elements that are already part of a track will not be asked if they want to be copied into the new track. If you wish to do this, you can use ClipExt::add_child_to_track().

Note that the returned GPtrArray should own a new reference to each of its contained Track. The timeline will set the GDestroyNotify free function on the GPtrArray to dereference the elements.

snapping-ended

Will be emitted whenever a snapping event ends. After a snap event has started (see snapping-started), it can later end because either another timeline edit has occurred (which may or may not have created a new snapping event), or because the timeline has been committed.

snapping-started

Will be emitted whenever an element’s movement invokes a snapping event during an edit (usually of one of its ancestors) because its start or end point lies within the snapping-distance of another element’s start or end point.

See EditMode to see what can snap during an edit.

Note that only up to one snapping-started signal will be emitted per element edit within a timeline.

track-added

Will be emitted after the track is added to the timeline.

Note that this should not be emitted whilst a timeline is being loaded from its Project asset. You should connect to the project’s loaded signal if you want to know which tracks were created for the timeline.

track-removed

Will be emitted after the track is removed from the timeline.

Bin

deep-element-added

Will be emitted after the element was added to sub_bin.

deep-element-removed

Will be emitted after the element was removed from sub_bin.

do-latency

Will be emitted when the bin needs to perform latency calculations. This signal is only emitted for toplevel bins or when async-handling is enabled.

Only one signal handler is invoked. If no signals are connected, the default handler is invoked, which will query and distribute the lowest possible latency to all sinks.

Connect to this signal if the default latency calculations are not sufficient, like when you need different latencies for different sinks in the same pipeline.

element-added

Will be emitted after the element was added to the bin.

element-removed

Will be emitted after the element was removed from the bin.

Element

no-more-pads

This signals that the element will not generate more dynamic pads. Note that this signal will usually be emitted from the context of the streaming thread.

pad-added

a new gst::Pad has been added to the element. Note that this signal will usually be emitted from the context of the streaming thread. Also keep in mind that if you add new elements to the pipeline in the signal handler you will need to set them to the desired target state with [ElementExtManual::set_state()][crate::gst::prelude::ElementExtManual::set_state()] or [ElementExtManual::sync_state_with_parent()][crate::gst::prelude::ElementExtManual::sync_state_with_parent()].

pad-removed

a gst::Pad has been removed from the element

Object

deep-notify

The deep notify signal is used to be notified of property changes. It is typically attached to the toplevel bin to receive notifications from all the elements contained in that bin.

Detailed

ChildProxy

child-added

Will be emitted after the object was added to the child_proxy.

child-removed

Will be emitted after the object was removed from the child_proxy.

MetaContainer

notify-meta

This is emitted for a meta container whenever the metadata under one of its fields changes, is set for the first time, or is removed. In the latter case, value will be None.

Detailed

Implements

TimelineExt, [trait@gst::prelude::BinExt], gst::prelude::ElementExt, gst::prelude::GstObjectExt, glib::ObjectExt, gst::prelude::ChildProxyExt, ExtractableExt, MetaContainerExt

Implementations

impl Timeline

pub const NONE: Option<&'static Timeline> = None

pub fn new() -> Timeline

Creates a new empty timeline.

Returns

The new timeline.

pub fn new_audio_video() -> Timeline

Creates a new timeline containing a single AudioTrack and a single VideoTrack.

Returns

The new timeline.

pub fn from_uri(uri: &str) -> Result<Timeline, Error>

Creates a timeline from the given URI.

uri

The URI to load from

Returns

A new timeline if the uri was loaded successfully, or None if the uri could not be loaded.

Trait Implementations

impl Clone for Timeline

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Timeline

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Timeline

fn default() -> Self

Returns the “default value” for a type.

impl HasParamSpec for Timeline

type ParamSpec = ParamSpecObject

type SetValue = Timeline

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, Timeline>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Timeline

fn hash<H>(&self, state: &mut H)where
    H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Timeline

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl ParentClassIs for Timeline

type Parent = Bin

impl<OT: ObjectType> PartialEq<OT> for Timeline

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Timeline

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Timeline

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Timeline

impl IsA<Bin> for Timeline

impl IsA<ChildProxy> for Timeline

impl IsA<Element> for Timeline

impl IsA<Extractable> for Timeline

impl IsA<MetaContainer> for Timeline

impl IsA<Object> for Timeline