GESAsset: GStreamer Editing Services 1.16.1 Reference Manual

## GESAsset GESAsset — Represents usable resources inside the GStreamer Editing Services |

## Functions

GType | ges_asset_get_extractable_type ()
const gchar * | ges_asset_get_id ()
GESAsset * | ges_asset_request ()
void | ges_asset_request_async ()
GESAsset * | ges_asset_request_finish ()
GESExtractable * | ges_asset_extract ()
GError * | ges_asset_get_error ()
GList * | ges_list_assets ()
gboolean | ges_asset_set_proxy ()
GList * | ges_asset_list_proxies ()
GESAsset * | ges_asset_get_proxy_target ()
GESAsset * | ges_asset_get_proxy ()
gboolean | ges_asset_needs_reload ()

## Types and Values

| GESAsset

## Object Hierarchy

        GObject
        ╰── GESAsset
            ├── GESProject
            ├── GESClipAsset
            ╰── GESTrackElementAsset

## Implemented Interfaces

GESAsset implements GAsyncInitable, GInitable and GESMetaContainer.

## Includes

    #include <ges/ges.h>

## Description

The Assets in the GStreamer Editing Services represent the resources that can be used. You can create assets for any type that implements the GESExtractable interface, for example GESClips, GESFormatter, and GESTrackElement do implement it. This means that assets will represent for example a GESUriClips, GESBaseEffect etc, and then you can extract objects of those types with the appropriate parameters from the asset using the ges_asset_extract method:

    1
    2
    3
    4
    5
    6
    7
    8
    GESAsset *effect_asset;
    GESEffect *effect;

    // You create an asset for an effect
    effect_asset = ges_asset_request (GES_TYPE_EFFECT, "agingtv", NULL);

    // And now you can extract an instance of GESEffect from that asset
    effect = GES_EFFECT (ges_asset_extract (effect_asset));

In that example, the advantages of having a GESAsset are that you can know what effects you are working with and let your user know about the avalaible ones, you can add metadata to the GESAsset through the GESMetaContainer interface and you have a model for your custom effects. Note that GESAsset management is making easier thanks to the GESProject class.

Each asset is represented by a pair of `extractable_type` and `id` (string). Actually the `extractable_type` is the type that implements the GESExtractable interface, that means that for example for a GESUriClip, the type that implements the GESExtractable interface is GESClip. The identifier represents different things depending on the `extractable_type` and you should check the documentation of each type to know what the ID of GESAsset actually represents for that type. By default, we only have one GESAsset per type, and the `id` is the name of the type, but this behaviour is overriden to be more useful. For example, for GESTransitionClips, the ID is the vtype of the transition you will extract from it (ie crossfade, box-wipe-rc etc..) For GESEffect the ID is the `bin` -description property of the extracted objects (ie the gst-launch style description of the bin that will be used).

Each and every GESAsset is cached into GES, and you can query those with the ges_list_assets function. Also the system will automatically register GESAssets for GESFormatters and GESTransitionClips and standard effects (actually not implemented yet) and you can simply query those calling:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    GList *formatter_assets, *tmp;

    //  List all  the transitions
    formatter_assets = ges_list_assets (GES_TYPE_FORMATTER);

    // Print some infos about the formatter GESAsset
    for (tmp = formatter_assets; tmp; tmp = tmp->next) {
      g_print ("Name of the formatter: %s, file extension it produces: %s",
        ges_meta_container_get_string (GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_NAME),
        ges_meta_container_get_string (GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_EXTENSION));
    }

    g_list_free (transition_assets);

You can request the creation of GESAssets using either `ges_asset_request()` or `ges_asset_request_async()`. All the GESAssets are cached and thus any asset that has already been created can be requested again without overhead.

## Functions

### ges_asset_get_extractable_type ()

    GType
    ges_asset_get_extractable_type (GESAsset *self);

Gets the type of object that can be extracted from `self`

#### Parameters

self | The GESAsset |

#### Returns

the type of object that can be extracted from `self`

### ges_asset_get_id ()

    const gchar *
    ges_asset_get_id (GESAsset *self);

Gets the ID of a GESAsset

#### Parameters

self | The GESAsset to get ID from |

#### Returns

The ID of `self`

### ges_asset_request ()

    GESAsset *
    ges_asset_request (GType extractable_type,
                       const gchar *id,
                       GError **error);

Create a GESAsset in the most simple cases, you should look at the `extractable_type` documentation to see if that constructor can be called for this particular type

As it is recommanded not to instanciate assets for GESUriClip synchronously, it will not work with this method, but you can instead use the specific ges_uri_clip_asset_request_sync method if you really want to.

#### Parameters

extractable_type | The GType of the object that can be extracted from the new asset. |
id | The Identifier or `NULL`. | [allow-none]
error | An error to be set in case something wrong happens or `NULL`. | [allow-none]

#### Returns

A reference to the wanted GESAsset or `NULL`.

[transfer full][allow-none]

### ges_asset_request_async ()

    void
    ges_asset_request_async (GType extractable_type,
                             const gchar *id,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

The `callback` will be called from a running GMainLoop which is iterating a GMainContext. Note that, users should ensure the GMainContext, since this method will notify `callback` from the thread which was associated with a thread default GMainContext at calling `ges_init()`. For example, if a user wants non-default GMainContext to be associated with `callback` , `ges_init()` must be called after `g_main_context_push_thread_default()` with custom GMainContext.

Request a new GESAsset asyncronously, `callback` will be called when the materail is ready to be used or if an error occured.

Example of request of a GESAsset async:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    // The request callback
    static void
    asset_loaded_cb (GESAsset * source, GAsyncResult * res, gpointer user_data)
    {
      GESAsset *asset;
      GError *error = NULL;

      asset = ges_asset_request_finish (res, &error);
      if (asset) {
       g_print ("The file: %s is usable as a FileSource",
           ges_asset_get_id (asset));
      } else {
       g_print ("The file: %s is *not* usable as a FileSource because: %s",
           ges_asset_get_id (source), error->message);
      }

      gst_object_unref (mfs);
    }

    // The request:
    ges_asset_request_async (GES_TYPE_URI_CLIP, some_uri, NULL,
       (GAsyncReadyCallback) asset_loaded_cb, user_data);

#### Parameters

extractable_type | The GType of the object that can be extracted from the new asset. The class must implement the GESExtractable interface. |
id | The Identifier of the asset we want to create. This identifier depends of the extractable, type you want. By default it is the name of the class itself (or `NULL`), but for example for a GESEffect, it will be the pipeline description, for a GESUriClip it will be the name of the file, etc... You should refer to the documentation of the GESExtractable type you want to create a GESAsset for. |
cancellable | optional `GCancellable` object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback to call when the initialization is finished, Note that the `source` of the callback will be the GESAsset, but you need to make sure that the asset is properly loaded using the ges_asset_request_finish method. This asset can not be used as is. |
user_data | The user data to pass when `callback` is called |

### ges_asset_request_finish ()

    GESAsset *
    ges_asset_request_finish (GAsyncResult *res,
                              GError **error);

Finalize the request of an async GESAsset

#### Parameters

res | The GAsyncResult from which to get the newly created GESAsset |
error | An error to be set in case something wrong happens or `NULL`. | [out][allow-none][transfer full]

#### Returns

The GESAsset previously requested.

[transfer full][allow-none]

### ges_asset_extract ()

    GESExtractable *
    ges_asset_extract (GESAsset *self,
                       GError **error);

Extracts a new GObject from `asset` . The type of the object is defined by the extractable-type of `asset` , you can check what type will be extracted from `asset` using ges_asset_get_extractable_type

#### Parameters

self | The GESAsset to get extract an object from |
error | An error to be set in case something wrong happens or `NULL`. | [allow-none]

#### Returns

A newly created GESExtractable.

[transfer floating][allow-none]

### ges_asset_get_error ()

    GError *
    ges_asset_get_error (GESAsset *self);

#### Parameters

self | The asset to retrieve the error from |

#### Returns

The GError of the asset or `NULL` if the asset was loaded without issue.

[transfer none][nullable]

Since: 1.8

### ges_list_assets ()

    GList *
    ges_list_assets (GType filter);

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

#### Parameters

filter | Type of assets to list, GES_TYPE_EXTRACTABLE will list all assets |

#### Returns

The list of GESAsset the object contains.

[transfer container][element-type GESAsset]

### ges_asset_set_proxy ()

    gboolean
    ges_asset_set_proxy (GESAsset *asset,
                         GESAsset *proxy);

A proxying asset is an asset that can substitue the real `asset` . For example if you have a full HD GESUriClipAsset you might want to set a lower resolution (HD version of the same file) as proxy. Note that when an asset is proxied, calling ges_asset_request will actually return the proxy asset.

#### Parameters

asset | The GESAsset to set proxy on |
proxy | The GESAsset that should be used as default proxy for `asset` or `NULL` if you want to use the currently set proxy. Note that an asset can proxy one and only one other asset. | [allow-none]

#### Returns

`TRUE` if `proxy` has been set on `asset` , `FALSE` otherwise.

### ges_asset_list_proxies ()

    GList *
    ges_asset_list_proxies (GESAsset *asset);

#### Parameters

asset | The GESAsset to get proxies from |

#### Returns

The list of proxies `asset` has. Note that the default asset to be used is always the first in that list.

[element-type GESAsset][transfer none]

### ges_asset_get_proxy_target ()

    GESAsset *
    ges_asset_get_proxy_target (GESAsset *proxy);

#### Parameters

proxy | The GESAsset from which to get the the asset it proxies. |

#### Returns

The GESAsset that is proxied by `proxy` .

[transfer none][nullable]

### ges_asset_get_proxy ()

    GESAsset *
    ges_asset_get_proxy (GESAsset *asset);

#### Parameters

asset | The GESAsset to get currenlty used proxy |

#### Returns

The proxy in use for `asset` .

[transfer none][nullable]

### ges_asset_needs_reload ()

    gboolean
    ges_asset_needs_reload (GType extractable_type,
                            const gchar *id);

Sets an asset from the internal cache as needing reload. An asset needs reload in the case where, for example, we were missing a GstPlugin to use it and that plugin has been installed, or, that particular asset content as changed meanwhile (in the case of the usage of proxies).

Once an asset has been set as "needs reload", requesting that asset again will lead to it being re discovered, and reloaded as if it was not in the cache before.

#### Parameters

extractable_type | The GType of the object that can be extracted from the asset to be reloaded. |
id | The identifier of the asset to mark as needing reload |

#### Returns

`TRUE` if the asset was in the cache and could be set as needing reload, `FALSE` otherwise.

## Types and Values

### GESAsset

    typedef struct _GESAsset GESAsset;