GI.GES.Objects.Asset

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

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

c code

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

The advantage of using assets, rather than simply creating the object directly, is that the currently loaded resources can be listed with listAssets 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 TransitionClip and Formatter, which you can use to list all the available transition types and supported formats.

The other advantage is that Asset implements 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 Asset:extractableType and Asset:id. Depending on the Asset:extractableType, the Asset:id can be used to parametrise the creation of the object upon extraction. By default, a class that implements Extractable will only have a single associated asset, with an 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 TransitionClip the Asset:id will be a nickname of the TransitionClip:vtype. You should check the documentation for each extractable type to see if they differ from the default.

Moreover, each Asset:extractableType 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 Project to easily manage the assets of a Timeline.

Proxies

Some assets can (temporarily) act as the 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 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 assetSetProxy, and you can remove them with assetUnproxy.

Exported types

newtype Asset

Memory-managed wrapper type.

Constructors

Asset (ManagedPtr Asset)

Instances

Eq Asset

Defined in GI.GES.Objects.Asset

Methods

(==) :: Asset -> Asset -> Bool

(/=) :: Asset -> Asset -> Bool

GObject Asset

Defined in GI.GES.Objects.Asset

ManagedPtrNewtype Asset

Defined in GI.GES.Objects.Asset

Methods

toManagedPtr :: Asset -> ManagedPtr Asset

TypedObject Asset

Defined in GI.GES.Objects.Asset

Methods

glibType :: IO GType

HasParentTypes Asset

Defined in GI.GES.Objects.Asset

IsGValue (Maybe Asset)

Convert Asset to and from GValue. See toGValue and fromGValue.

Defined in GI.GES.Objects.Asset

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Asset -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Asset)

type ParentTypes Asset

Defined in GI.GES.Objects.Asset

type ParentTypes Asset = '[Object, MetaContainer, AsyncInitable, Initable]

class (GObject o, IsDescendantOf Asset o) => IsAsset o

Type class for types which can be safely cast to Asset, for instance with toAsset.

Instances

(GObject o, IsDescendantOf Asset o) => IsAsset o

Defined in GI.GES.Objects.Asset

toAsset :: (MonadIO m, IsAsset o) => o -> m Asset

Cast to Asset, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

addMetasFromString, bindProperty, bindPropertyFull, checkMetaRegistered, extract, forceFloating, foreach, freezeNotify, getv, init, initAsync, initFinish, isFloating, listProxies, metasToString, newFinish, notify, notifyByPspec, ref, refSink, registerMeta, registerMetaBoolean, registerMetaDate, registerMetaDateTime, registerMetaDouble, registerMetaFloat, registerMetaInt, registerMetaInt64, registerMetaString, registerMetaUint, registerMetaUint64, registerStaticMeta, runDispose, stealData, stealQdata, thawNotify, unproxy, unref, watchClosure.

Getters

getBoolean, getData, getDate, getDateTime, getDouble, getError, getExtractableType, getFloat, getId, getInt, getInt64, getMarkerList, getMeta, getProperty, getProxy, getProxyTarget, getQdata, getString, getUint, getUint64.

Setters

setBoolean, setData, setDataFull, setDate, setDateTime, setDouble, setFloat, setInt, setInt64, setMarkerList, setMeta, setProperty, setProxy, setString, setUint, setUint64.

extract

assetExtract

Arguments

:: (HasCallStack, MonadIO m, IsAsset a)

=> a

self: The Asset to extract an object from

-> m Extractable

Returns: A newly created object, or Nothing if an error occurred. (Can throw GError)

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

getError

assetGetError

Arguments

:: (HasCallStack, MonadIO m, IsAsset a)

=> a

self: A Asset

-> m (Maybe GError)

Returns: The error set on asset, or Nothing if no error occurred when asset was loaded.

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

Since: 1.8

getExtractableType

assetGetExtractableType

Arguments

:: (HasCallStack, MonadIO m, IsAsset a)

=> a

self: The Asset

-> m GType

Returns: The extractable type of self.

Gets the Asset:extractableType of the asset.

getId

assetGetId

Arguments

:: (HasCallStack, MonadIO m, IsAsset a)

=> a

self: A Asset

-> m Text

Returns: The ID of self.

Gets the Asset:id of the asset.

getProxy

assetGetProxy

Arguments

:: (HasCallStack, MonadIO m, IsAsset a)

=> a

asset: A Asset

-> m (Maybe Asset)

Returns: The default proxy of asset.

Gets the default Asset:proxy of the asset.

getProxyTarget

assetGetProxyTarget

Arguments

:: (HasCallStack, MonadIO m, IsAsset a)

=> a

proxy: A Asset

-> m (Maybe Asset)

Returns: The asset that proxy is a proxy of.

Gets the Asset:proxyTarget of the asset.

Note that the proxy target may have loaded with an error, so you should call assetGetError on the returned target.

listProxies

assetListProxies

Arguments

:: (HasCallStack, MonadIO m, IsAsset a)

=> a

asset: A Asset

-> m [Asset]

Returns: The list of proxies that asset has.

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

needsReload

assetNeedsReload

Arguments

:: (HasCallStack, MonadIO m)

=> GType

extractableType: The Asset:extractableType of the asset that needs reloading

-> Maybe Text

id: The Asset:id of the asset asset that needs reloading

-> m Bool

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

Indicate that an existing 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 assetRequest or assetRequestAsync.

request

assetRequest

Arguments

:: (HasCallStack, MonadIO m)

=> GType

extractableType: The Asset:extractableType of the asset

-> Maybe Text

id: The Asset:id of the asset

-> m (Maybe Asset)

Returns: A reference to the requested asset, or Nothing if an error occurred. (Can throw GError)

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 Nothing will be returned instead.

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

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

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

Finally, if the requested asset has a 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 UriClip. For such assets this method will fail, and you should use assetRequestAsync instead. In the case of UriClip, you can use uriClipAssetRequestSync if you only want to wait for the request to finish.

requestAsync

assetRequestAsync

Arguments

:: (HasCallStack, MonadIO m, IsCancellable a)

=> GType

extractableType: The Asset:extractableType of the asset

-> Maybe Text

id: The Asset:id of the asset

-> Maybe a

cancellable: An object to allow cancellation of the asset request, or Nothing to ignore

-> Maybe AsyncReadyCallback

callback: A function to call when the initialization is finished

-> m ()

Requests an asset with the given properties asynchronously (see assetRequest). 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 assetRequestFinish method on the given AsyncResult.

Note that the source object passed to the callback will be the Asset corresponding to the request, but it may not have loaded correctly and therefore can not be used as is. Instead, assetRequestFinish 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 MainLoop running under the same MainContext that init was called in. So, if you wish the callback to be invoked outside the default MainContext, you can call mainContextPushThreadDefault in a new thread before calling init.

Example of an asynchronous asset request:

c code

// 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) {
   gst_print ("The file: %s is usable as a GESUriClip",
       ges_asset_get_id (asset));
  } else {
   gst_print ("The file: %s is *not* usable as a GESUriClip 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, NULL,
   (GAsyncReadyCallback) asset_loaded_cb, user_data);

requestFinish

assetRequestFinish

Arguments

:: (HasCallStack, MonadIO m, IsAsyncResult a)

=> a

res: The task result to fetch the asset from

-> m Asset

Returns: The requested asset, or Nothing if an error occurred. (Can throw GError)

Fetches an asset requested by assetRequestAsync, which finalises the request.

setProxy

assetSetProxy

Arguments

:: (HasCallStack, MonadIO m, IsAsset a, IsAsset b)

=> a

asset: The Asset to proxy

-> Maybe b

proxy: A new default proxy for asset

-> m Bool

Returns: True if proxy was successfully set as the default for asset.

Sets the Asset:proxy for the asset.

If proxy is among the existing proxies of the asset (see assetListProxies) it will be moved to become the default proxy. Otherwise, if proxy is not Nothing, 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 assetUnproxy for that).

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

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

unproxy

assetUnproxy

Arguments

:: (HasCallStack, MonadIO m, IsAsset a, IsAsset b)

=> a

asset: The Asset to no longer proxy with proxy

-> b

proxy: An existing proxy of asset

-> m Bool

Returns: True if proxy was successfully removed from asset's proxy list.

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 assetListProxies) will become the default. If there are no other proxies, then the asset will no longer have a default Asset:proxy.

Properties

extractableType

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

constructAssetExtractableType :: (IsAsset o, MonadIO m) => GType -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “extractable-type” property. This is rarely needed directly, but it is used by new.

getAssetExtractableType :: (MonadIO m, IsAsset o) => o -> m GType

Get the value of the “extractable-type” property. When overloading is enabled, this is equivalent to

get asset #extractableType

id

The ID of the asset. This should be unique amongst all assets with the same Asset:extractableType. Depending on the associated Extractable implementation, this id may convey some information about the 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 Asset:extractableType, but you should check the documentation of the extractable type to see whether they differ from the default behaviour.

constructAssetId :: (IsAsset o, MonadIO m) => Text -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “id” property. This is rarely needed directly, but it is used by new.

getAssetId :: (MonadIO m, IsAsset o) => o -> m Text

Get the value of the “id” property. When overloading is enabled, this is equivalent to

get asset #id

proxy

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

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

clearAssetProxy :: (MonadIO m, IsAsset o) => o -> m ()

Set the value of the “proxy” property to Nothing. When overloading is enabled, this is equivalent to

clear #proxy

constructAssetProxy :: (IsAsset o, MonadIO m, IsAsset a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “proxy” property. This is rarely needed directly, but it is used by new.

getAssetProxy :: (MonadIO m, IsAsset o) => o -> m (Maybe Asset)

Get the value of the “proxy” property. When overloading is enabled, this is equivalent to

get asset #proxy

setAssetProxy :: (MonadIO m, IsAsset o, IsAsset a) => o -> a -> m ()

Set the value of the “proxy” property. When overloading is enabled, this is equivalent to

set asset [ #proxy := value ]

proxyTarget

The asset that this asset is a proxy for, or Nothing 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 Asset:proxy, then proxy-target will *still* point to this other asset. So you should check the Asset:proxy property of target-proxy before assuming it is the current default proxy for the target.

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

getAssetProxyTarget :: (MonadIO m, IsAsset o) => o -> m (Maybe Asset)

Get the value of the “proxy-target” property. When overloading is enabled, this is equivalent to

get asset #proxyTarget