GESTimeline: GStreamer Editing Services 1.16.2 Reference Manual

## GESTimeline GESTimeline — Multimedia timeline |

## Functions

GESTimeline * | ges_timeline_new ()
GESTimeline * | ges_timeline_new_audio_video ()
GESTimeline * | ges_timeline_new_from_uri ()
gboolean | ges_timeline_add_layer ()
GESLayer * | ges_timeline_append_layer ()
gboolean | ges_timeline_remove_layer ()
gboolean | ges_timeline_add_track ()
gboolean | ges_timeline_remove_track ()
gboolean | ges_timeline_load_from_uri ()
gboolean | ges_timeline_save_to_uri ()
gboolean | ges_timeline_commit ()
gboolean | ges_timeline_commit_sync ()
gboolean | ges_timeline_move_layer ()
GList * | ges_timeline_get_tracks ()
GESLayer * | ges_timeline_get_layer ()
GList * | ges_timeline_get_layers ()
GESTrack * | ges_timeline_get_track_for_pad ()
GstPad * | ges_timeline_get_pad_for_track ()
GstClockTime | ges_timeline_get_duration ()
#define | ges_timeline_get_project()
gboolean | ges_timeline_get_auto_transition ()
void | ges_timeline_set_auto_transition ()
GstClockTime | ges_timeline_get_snapping_distance ()
void | ges_timeline_set_snapping_distance ()
GESTimelineElement * | ges_timeline_get_element ()
gboolean | ges_timeline_is_empty ()
#define | GES_TIMELINE_GET_LAYERS()
#define | GES_TIMELINE_GET_TRACKS()

## Properties

gboolean | auto-transition | Read / Write
guint64 | duration | Read
guint64 | snapping-distance | Read / Write

## Signals

void | commited | Run Last
void | group-added | Run First
void | group-removed | Run First
void | layer-added | Run First
void | layer-removed | Run First
GPtrArray* | select-tracks-for-object | Run Last
void | snapping-ended | Run Last
void | snapping-started | Run Last
void | track-added | Run First
void | track-removed | Run First

## Types and Values

| GESTimeline

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstElement
                    ╰── GstBin
                        ╰── GESTimeline

## Implemented Interfaces

GESTimeline implements GstChildProxy, GESExtractable and GESMetaContainer.

## Includes

    #include <ges/ges.h>

## Description

GESTimeline is the central object for any multimedia timeline.

Contains a list of GESLayer which users should use to arrange the various clips through time.

The output type is determined by the GESTrack that are set on the GESTimeline.

To save/load a timeline, you can use the `ges_timeline_load_from_uri()` and `ges_timeline_save_to_uri()` methods to use the default format. If you wish

Note that any change you make in the timeline will not actually be taken into account until you call the ges_timeline_commit method.

## Functions

### ges_timeline_new ()

    GESTimeline *
    ges_timeline_new (void);

Creates a new empty GESTimeline.

#### Returns

The new timeline.

[transfer floating]

### ges_timeline_new_audio_video ()

    GESTimeline *
    ges_timeline_new_audio_video (void);

Creates a new GESTimeline containing a raw audio and a raw video track.

#### Returns

The newly created GESTimeline.

[transfer floating]

### ges_timeline_new_from_uri ()

    GESTimeline *
    ges_timeline_new_from_uri (const gchar *uri,
                               GError **error);

Creates a timeline from the given URI.

#### Parameters

uri | the URI to load from |
error | An error to be set in case something wrong happens or `NULL`. | [out][allow-none]

#### Returns

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

[transfer floating][nullable]

### ges_timeline_add_layer ()

    gboolean
    ges_timeline_add_layer (GESTimeline *timeline,
                            GESLayer *layer);

Add the layer to the timeline. The reference to the `layer` will be stolen by the `timeline` .

#### Parameters

timeline | a GESTimeline |
layer | the GESLayer to add. | [transfer floating]

#### Returns

`TRUE` if the layer was properly added, else `FALSE`.

### ges_timeline_append_layer ()

    GESLayer *
    ges_timeline_append_layer (GESTimeline *timeline);

Append a newly created GESLayer to `timeline` Note that you do not own any reference to the returned layer.

#### Parameters

timeline | a GESTimeline |

#### Returns

The newly created GESLayer, or the last (empty) GESLayer of `timeline` .

[transfer none]

### ges_timeline_remove_layer ()

    gboolean
    ges_timeline_remove_layer (GESTimeline *timeline,
                               GESLayer *layer);

Removes the layer from the timeline. The reference that the `timeline` holds on the layer will be dropped. If you wish to use the `layer` after calling this method, you need to take a reference before calling.

#### Parameters

timeline | a GESTimeline |
layer | the GESLayer to remove |

#### Returns

`TRUE` if the layer was properly removed, else `FALSE`.

### ges_timeline_add_track ()

    gboolean
    ges_timeline_add_track (GESTimeline *timeline,
                            GESTrack *track);

Add a track to the timeline. The reference to the track will be stolen by the pipeline.

#### Parameters

timeline | a GESTimeline |
track | the GESTrack to add. | [transfer full]

#### Returns

`TRUE` if the track was properly added, else `FALSE`.

### ges_timeline_remove_track ()

    gboolean
    ges_timeline_remove_track (GESTimeline *timeline,
                               GESTrack *track);

Remove the `track` from the `timeline` . The reference stolen when adding the `track` will be removed. If you wish to use the `track` after calling this function you must ensure that you have a reference to it.

#### Parameters

timeline | a GESTimeline |
track | the GESTrack to remove |

#### Returns

`TRUE` if the `track` was properly removed, else `FALSE`.

### ges_timeline_load_from_uri ()

    gboolean
    ges_timeline_load_from_uri (GESTimeline *timeline,
                                const gchar *uri,
                                GError **error);

Loads the contents of URI into the given timeline.

#### Parameters

timeline | an empty GESTimeline into which to load the formatter |
uri | The URI to load from |
error | An error to be set in case something wrong happens or `NULL`. | [out][allow-none]

#### Returns

`TRUE` if the timeline was loaded successfully, or `FALSE` if the uri could not be loaded.

### ges_timeline_save_to_uri ()

    gboolean
    ges_timeline_save_to_uri (GESTimeline *timeline,
                              const gchar *uri,
                              GESAsset *formatter_asset,
                              gboolean overwrite,
                              GError **error);

Saves the timeline to the given location

#### Parameters

timeline | a GESTimeline |
uri | The location to save to |
formatter_asset | The formatter asset to use or `NULL`. If `NULL`, will try to save in the same format as the one from which the timeline as been loaded or default to the formatter with highest rank. | [allow-none]
overwrite | `TRUE` to overwrite file if it exists |
error | An error to be set in case something wrong happens or `NULL`. | [out][allow-none]

#### Returns

`TRUE` if the timeline was successfully saved to the given location, else `FALSE`.

### ges_timeline_commit ()

    gboolean
    ges_timeline_commit (GESTimeline *timeline);

Commit all the pending changes of the clips contained in the `timeline` .

When changes happen in a timeline, they are not directly executed in the non-linear engine. Call this method once you are done with a set of changes and want it to be executed.

The “commited” signal will be emitted when the (possibly updated) GstPipeline is ready to output data again, except if the state of the timeline was GST_STATE_READY or GST_STATE_NULL.

Note that all the pending changes will automatically be executed when the timeline goes from GST_STATE_READY to GST_STATE_PAUSED, which usually is triggered by corresponding state changes in a containing GESPipeline.

You should not try to change the state of the timeline, seek it or add tracks to it during a commit operation, that is between a call to this function and after receiving the “commited” signal.

See ges_timeline_commit_sync if you don't want to bother with waiting for the signal.

#### Parameters

timeline | a GESTimeline |

#### Returns

`TRUE` if pending changes were commited or `FALSE` if nothing needed to be commited

### ges_timeline_commit_sync ()

    gboolean
    ges_timeline_commit_sync (GESTimeline *timeline);

Commit all the pending changes of the GESClips contained in the `timeline` .

Will return once the update is complete, that is when the (possibly updated) GstPipeline is ready to output data again, or if the state of the timeline was GST_STATE_READY or GST_STATE_NULL.

This function will wait for any pending state change of the timeline by calling gst_element_get_state with a GST_CLOCK_TIME_NONE timeout, you should not try to change the state from another thread before this function has returned.

See ges_timeline_commit for more information.

#### Parameters

timeline | a GESTimeline |

#### Returns

`TRUE` if pending changes were commited or `FALSE` if nothing needed to be commited

### ges_timeline_move_layer ()

    gboolean
    ges_timeline_move_layer (GESTimeline *timeline,
                             GESLayer *layer,
                             guint new_layer_priority);

Moves `layer` at `new_layer_priority` meaning that `layer` we land at that position in the stack of layers inside the timeline. If `new_layer_priority` is superior than the number of layers present in the time, it will move to the end of the stack of layers.

#### Parameters

timeline | The timeline in which `layer` must be |
layer | The layer to move at `new_layer_priority` |
new_layer_priority | The index at which `layer` should land |

Since: 1.16

### ges_timeline_get_tracks ()

    GList *
    ges_timeline_get_tracks (GESTimeline *timeline);

Returns the list of GESTrack used by the Timeline.

#### Parameters

timeline | a GESTimeline |

#### Returns

A list of GESTrack. The caller should unref each track once he is done with them.

[transfer full][element-type GESTrack]

### ges_timeline_get_layer ()

    GESLayer *
    ges_timeline_get_layer (GESTimeline *timeline,
                            guint priority);

Retrieve the layer with `priority` as a priority

#### Parameters

timeline | The GESTimeline to retrive a layer from |
priority | The priority of the layer to find |

#### Returns

A GESLayer or `NULL` if no layer with `priority` was found

Since 1.6.

[transfer full][nullable]

### ges_timeline_get_layers ()

    GList *
    ges_timeline_get_layers (GESTimeline *timeline);

Get the list of GESLayer present in the Timeline.

#### Parameters

timeline | a GESTimeline |

#### Returns

the list of GESLayer present in the Timeline sorted by priority. The caller should unref each Layer once he is done with them.

[transfer full][element-type GESLayer]

### ges_timeline_get_track_for_pad ()

    GESTrack *
    ges_timeline_get_track_for_pad (GESTimeline *timeline,
                                    GstPad *pad);

Search the GESTrack corresponding to the given `timeline` 's `pad` .

#### Parameters

timeline | The GESTimeline |
pad | The GstPad |

#### Returns

The corresponding GESTrack if it is found, or `NULL` if there is an error.

[transfer none][nullable]

### ges_timeline_get_pad_for_track ()

    GstPad *
    ges_timeline_get_pad_for_track (GESTimeline *timeline,
                                    GESTrack *track);

Search the GstPad corresponding to the given `timeline` 's `track` .

#### Parameters

timeline | The GESTimeline |
track | The GESTrack |

#### Returns

The corresponding GstPad if it is found, or `NULL` if there is an error.

[transfer none][nullable]

### ges_timeline_get_duration ()

    GstClockTime
    ges_timeline_get_duration (GESTimeline *timeline);

Get the current duration of `timeline`

#### Parameters

timeline | a GESTimeline |

#### Returns

The current duration of `timeline`

### ges_timeline_get_project()

    #define ges_timeline_get_project(obj) (GES_PROJECT (ges_extractable_get_asset (GES_EXTRACTABLE(obj))))

Helper macro to retrieve the project from which a GESTimeline as been extracted

#### Parameters

obj | The GESTimeline from which to retrieve the project |

### ges_timeline_get_auto_transition ()

    gboolean
    ges_timeline_get_auto_transition (GESTimeline *timeline);

Gets whether transitions are automatically added when objects overlap or not.

#### Parameters

timeline | a GESTimeline |

#### Returns

`TRUE` if transitions are automatically added, else `FALSE`.

### ges_timeline_set_auto_transition ()

    void
    ges_timeline_set_auto_transition (GESTimeline *timeline,
                                      gboolean auto_transition);

Sets the layer to the given `auto_transition` . See the documentation of the property auto_transition for more information.

#### Parameters

timeline | a GESLayer |
auto_transition | whether the auto_transition is active |

### ges_timeline_get_snapping_distance ()

    GstClockTime
    ges_timeline_get_snapping_distance (GESTimeline *timeline);

Gets the configured snapping distance of the timeline. See the documentation of the property snapping_distance for more information.

#### Parameters

timeline | a GESTimeline |

#### Returns

The `snapping_distance` property of the timeline

### ges_timeline_set_snapping_distance ()

    void
    ges_timeline_set_snapping_distance (GESTimeline *timeline,
                                        GstClockTime snapping_distance);

Sets the `snapping_distance` of the timeline. See the documentation of the property snapping_distance for more information.

#### Parameters

timeline | a GESLayer |
snapping_distance | whether the snapping_distance is active |

### ges_timeline_get_element ()

    GESTimelineElement *
    ges_timeline_get_element (GESTimeline *timeline,
                              const gchar *name);

Gets a GESTimelineElement contained in the timeline

#### Parameters

timeline | a GESTimeline |

#### Returns

The GESTimelineElement or `NULL` if not found.

[transfer full][nullable]

### ges_timeline_is_empty ()

    gboolean
    ges_timeline_is_empty (GESTimeline *timeline);

Check whether a GESTimeline is empty or not

#### Parameters

timeline | a GESTimeline |

#### Returns

`TRUE` if the timeline is empty `FALSE` otherwize

### GES_TIMELINE_GET_LAYERS()

    #define GES_TIMELINE_GET_LAYERS(obj) (GES_TIMELINE (obj)->layers)

### GES_TIMELINE_GET_TRACKS()

    #define GES_TIMELINE_GET_TRACKS(obj) (GES_TIMELINE (obj)->tracks)

## Types and Values

### GESTimeline

    typedef struct {
      /* <readonly> */
      GList *layers;
      GList *tracks;
    } GESTimeline;

#### Members

GList *`layers`; | A list of GESLayer sorted by priority NOTE: Do not modify. | [element-type GES.Layer]
GList *`tracks`; | A list of GESTrack sorted by priority NOTE: Do not modify. | [element-type GES.Track]

## Property Details

### The `“auto-transition”` property

      “auto-transition”          gboolean

Sets whether transitions are added automagically when clips overlap.

Owner: GESTimeline

Flags: Read / Write

Default value: FALSE

### The `“duration”` property

      “duration”                 guint64

Current duration (in nanoseconds) of the GESTimeline

Owner: GESTimeline

Flags: Read

Default value: 18446744073709551615

### The `“snapping-distance”` property

      “snapping-distance”        guint64

Distance (in nanoseconds) from which a moving object will snap with it neighboors. 0 means no snapping.

Owner: GESTimeline

Flags: Read / Write

Default value: 0

## Signal Details

### The `“commited”` signal

    void
    user_function (GESTimeline *timeline,
                   gpointer     user_data)

This signal will be emitted once the changes initiated by ges_timeline_commit have been executed in the backend. Use ges_timeline_commit_sync if you don't need to do anything in the meantime.

#### Parameters

timeline | the GESTimeline |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“group-added”` signal

    void
    user_function (GESTimeline *timeline,
                   GESGroup    *group,
                   gpointer     user_data)

Will be emitted after a new group is added to to the timeline.

#### Parameters

timeline | the GESTimeline |
group | the GESGroup |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“group-removed”` signal

    void
    user_function (GESTimeline *timeline,
                   GESGroup    *group,
                   GPtrArray   *children,
                   gpointer     user_data)

Will be emitted after a group has been removed from the timeline.

#### Parameters

timeline | the GESTimeline |
group | the GESGroup |
children | a list of GESContainer. | [element-type GES.Container][transfer container]
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“layer-added”` signal

    void
    user_function (GESTimeline *timeline,
                   GESLayer    *layer,
                   gpointer     user_data)

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

#### Parameters

timeline | the GESTimeline |
layer | the GESLayer that was added to the timeline |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“layer-removed”` signal

    void
    user_function (GESTimeline *timeline,
                   GESLayer    *layer,
                   gpointer     user_data)

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

#### Parameters

timeline | the GESTimeline |
layer | the GESLayer that was removed from the timeline |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“select-tracks-for-object”` signal

    GPtrArray*
    user_function (GESTimeline     *timeline,
                   GESClip         *clip,
                   GESTrackElement *track_element,
                   gpointer         user_data)

#### Parameters

timeline | the GESTimeline |
clip | The GESClip on which `track_element` will land |
track_element | The GESTrackElement for which to choose the tracks it should land into |
user_data | user data set when the signal handler was connected. |

#### Returns

a GPtrArray of GESTrack-s where that object should be added.

[transfer full][element-type GESTrack]

Flags: Run Last

### The `“snapping-ended”` signal

    void
    user_function (GESTimeline     *timeline,
                   GESTrackElement *obj1,
                   GESTrackElement *obj2,
                   guint64          position,
                   gpointer         user_data)

Will be emitted when the 2 GESTrackElement ended to snap

#### Parameters

timeline | the GESTimeline |
obj1 | the first GESTrackElement that was snapping. |
obj2 | the second GESTrackElement that was snapping. |
position | the position where the two objects finally snapping. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“snapping-started”` signal

    void
    user_function (GESTimeline     *timeline,
                   GESTrackElement *obj1,
                   GESTrackElement *obj2,
                   guint64          position,
                   gpointer         user_data)

Will be emitted when the 2 GESTrackElement first snapped

#### Parameters

timeline | the GESTimeline |
obj1 | the first GESTrackElement that was snapping. |
obj2 | the second GESTrackElement that was snapping. |
position | the position where the two objects finally snapping. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“track-added”` signal

    void
    user_function (GESTimeline *timeline,
                   GESTrack    *track,
                   gpointer     user_data)

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

#### Parameters

timeline | the GESTimeline |
track | the GESTrack that was added to the timeline |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“track-removed”` signal

    void
    user_function (GESTimeline *timeline,
                   GESTrack    *track,
                   gpointer     user_data)

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

#### Parameters

timeline | the GESTimeline |
track | the GESTrack that was removed from the timeline |
user_data | user data set when the signal handler was connected. |

Flags: Run First