## 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 ()
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 ()

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

Returns (transfer floating) (nullable): A new timeline if the uri was loaded successfully, or NULL if the uri could not be loaded.

#### Parameters

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

### 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 full]

#### 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 GESTimeline::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 GESTimeline::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_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 GESTimelineElement is empty or not

#### Parameters

timeline | a GESTimeline |

#### Returns

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

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

Flags: Read / Write

Default value: FALSE

### The `“duration”` property

      “duration”                 guint64

Current duration (in nanoseconds) of the 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.

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     *gestimeline,
                   GESTrackElement *arg1,
                   GESTrackElement *arg2,
                   guint64          arg3,
                   gpointer         user_data)

Flags: Run Last

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

    void
    user_function (GESTimeline     *gestimeline,
                   GESTrackElement *arg1,
                   GESTrackElement *arg2,
                   guint64          arg3,
                   gpointer         user_data)

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