GESTimeline

## GESTimeline GESTimeline — Multimedia timeline |

## Synopsis

    #include <ges/ges.h>

                        GESTimeline;
    GESTimeline *       ges_timeline_new                    (void);
    GESTimeline *       ges_timeline_new_audio_video        (void);
    GESTimeline *       ges_timeline_new_from_uri           (const gchar *uri,
                                                             GError **error);
    gboolean            ges_timeline_add_layer              (GESTimeline *timeline,
                                                             GESLayer *layer);
    GESLayer *          ges_timeline_append_layer           (GESTimeline *timeline);
    gboolean            ges_timeline_remove_layer           (GESTimeline *timeline,
                                                             GESLayer *layer);
    gboolean            ges_timeline_add_track              (GESTimeline *timeline,
                                                             GESTrack *track);
    gboolean            ges_timeline_remove_track           (GESTimeline *timeline,
                                                             GESTrack *track);
    gboolean            ges_timeline_load_from_uri          (GESTimeline *timeline,
                                                             const gchar *uri,
                                                             GError **error);
    gboolean            ges_timeline_save_to_uri            (GESTimeline *timeline,
                                                             const gchar *uri,
                                                             GESAsset *formatter_asset,
                                                             gboolean overwrite,
                                                             GError **error);

    GList *             ges_timeline_get_tracks             (GESTimeline *timeline);
    GList *             ges_timeline_get_layers             (GESTimeline *timeline);
    GESTrack *          ges_timeline_get_track_for_pad      (GESTimeline *timeline,
                                                             GstPad *pad);
    GstClockTime        ges_timeline_get_duration           (GESTimeline *timeline);
    #define             ges_timeline_get_project            (obj)
    gboolean            ges_timeline_get_auto_transition    (GESTimeline *timeline);
    void                ges_timeline_set_auto_transition    (GESTimeline *timeline,
                                                             gboolean auto_transition);
    GstClockTime        ges_timeline_get_snapping_distance  (GESTimeline *timeline);
    void                ges_timeline_set_snapping_distance  (GESTimeline *timeline,
                                                             GstClockTime snapping_distance);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GstObject
                   +----GstElement
                         +----GstBin
                               +----GESTimeline

## Implemented Interfaces

GESTimeline implements GstChildProxy, GESExtractable and GESMetaContainer.

## Properties

      "auto-transition"          gboolean              : Read / Write
      "duration"                 guint64               : Read
      "snapping-distance"        guint64               : Read / Write

## Signals

      "commited"                                       : Run Last
      "layer-added"                                    : Run First
      "layer-removed"                                  : Run First
      "select-tracks-for-object"                       : Run Last
      "snapping-ended"                                 : Run Last
      "snapping-started"                               : Run Last
      "track-added"                                    : Run First
      "track-removed"                                  : Run First

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

## Details

### GESTimeline

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

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]

### ges_timeline_new ()

    GESTimeline *       ges_timeline_new                    (void);

Creates a new empty GESTimeline.

Returns : | The new timeline.

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

### ges_timeline_new_from_uri ()

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

Creates a timeline from the given URI.

`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

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

`timeline` : | a GESTimeline
`layer` : | the GESLayer to add
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.

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

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

`timeline` : | a GESTimeline
`track` : | the GESTrack to add
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.

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

`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

`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_get_tracks ()

    GList *             ges_timeline_get_tracks             (GESTimeline *timeline);

Returns the list of GESTrack used by the Timeline.

`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_layers ()

    GList *             ges_timeline_get_layers             (GESTimeline *timeline);

Get the list of GESLayer present in the Timeline.

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

`timeline` : | The GESTimeline
`pad` : | The GstPad
Returns : | The corresponding GESTrack if it is found, or `NULL` if there is an error. [transfer none]

### ges_timeline_get_duration ()

    GstClockTime        ges_timeline_get_duration           (GESTimeline *timeline);

Get the current duration of `timeline`

`timeline` : | a GESTimeline
Returns : | The current duration of `timeline`

### ges_timeline_get_project()

    #define ges_timeline_get_project(obj) (GES_TIMELINE (ges_extractable_get_asset (obj))

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

`obj` : | The GESClip 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.

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

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

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

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

## Property Details

### The `"auto-transition"` property

      "auto-transition"          gboolean              : Read / Write

Sets whether transitions are added automagically when clips overlap.

Default value: FALSE

### The `"duration"` property

      "duration"                 guint64               : Read

Current duration (in nanoseconds) of the GESTimeline

Default value: 18446744073709551615

### The `"snapping-distance"` property

      "snapping-distance"        guint64               : Read / Write

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

Default value: 0

## Signal Details

### The `"commited"` signal

    void                user_function                      (GESTimeline *timeline,
                                                            gpointer     user_data)      : Run Last

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

### The `"layer-added"` signal

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

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

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

### The `"layer-removed"` signal

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

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

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

### The `"select-tracks-for-object"` signal

    GPtrArray*          user_function                      (GESTimeline     *timeline,
                                                            GESClip         *clip,
                                                            GESTrackElement *track-element,
                                                            gpointer         user_data)          : Run Last

`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]

Since 0.10.XX

### The `"snapping-ended"` signal

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

### The `"snapping-started"` signal

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

### The `"track-added"` signal

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

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

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

### The `"track-removed"` signal

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

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

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