GESProject

## GESProject GESProject — A GESAsset that is used to manage projects |

## Synopsis

    #include <ges/ges.h>

                        GESProject;
    gboolean            ges_project_load                    (GESProject *project,
                                                             GESTimeline *timeline,
                                                             GError **error);
    gboolean            ges_project_add_asset               (GESProject *project,
                                                             GESAsset *asset);
    gboolean            ges_project_remove_asset            (GESProject *project,
                                                             GESAsset *asset);
    GList *             ges_project_list_assets             (GESProject *project,
                                                             GType filter);
    GESAsset *          ges_project_get_asset               (GESProject *project,
                                                             const gchar *id,
                                                             GType extractable_type);
    gboolean            ges_project_save                    (GESProject *project,
                                                             GESTimeline *timeline,
                                                             const gchar *uri,
                                                             GESAsset *formatter_asset,
                                                             gboolean overwrite,
                                                             GError **error);
    gboolean            ges_project_create_asset            (GESProject *project,
                                                             const gchar *id,
                                                             GType extractable_type);
    GType               ges_project_get_type                (void);
    gchar *             ges_project_get_uri                 (GESProject *project);
    GESProject *        ges_project_new                     (const gchar *uri);
    gboolean            ges_project_add_encoding_profile    (GESProject *project,
                                                             GstEncodingProfile *profile);
    const GList *       ges_project_list_encoding_profiles  (GESProject *project);
    GList *             ges_project_get_loading_assets      (GESProject *project);

## Object Hierarchy

      GObject
       +----GESAsset
             +----GESProject

## Implemented Interfaces

GESProject implements GAsyncInitable, GInitable and GESMetaContainer.

## Properties

      "uri"                      gchar*                : Read / Write / Construct Only

## Signals

      "asset-added"                                    : Run Last
      "asset-removed"                                  : Run Last
      "error-loading-asset"                            : Run Last
      "loaded"                                         : Run First
      "missing-uri"                                    : Run Last

## Description

The GESProject is used to control a set of GESAsset and is a GESAsset with GES_TYPE_TIMELINE as `extractable_type` itself. That means that you can extract GESTimeline from a project as followed:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    GESProject *project;
    GESTimeline *timeline;

    project = ges_project_new ("file:///path/to/a/valid/project/uri");

    // Here you can connect to the various signal to get more infos about
    // what is happening and recover from errors if possible
    ...

    timeline = ges_asset_extract (GES_ASSET (project));

The GESProject class offers a higher level API to handle GESAsset-s. It lets you request new asset, and it informs you about new assets through a set of signals. Also it handles problem such as missing files/missing GstElement and lets you try to recover from those.

## Details

### GESProject

    typedef struct _GESProject GESProject;

### ges_project_load ()

    gboolean            ges_project_load                    (GESProject *project,
                                                             GESTimeline *timeline,
                                                             GError **error);

Loads `project` into `timeline`

`project` : | A GESProject that has an `uri` set already
`timeline` : | A blank timeline to load `project` into
`error` : | An error to be set in case something wrong happens or `NULL`. [out][allow-none]
Returns : | `TRUE` if the project could be loaded `FALSE` otherwize.

### ges_project_add_asset ()

    gboolean            ges_project_add_asset               (GESProject *project,
                                                             GESAsset *asset);

Adds a Asset to `project`, the project will keep a reference on `asset`.

`project` : | A GESProject
`asset` : | A GESAsset to add to `project`. [transfer none]
Returns : | `TRUE` if the asset could be added `FALSE` it was already in the project

### ges_project_remove_asset ()

    gboolean            ges_project_remove_asset            (GESProject *project,
                                                             GESAsset *asset);

remove a `asset` to from `project`.

`project` : | A GESProject
`asset` : | A GESAsset to remove from `project`. [transfer none]
Returns : | `TRUE` if the asset could be removed `FALSE` otherwise

### ges_project_list_assets ()

    GList *             ges_project_list_assets             (GESProject *project,
                                                             GType filter);

List all `asset` contained in `project` filtering per extractable_type as defined by `filter`. It copies the asset and thus will not be updated in time.

`project` : | A GESProject
`filter` : | Type of assets to list, GES_TYPE_EXTRACTABLE will list all assets
Returns : | The list of GESAsset the object contains. [transfer full][element-type GESAsset]

### ges_project_get_asset ()

    GESAsset *          ges_project_get_asset               (GESProject *project,
                                                             const gchar *id,
                                                             GType extractable_type);

`project` : | A GESProject
`id` : | The id of the asset to retrieve
`extractable_type` : | The extractable_type of the asset to retrieve from `object`
Returns : | The GESAsset with `id` or `NULL` if no asset with `id` as an ID. [transfer full][allow-none]

### ges_project_save ()

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

Save the timeline of `project` to `uri`. You should make sure that `timeline` is one of the timelines that have been extracted from `project` (using ges_asset_extract (`project`);)

`project` : | A GESProject to save
`timeline` : | The GESTimeline to save, it must have been extracted from `project`
`uri` : | The uri where to save `project` and `timeline`
`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 project could be save, `FALSE` otherwize

### ges_project_create_asset ()

    gboolean            ges_project_create_asset            (GESProject *project,
                                                             const gchar *id,
                                                             GType extractable_type);

Create and add a GESAsset to `project`. You should connect to the "asset-added" signal to get the asset when it finally gets added to `project`

`project` : | A GESProject
`id` : | The id of the asset to create and add to `project`. [allow-none]
`extractable_type` : | The GType of the asset to create
Returns : | `TRUE` if the asset started to be added `FALSE` it was already in the project

### ges_project_get_type ()

    GType               ges_project_get_type                (void);

### ges_project_get_uri ()

    gchar *             ges_project_get_uri                 (GESProject *project);

Retrieve the uri that is currently set on `project`

`project` : | A GESProject
Returns : | The uri that is set on `project`

### ges_project_new ()

    GESProject *        ges_project_new                     (const gchar *uri);

Creates a new GESProject and sets its uri to `uri` if provided. Note that if `uri` is not valid or `NULL`, the uri of the project will then be set the first time you save the project. If you then save the project to other locations, it will never be updated again and the first valid URI is the URI it will keep refering to.

`uri` : | The uri to be set after creating the project. [allow-none]
Returns : | A newly created GESProject

### ges_project_add_encoding_profile ()

    gboolean            ges_project_add_encoding_profile    (GESProject *project,
                                                             GstEncodingProfile *profile);

Adds `profile` to the project. It lets you save in what format the project has been renders and keep a reference to those formats. Also, those formats will be saves to the project file when possible.

`project` : | A GESProject
`profile` : | A GstEncodingProfile to add to the project. If a profile with the same name already exists, it will be replaced
Returns : | `TRUE` if `profile` could be added, `FALSE` otherwize

### ges_project_list_encoding_profiles ()

    const GList *       ges_project_list_encoding_profiles  (GESProject *project);

Lists the encoding profile that have been set to `project`. The first one is the latest added.

`project` : | A GESProject
Returns : | The list of GstEncodingProfile used in `project`. [transfer none][element-type GstPbutils.EncodingProfile][allow-none]

### ges_project_get_loading_assets ()

    GList *             ges_project_get_loading_assets      (GESProject *project);

Get the assets that are being loaded

`project` : | A GESProject
Returns : | A set of loading asset that will be added to `project`. Note that those Asset are *not* loaded yet, and thus can not be used. [transfer full][element-type GES.Asset]

## Property Details

### The `"uri"` property

      "uri"                      gchar*                : Read / Write / Construct Only

uri of the project.

Default value: NULL

## Signal Details

### The `"asset-added"` signal

    void                user_function                      (GESProject *formatter,
                                                            GESAsset   *asset,
                                                            gpointer    user_data)      : Run Last

`formatter` : | the GESProject
`asset` : | The GESAsset that has been added to `project`
`user_data` : | user data set when the signal handler was connected.

### The `"asset-removed"` signal

    void                user_function                      (GESProject *formatter,
                                                            GESAsset   *asset,
                                                            gpointer    user_data)      : Run Last

`formatter` : | the GESProject
`asset` : | The GESAsset that has been removed from `project`
`user_data` : | user data set when the signal handler was connected.

### The `"error-loading-asset"` signal

    void                user_function                      (GESProject *project,
                                                            GError     *error,
                                                            gchar      *id,
                                                            GType      *extractable_type,
                                                            gpointer    user_data)             : Run Last

Informs you that a GESAsset could not be created. In case of missing GStreamer plugins, the error will be set to GST_CORE_ERROR GST_CORE_ERROR_MISSING_PLUGIN

`project` : | the GESProject on which a problem happend when creted a GESAsset
`error` : | The GError defining the error that accured, might be `NULL`
`id` : | The `id` of the asset that failed loading
`extractable_type` : | The `extractable_type` of the asset that failed loading
`user_data` : | user data set when the signal handler was connected.

### The `"loaded"` signal

    void                user_function                      (GESProject  *project,
                                                            GESTimeline *timeline,
                                                            gpointer     user_data)      : Run First

`project` : | the GESProject that is done loading a project.
`timeline` : | The GESTimeline that complete loading
`user_data` : | user data set when the signal handler was connected.

### The `"missing-uri"` signal

    gchar*              user_function                      (GESProject *project,
                                                            GError     *error,
                                                            GESAsset   *wrong_asset,
                                                            gpointer    user_data)        : Run Last

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    static gchar
    source_moved_cb (GESProject *project, GError *error, GESAsset *asset_with_error)
    {
      return g_strdup ("file:///the/new/uri.ogg");
    }

    static int
    main (int argc, gchar ** argv)
    {
      GESTimeline *timeline;
      GESProject *project = ges_project_new ("file:///some/uri.xges");

      g_signal_connect (project, "missing-uri", source_moved_cb, NULL);
      timeline = ges_asset_extract (GES_ASSET (project));
    }

`project` : | the GESProject reporting that a file has moved
`error` : | The error that happened
`wrong_asset` : | The asset with the wrong ID, you should us it and its content only to find out what the new location is.
`user_data` : | user data set when the signal handler was connected.
Returns : | The new URI of `wrong_asset`. [transfer full][allow-none]