GES.Asset¶

Subclasses:: GES.ClipAsset, GES.Project, GES.TrackElementAsset

Methods¶

Inherited:: GObject.Object (37), GES.MetaContainer (40), Gio.AsyncInitable (4), Gio.Initable (2)
Structs:: GObject.ObjectClass (5)

class	`needs_reload` (extractable_type, id)
class	`request` (extractable_type, id)
class	`request_async` (extractable_type, id, cancellable, callback, *user_data)
class	`request_finish` (res)
	`extract` ()
	`get_error` ()
	`get_extractable_type` ()
	`get_id` ()
	`get_proxy` ()
	`get_proxy_target` ()
	`list_proxies` ()
	`set_proxy` (proxy)
	`unproxy` (proxy)

Virtual Methods¶

Inherited:: GObject.Object (7), Gio.AsyncInitable (2), Gio.Initable (1)

	`do_extract` ()
	`do_inform_proxy` (proxy_id)
	`do_proxied` (proxy)
	`do_request_id_update` (proposed_new_id, error)
	`do_start_loading` ()

Properties¶

Name	Type	Flags	Short Description
`extractable-type`	`GObject.GType`	r/w/co	The type of the Object that can be extracted out of the asset
`id`	`str`	r/w/co	The unique identifier of the asset
`proxy`	`GES.Asset`	r/w	The asset default proxy.
`proxy-target`	`GES.Asset`	r	The target of a proxy asset.

Signals¶

Inherited:: GObject.Object (1), GES.MetaContainer (1)

Fields¶

Inherited:: GObject.Object (1), GES.MetaContainer (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class GES.Asset(**kwargs)¶

Bases:: GObject.Object, GES.MetaContainer, Gio.AsyncInitable, Gio.Initable
Abstract:: No
Structure:: GES.AssetClass

A GES.Asset in the GStreamer Editing Services represents a resources that can be used. In particular, any class that implements the GES.Extractable interface may have some associated assets with a corresponding GES.Asset :extractable-type, from which its objects can be extracted using GES.Asset.extract(). Some examples would be GES.Clip, GES.Formatter and GES.TrackElement.

All assets that are created within GES are stored in a cache; one per each GES.Asset :id and GES.Asset :extractable-type pair. These assets can be fetched, and initialized if they do not yet exist in the cache, using GES.Asset.request().

``` c GES.Asset *effect_asset; GES.Effect *effect;

// You create an asset for an effect effect_asset = GES.Asset.request (GES_TYPE_EFFECT, “agingtv”, None);

// And now you can extract an instance of GES.Effect from that asset effect = GES_EFFECT (GES.Asset.extract (effect_asset));

```

The advantage of using assets, rather than simply creating the object directly, is that the currently loaded resources can be listed with GES.list_assets() and displayed to an end user. For example, to show which media files have been loaded, and a standard list of effects. In fact, the GES library already creates assets for GES.TransitionClip and GES.Formatter, which you can use to list all the available transition types and supported formats.

The other advantage is that GES.Asset implements GES.MetaContainer, so metadata can be set on the asset, with some subclasses automatically creating this metadata on initiation.

For example, to display information about the supported formats, you could do the following:

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) {
  gst_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);

ID

Each asset is uniquely defined in the cache by its GES.Asset :extractable-type and GES.Asset :id. Depending on the GES.Asset :extractable-type, the GES.Asset :id can be used to parametrise the creation of the object upon extraction. By default, a class that implements GES.Extractable will only have a single associated asset, with an GES.Asset :id set to the type name of its objects. However, this is overwritten by some implementations, which allow a class to have multiple associated assets. For example, for GES.TransitionClip the GES.Asset :id will be a nickname of the GES.TransitionClip :vtype. You should check the documentation for each extractable type to see if they differ from the default.

Moreover, each GES.Asset :extractable-type may also associate itself with a specific asset subclass. In such cases, when their asset is requested, an asset of this subclass will be returned instead.

Managing

You can use a GES.Project to easily manage the assets of a GES.Timeline.

Proxies

Some assets can (temporarily) act as the GES.Asset :proxy of another asset. When the original asset is requested from the cache, the proxy will be returned in its place. This can be useful if, say, you want to substitute a GES.UriClipAsset corresponding to a high resolution media file with the asset of a lower resolution stand in.

An asset may even have several proxies, the first of which will act as its default and be returned on requests, but the others will be ordered to take its place once it is removed. You can add a proxy to an asset, or set its default, using GES.Asset.set_proxy(), and you can remove them with GES.Asset.unproxy().

classmethod needs_reload(extractable_type, id)[source]¶

Parameters:

extractable_type (GObject.GType) – The GES.Asset :extractable-type of the asset that needs reloading
id (str or None) – The GES.Asset :id of the asset asset that needs reloading

Returns:

True if the specified asset exists in the cache and could be marked for reloading.

Return type:

bool

Indicate that an existing GES.Asset in the cache should be reloaded upon the next request. This can be used when some condition has changed, which may require that an existing asset should be updated. For example, if an external resource has changed or now become available.

Note, the asset is not immediately changed, but will only actually reload on the next call to GES.Asset.request() or GES.Asset.request_async().

classmethod request(extractable_type, id)[source]¶

Parameters:

extractable_type (GObject.GType) – The GES.Asset :extractable-type of the asset
id (str or None) – The GES.Asset :id of the asset

Raises:

GLib.Error

Returns:

A reference to the requested asset, or None if an error occurred.

Return type:

GES.Asset or None

Returns an asset with the given properties. If such an asset already exists in the cache (it has been previously created in GES), then a reference to the existing asset is returned. Otherwise, a newly created asset is returned, and also added to the cache.

If the requested asset has been loaded with an error, then error is set, if given, and None will be returned instead.

Note that the given id may not be exactly the GES.Asset :id that is set on the returned asset. For instance, it may be adjusted into a standard format. Or, if a GES.Extractable type does not have its extraction parametrised, as is the case by default, then the given id may be ignored entirely and the GES.Asset :id set to some standard, in which case a None id can be given.

Similarly, the given extractable_type may not be exactly the GES.Asset :extractable-type that is set on the returned asset. Instead, the actual extractable type may correspond to a subclass of the given extractable_type, depending on the given id.

Moreover, depending on the given extractable_type, the returned asset may belong to a subclass of GES.Asset.

Finally, if the requested asset has a GES.Asset :proxy, then the proxy that is found at the end of the chain of proxies is returned (a proxy’s proxy will take its place, and so on, unless it has no proxy).

Some asset subclasses only support asynchronous construction of its assets, such as GES.UriClip. For such assets this method will fail, and you should use GES.Asset.request_async() instead. In the case of GES.UriClip, you can use GES.UriClipAsset.request_sync() if you only want to wait for the request to finish.

classmethod request_async(extractable_type, id, cancellable, callback, *user_data)[source]¶

Parameters:

extractable_type (GObject.GType) – The GES.Asset :extractable-type of the asset
id (str or None) – The GES.Asset :id of the asset
cancellable (Gio.Cancellable or None) – An object to allow cancellation of the asset request, or None to ignore
callback (Gio.AsyncReadyCallback or None) – A function to call when the initialization is finished
user_data (object or None) – Data to be passed to callback

Requests an asset with the given properties asynchronously (see GES.Asset.request()). When the asset has been initialized or fetched from the cache, the given callback function will be called. The asset can then be retrieved in the callback using the GES.Asset.request_finish() method on the given Gio.AsyncResult.

Note that the source object passed to the callback will be the GES.Asset corresponding to the request, but it may not have loaded correctly and therefore can not be used as is. Instead, GES.Asset.request_finish() should be used to fetch a usable asset, or indicate that an error occurred in the asset’s creation.

Note that the callback will be called in the GLib.MainLoop running under the same GLib.MainContext that GES.init() was called in. So, if you wish the callback to be invoked outside the default GLib.MainContext, you can call GLib.MainContext.push_thread_default() in a new thread before calling GES.init().

Example of an asynchronous asset request: ``` c // The request callback static void asset_loaded_cb (GES.Asset * source, Gio.AsyncResult * res, object user_data) { GES.Asset *asset; GLib.Error *error = None;

asset = GES.Asset.request_finish (res, &error); if (asset) { gst_print (“The file: %s is usable as a GES.UriClip", GES.Asset.get_id (asset)); } else { gst_print (“The file: %s is *not* usable as a GES.UriClip because: %s”, GES.Asset.get_id (source), error->message); }

Gst.Object.unref (asset); }

// The request: GES.Asset.request_async (GES_TYPE_URI_CLIP, some_uri, None, (Gio.AsyncReadyCallback) asset_loaded_cb, user_data); ```

classmethod request_finish(res)[source]¶

Parameters:: res (Gio.AsyncResult) – The task result to fetch the asset from
Raises:: GLib.Error
Returns:: The requested asset, or None if an error occurred.
Return type:: GES.Asset

Fetches an asset requested by GES.Asset.request_async(), which finalises the request.

extract()[source]¶

Raises:: GLib.Error
Returns:: A newly created object, or None if an error occurred.
Return type:: GES.Extractable

Extracts a new GES.Asset :extractable-type object from the asset. The GES.Asset :id of the asset may determine the properties and state of the newly created object.

get_error()[source]¶

Returns:: The error set on asset, or None if no error occurred when asset was loaded.
Return type:: GLib.Error or None

Retrieve the error that was set on the asset when it was loaded.

New in version 1.8.

get_extractable_type()[source]¶

Returns:: The extractable type of self.
Return type:: GObject.GType

Gets the GES.Asset :extractable-type of the asset.

get_id()[source]¶

Returns:: The ID of self.
Return type:: str

Gets the GES.Asset :id of the asset.

get_proxy()[source]¶

Returns:: The default proxy of self.
Return type:: GES.Asset or None

Gets the default GES.Asset :proxy of the asset.

get_proxy_target()[source]¶

Returns:: The asset that self is a proxy of.
Return type:: GES.Asset or None

Gets the GES.Asset :proxy-target of the asset.

Note that the proxy target may have loaded with an error, so you should call GES.Asset.get_error() on the returned target.

list_proxies()[source]¶

Returns:: The list of proxies that self has.
Return type:: [GES.Asset]

Get all the proxies that the asset has. The first item of the list will be the default GES.Asset :proxy. The second will be the proxy that is ‘next in line’ to be default, and so on.

set_proxy(proxy)[source]¶

Parameters:: proxy (GES.Asset or None) – A new default proxy for self
Returns:: True if proxy was successfully set as the default for self.
Return type:: bool

Sets the GES.Asset :proxy for the asset.

If proxy is among the existing proxies of the asset (see GES.Asset.list_proxies()) it will be moved to become the default proxy. Otherwise, if proxy is not None, it will be added to the list of proxies, as the new default. The previous default proxy will become ‘next in line’ for if the new one is removed, and so on. As such, this will **not** actually remove the previous default proxy (use GES.Asset.unproxy() for that).

Note that an asset can only act as a proxy for one other asset.

As a special case, if proxy is None, then this method will actually remove **all** proxies from the asset.

unproxy(proxy)[source]¶

Parameters:: proxy (GES.Asset) – An existing proxy of self
Returns:: True if proxy was successfully removed from self's proxy list.
Return type:: bool

Removes the proxy from the available list of proxies for the asset. If the given proxy is the default proxy of the list, then the next proxy in the available list (see GES.Asset.list_proxies()) will become the default. If there are no other proxies, then the asset will no longer have a default GES.Asset :proxy.

do_extract() virtual¶

Returns:: A newly created object, or None if an error occurred.
Return type:: GES.Extractable

Extracts a new GES.Asset :extractable-type object from the asset. The GES.Asset :id of the asset may determine the properties and state of the newly created object.

do_inform_proxy(proxy_id) virtual¶

Parameters:: proxy_id (str) –

do_proxied(proxy) virtual¶

Parameters:: proxy (GES.Asset) –

Deprecated: 1.18: This vmethod is no longer called.

do_request_id_update(proposed_new_id, error) virtual¶

Parameters:

proposed_new_id (str) –
error (GLib.Error) –

Return type:

bool

A method called by a GES.Project when an asset has failed to load. error is the error given by GES.Asset.request_finish (). Returns: True if a new id for self was passed to proposed_new_id.

do_start_loading() virtual¶

Return type:: GES.AssetLoadingReturn

A method to be called when an asset is being requested asynchronously. This will be after the properties of the asset have been set, so it is tasked with (re)loading the ‘state’ of the asset. The return value should indicated whether the loading is complete, is carrying on asynchronously, or an error occurred. The default implementation will simply return that loading is already complete (the asset is already in a usable state after the properties have been set).

Property Details¶

GES.Asset.props.extractable_type¶

Name:: extractable-type
Type:: GObject.GType
Default Value:: <GType GObject>
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The GES.Extractable object type that can be extracted from the asset.

GES.Asset.props.id¶

Name:: id
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The ID of the asset. This should be unique amongst all assets with the same GES.Asset :extractable-type. Depending on the associated GES.Extractable implementation, this id may convey some information about the GObject.Object that should be extracted. Note that, as such, the ID will have an expected format, and you can not choose this value arbitrarily. By default, this will be set to the type name of the GES.Asset :extractable-type, but you should check the documentation of the extractable type to see whether they differ from the default behaviour.

GES.Asset.props.proxy¶

Name:: proxy
Type:: GES.Asset
Default Value:: None
Flags:: READABLE, WRITABLE

The default proxy for this asset, or None if it has no proxy. A proxy will act as a substitute for the original asset when the original is requested (see GES.Asset.request()).

Setting this property will not usually remove the existing proxy, but will replace it as the default (see GES.Asset.set_proxy()).

GES.Asset.props.proxy_target¶

Name:: proxy-target
Type:: GES.Asset
Default Value:: None
Flags:: READABLE

The asset that this asset is a proxy for, or None if it is not a proxy for another asset.

Note that even if this asset is acting as a proxy for another asset, but this asset is not the default GES.Asset :proxy, then proxy-target will *still* point to this other asset. So you should check the GES.Asset :proxy property of target-proxy before assuming it is the current default proxy for the target.

Note that the GObject.Object ::notify for this property is emitted after the GES.Asset :proxy GObject.Object ::notify for the corresponding (if any) asset it is now the proxy of/no longer the proxy of.