Trait gstreamer_editing_services::prelude::ClipExt

pub trait ClipExt:
    IsA<Clip>
    + Sealed
    + 'static {
    // Provided methods
    fn add_asset(
        &self,
        asset: &impl IsA<Asset>,
    ) -> Result<TrackElement, BoolError> { ... }
    fn add_child_to_track(
        &self,
        child: &impl IsA<TrackElement>,
        track: &impl IsA<Track>,
    ) -> Result<TrackElement, Error> { ... }
    fn add_top_effect(
        &self,
        effect: &impl IsA<BaseEffect>,
        index: i32,
    ) -> Result<(), Error> { ... }
    fn find_track_element(
        &self,
        track: Option<&impl IsA<Track>>,
        type_: Type,
    ) -> Option<TrackElement> { ... }
    fn find_track_elements(
        &self,
        track: Option<&impl IsA<Track>>,
        track_type: TrackType,
        type_: Type,
    ) -> Vec<TrackElement> { ... }
    fn duration_limit(&self) -> ClockTime { ... }
    fn internal_time_from_timeline_time(
        &self,
        child: &impl IsA<TrackElement>,
        timeline_time: impl Into<Option<ClockTime>>,
    ) -> Result<Option<ClockTime>, Error> { ... }
    fn layer(&self) -> Option<Layer> { ... }
    fn supported_formats(&self) -> TrackType { ... }
    fn timeline_time_from_internal_time(
        &self,
        child: &impl IsA<TrackElement>,
        internal_time: impl Into<Option<ClockTime>>,
    ) -> Result<Option<ClockTime>, Error> { ... }
    fn timeline_time_from_source_frame(
        &self,
        frame_number: FrameNumber,
    ) -> Result<Option<ClockTime>, Error> { ... }
    fn top_effect_index(&self, effect: &impl IsA<BaseEffect>) -> i32 { ... }
    fn top_effect_position(&self, effect: &impl IsA<BaseEffect>) -> i32 { ... }
    fn top_effects(&self) -> Vec<TrackElement> { ... }
    fn move_to_layer(&self, layer: &impl IsA<Layer>) -> Result<(), BoolError> { ... }
    fn move_to_layer_full(&self, layer: &impl IsA<Layer>) -> Result<(), Error> { ... }
    fn remove_top_effect(
        &self,
        effect: &impl IsA<BaseEffect>,
    ) -> Result<(), Error> { ... }
    fn set_supported_formats(&self, supportedformats: TrackType) { ... }
    fn set_top_effect_index(
        &self,
        effect: &impl IsA<BaseEffect>,
        newindex: u32,
    ) -> Result<(), BoolError> { ... }
    fn set_top_effect_index_full(
        &self,
        effect: &impl IsA<BaseEffect>,
        newindex: u32,
    ) -> Result<(), Error> { ... }
    fn set_top_effect_priority(
        &self,
        effect: &impl IsA<BaseEffect>,
        newpriority: u32,
    ) -> Result<(), BoolError> { ... }
    fn split(&self, position: u64) -> Result<Clip, BoolError> { ... }
    fn split_full(&self, position: u64) -> Result<Option<Clip>, Error> { ... }
    fn connect_duration_limit_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
    fn connect_layer_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
    fn connect_supported_formats_notify<F: Fn(&Self) + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId { ... }
}

Trait containing all Clip methods.

Implementors

Clip, OperationClip, SourceClip

Provided Methods

fn add_asset(&self, asset: &impl IsA<Asset>) -> Result<TrackElement, BoolError>

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

asset

An asset with GES_TYPE_TRACK_ELEMENT as its extractable-type

Returns

The newly created element, or None if an error occurred.

fn add_child_to_track( &self, child: &impl IsA<TrackElement>, track: &impl IsA<Track>, ) -> Result<TrackElement, Error>

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 Timeline, and for tracks that are in the same timeline.

This method is an alternative to using the 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 Timeline, such as causing three sources to overlap at a single time, or causing a source to completely overlap another in the same track.

child

A child of self

track

The track to add child to

Returns

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

fn add_top_effect( &self, effect: &impl IsA<BaseEffect>, index: i32, ) -> Result<(), Error>

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

Unlike using GESContainerExt::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 GESClipClass that have GES_CLIP_CLASS_CAN_ADD_EFFECTS set to true (such as SourceClip and 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.

effect

A top effect to add

index

The index to add effect at, or -1 to add at the highest, see ges_clip_get_top_effect_index for more information

Returns

true if effect was successfully added to self at index.

fn find_track_element( &self, track: Option<&impl IsA<Track>>, type_: Type, ) -> Option<TrackElement>

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 priority (numerically, the smallest). See find_track_elements() if you wish to find all such elements.

track

The track to search in, or None to search in all tracks

type_

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.

fn find_track_elements( &self, track: Option<&impl IsA<Track>>, track_type: TrackType, type_: Type, ) -> Vec<TrackElement>

Finds the TrackElement-s controlled by the clip that match the given criteria. If track is given as None and track_type is given as TrackType::UNKNOWN, then the search will match all elements in any track, including those with no track, and of any track-type. Otherwise, if track is not None, but track_type is TrackType::UNKNOWN, then only the track elements in track are searched for. Otherwise, if track_type is not TrackType::UNKNOWN, but track is None, then only the track elements whose 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 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_.

track

The track to search in, or None to search in all tracks

track_type

The track-type of the track element to search for, or TrackType::UNKNOWN to match any track type

type_

The type of track element to search for, or G_TYPE_NONE to match any type

Returns

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

fn duration_limit(&self) -> ClockTime

Gets the duration-limit of the clip.

Returns

The duration-limit of self.

fn internal_time_from_timeline_time( &self, child: &impl IsA<TrackElement>, timeline_time: impl Into<Option<ClockTime>>, ) -> Result<Option<ClockTime>, Error>

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 BaseEffect for what time effects are supported, and how to declare them in GES).

When timeline_time is above the 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 max-duration.

If, instead, timeline_time is below the current start of self, this will return what you would need to set the in-point of child to if you set the start of self to timeline_time and wanted to keep the content of child currently found at the current start of self at the same timeline position. If this would be negative, the conversion fails. This is useful for determining what in-point would result from a 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 in-point or max-duration of the child.

See timeline_time_from_internal_time(), which performs the reverse.

child

An active child of self with a track

timeline_time

A time in the timeline time coordinates

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.

fn layer(&self) -> Option<Layer>

Gets the layer of the clip.

Returns

The layer self is in, or None if self is not in any layer.

fn supported_formats(&self) -> TrackType

Gets the supported-formats of the clip.

Returns

The TrackType-s supported by self.

fn timeline_time_from_internal_time( &self, child: &impl IsA<TrackElement>, internal_time: impl Into<Option<ClockTime>>, ) -> Result<Option<ClockTime>, Error>

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 BaseEffect for what time effects are supported, and how to declare them in GES).

When internal_time is above the 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 duration-limit.

If, instead, internal_time is below the current in-point of child, this will return what you would need to set the start of self to if you set the in-point of child to internal_time and wanted to keep the content of child currently found at the current 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 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 TimelineElementExt::edit() for 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 in-point, by translating the desired end time into the timeline coordinates, and using this position to trim the end of a clip.

See internal_time_from_timeline_time(), which performs the reverse, or timeline_time_from_source_frame() which does the same conversion, but using frame numbers.

child

An active child of self with a track

internal_time

A time in the internal time coordinates of child

Returns

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

fn timeline_time_from_source_frame( &self, frame_number: FrameNumber, ) -> Result<Option<ClockTime>, Error>

Convert the source frame number to a timeline time. This acts the same as 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 ClipAssetExt::frame_time().

frame_number

The frame number to get the corresponding timestamp of in the timeline coordinates

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.

fn top_effect_index(&self, effect: &impl IsA<BaseEffect>) -> i32

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

effect

The effect we want to get the index of

Returns

The index of effect in self, or -1 if something went wrong.

fn top_effect_position(&self, effect: &impl IsA<BaseEffect>) -> i32

fn top_effects(&self) -> Vec<TrackElement>

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

Returns

A list of all BaseEffect-s that have been added to self.

fn move_to_layer(&self, layer: &impl IsA<Layer>) -> Result<(), BoolError>

See move_to_layer_full(), which also gives an error.

layer

The new layer

Returns

true if self was successfully moved to layer.

fn move_to_layer_full(&self, layer: &impl IsA<Layer>) -> Result<(), Error>

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.

layer

The new layer

Returns

true if self was successfully moved to layer.

fn remove_top_effect(&self, effect: &impl IsA<BaseEffect>) -> Result<(), Error>

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.

effect

The top effect to remove

Returns

true if effect was successfully added to self at index.

fn set_supported_formats(&self, supportedformats: TrackType)

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

supportedformats

The TrackType-s supported by self

fn set_top_effect_index( &self, effect: &impl IsA<BaseEffect>, newindex: u32, ) -> Result<(), BoolError>

See set_top_effect_index_full(), which also gives an error.

effect

An effect within self to move

newindex

The index for effect in self

Returns

true if effect was successfully moved to newindex.

fn set_top_effect_index_full( &self, effect: &impl IsA<BaseEffect>, newindex: u32, ) -> Result<(), Error>

Set the index of an effect within the clip. See 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.

effect

An effect within self to move

newindex

The index for effect in self

Returns

true if effect was successfully moved to newindex.

fn set_top_effect_priority( &self, effect: &impl IsA<BaseEffect>, newpriority: u32, ) -> Result<(), BoolError>

fn split(&self, position: u64) -> Result<Clip, BoolError>

See split_full(), which also gives an error.

position

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.

fn split_full(&self, position: u64) -> Result<Option<Clip>, Error>

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

The original clip’s duration is reduced such that its end point matches the split position. Then a new clip is created in the same layer, whose start matches the split position and 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 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 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 Project, which only contains this clip (and its effects), and in the original layer create two neighbouring UriClip-s that reference this sub-project, but at a different in-point.

position

The timeline position at which to perform the split, between the start and end of the clip

Returns

The newly created clip resulting from the splitting self, or None if self can’t be split.

fn connect_duration_limit_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

fn connect_layer_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

fn connect_supported_formats_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

Object Safety

This trait is not object safe.

Implementors

impl<O: IsA<Clip>> ClipExt for O