gstreamer/docs/design/asset.txt

Assets
~~~~~~~~~

This draft document describes a possible design for asset objects.

The assets should be used in order to instantiate objects of differents
types.

Terminology: A asset is an object from which objects can be extracted.

Summary
~~~~~~~~~

1. Basic ideas
2. Problems
3. Propositions to solve those problems
4. Use-cases
5. API draft
   A. Asset API draft
   B. Source asset API draft
   C. Project asset API draft
   D. Extractable/Asset Interface API draft
   E. Methods that should be added to other classes

1. Basic ideas
~~~~~~~~~~~~~~~

Basically, asset is a way of avoiding duplicating data between object and avoid
processing when the same processing would happen several times for an 2 different
objects of a same type.

    * There will be a listing of avalaible, ready to use assets
    * Asset allow to create some particular types of object that implement the GESExtractable
      interface
    * Assets will hold metadatas
    * Assets can be either, created by the user, or will be created by GES itself
      when initializing, there should be a way to disable that feature on demand.

Some ideas of asset(especially for TimelineSource objects) can be found in docs/random/design.

2. Problems (Not in any particular order)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1) We have avoid to various times the same file on the system
    2) We must be able to query assets by some criteria
        a. By type of TimelineObject that it can produce
        b. By type of supported tracks
        c. Should we have filters by some specific properties of source asset
           - like duration, width, height, etc?
    3) We must be able to get reference to origin asset of any extracted object
    4) We need a way to describe projects
    5) GESAssets can be instantiated asynchronously
    6) The instantiation of a asset can fail
    7) Users need to get informations about the instantiation failures
    8) User should be able to cancel the creation of a GESAsset (especially
       in case of asynchronous Asset creation)

3. Propositions to solve those problems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    1) We should have an interface that needs to be implemented by classes that need to be extractable.
       We can call it GESExtractable. It should be responsible for:
          * letting the user get the Asset from which an extracted object comes from
          * Making it possible to instantiate a GESAsset only from a GType which means that:
              - It needs to contain a reference to a GES_TYPE_ASSET (or subclass) so the proper GESAsset type will be instantiated.
              - It need to contain some mapping between the ID (string) of the asset, and the property of the object that is used as its ID.
                For a property to be usable as an ID for its asset, each objects extracted from a same asset must have the same value for the property
                Examples:
                    GESTimelineFileSource -> URI
                    GESTrackParseLaunchEffect -> bin_description
                    GESProject -> project name / uri of the stored serialized

    2) A list of all available, ready to be used assets should be cached  and
       reused whenever it is possible.
       Basically it will look like:
          GESAsset.id -> asset
       (the ID is computed thanks to the mapping)

    4) To allow users to implement some sort of library (media, effects, transitions...)
       we must be able to query assets by using some criteria,
        e.g. GType of the extractable object, URI, supported track types, etc...

    5) We can instantiate a GESAsset only from a GType, the appropriate checks need
       to be done and it can return subclasses of GESAsset thanks to the
       information included in the GESExtractable interface.

    6) Instanciation can happen asyncronously in some cases. For example, a
       asset that  needs to discover a file to be properly filled needs.

4. Use cases
~~~~~~~~~~~~~
    UC-1. Define media files and discover them
    UC-2. Define project - reference all assets
    UC-3. Define titles
    UC-4. Define operations
        - Transitions - 1 asset per transition type
        - Effects - 1 asset per effects type
        - TextOverlay
    UC-5. Handle metadata
    UC-6. Add operations (only effects?) to a GESTimelineObject
    UC-7. User want to 'invent' a new operation, we need to be able
          to let him define it
    UC-8. The user want to make an object from a GESAsset


5. API Draft
~~~~~~~~~~~~

A. GESExtractable API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

GESExtractable is responsible for telling what GESAsset subclass need to
be instantiated.

/**
 * ges_extractable_object_get_asset:
 * @object: Target object
 * Method to get asset which was used to instaniate specified object
 * Returns: origin asset
 */
GESAsset *
ges_extractable_get_asset(GESExtractable *extractable);

/**
 * ges_extractable_object_set_asset:
 * @object: Target object
 * @asset: (transfer none): The #GESAsset to set
 *
 * Method to set asset which was used to instaniate specified object
 */
void
ges_extractable_set_asset (GESExtractable * self, GESAsset * asset)

/**
 * ges_extractable_get_asset_type:
 * @class: Get the #GType of the GESAsset that should be used to extract
 * the object that implements that #GESExtractable interface
 *
 * Lets user know the type of GESAsset that should be used to extract the
 * object that implement that interface.
 */
GType
ges_extractable_get_asset_type (GESExtractableClass *class)

/**
 * ges_extractable_get_id:
 * @self: The #GESExtractable
 *
 * Returns: The #id of the associated #GESAsset
 */
const gchar *
ges_extractable_get_id (GESExtractable * self)

/**
 * ges_extractable_type_get_parameters_for_id:
 * @type: The #GType implementing #GESExtractable
 * @id: The ID of the Extractable
 * @n_params: (out): Return location for the returned array
 *
 * Returns: (transfer full) (array length=n_params): an array of #GParameter
 * needed to extract the #GESExtractable from a #GESAsset of @id
 */
GParameter *
ges_extractable_type_get_parameters_from_id (GType type, const gchar * id,
    guint * n_params)

/**
 * ges_extractable_type_get_asset_type:
 * @type: The #GType implementing #GESExtractable
 *
 * Get the #GType, subclass of #GES_TYPE_ASSET to instanciate
 * to be able to extract a @type
 *
 * Returns: the #GType to use to create a asset to extract @type
 */
GType
ges_extractable_type_get_asset_type (GType type)

/**
 * ges_extractable_type_check_id:
 * @type: The #GType implementing #GESExtractable
 * @id: The ID to check
 *
 * Check if @id is valid for @type
 *
 * Returns: Return %TRUE if @id is valid, %FALSE otherwise
 */
gchar *
ges_extractable_type_check_id (GType type, const gchar * id)


A. Asset And subclasses API draft
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

a) GESAsset
|  ~~~~~~~~~~~
|
|  Will implement GESMetdata
|
|  Virtual method type:
|  -------------------
|
|  /**
|   * GESAssetCreatedCallback:
|   * @asset: the #newly created #GESAsset or %NULL if something went wrong
|   * @error: The #GError filled if previsouly provided in the constructor or %NULL
|   * @user_data: The user data pointer
|   *
|   * A function that will be called when a #GESAsset is ready to be used.
|   */
|  typedef void (*GESAssetCreatedCallback)(GESAsset *asset, GError *error, gpointer user_data);
|
|
|  Methods prototypes:
|  -------------------
|  /**
|   * ges_asset_request:
|   * @extractable_type: The #GType of the object that can be extracted from the new asset.
|   *    The class must implement the #GESExtractable interface.
|   * @callback: a #GAsyncReadyCallback to call when the initialization is finished
|   * @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
|   * GESTrackParseLaunchEffect, it will be the pipeline description, for a GESTimelineFileSource 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.
|   *
|   * Creates a new #GESAsset asyncronously, @callback will be called when the materail is loaded
|   *
|   * Returns: %TRUE if the asset could be loaded to load %FALSE otherwize
|   */
|   gboolean
|   ges_asset_request (GType extractable_type, GESAssetCreatedCallback callback,
|                     gpointer user_data, const gchar *id);
|
|->b) GESAssetTimelineObject
|  |  ~~~~~~~~~~~~~~~~~~~~~~~~~
|  |  /**
|  |   * ges_asset_timeline_object_get_track_types:
|  |   * @asset: a #GESAssetTimelineObject
|  |   *
|  |   * Method that returns track types that are supported by given asset
|  |   *
|  |   * Returns: Track types that are supported by asset
|  |   */
|  |  GESTrackType
|  |  ges_asset_timeline_object_get_track_types (GESAssetTimelineObject *asset);
|  |
|  |
|  |-> c) GESAssetFileSource
|         ~~~~~~~~~~~~~~~~~~~~~
|      /**
|       * ges_asset_file_source_get_stream_info:
|       * @asset: a #GESAsset of extractable_type GES_TIMELINE_FILE_SOURCE
|       * Method that returns discoverer data of specified asset so user could work with
|       * it directly
|       * Returns: discover info of asset
|       */
|      GstDiscovererStreamInfo *
|      ges_asset_file_source_get_stream_info (GESAssetFileSource *asset);
|
|
|-> d) GESProjectAsset asset API
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    A project is a GESAsset that has GES_TYPE_TIMELINE or subclasses as extractable_type

    FIXME: This special case that should be thought thoroughly.

    /**
     * ges_asset_project_list_assets:
     * @asset: Project asset
     * @type: Type of asset to list
     * Method for listing assets of specified type that are available in
     * particular project.
     *
     * Returns: list of available assets of given type in project
     */
    ges_asset_project_list_assets (GESAsset *project,
                                       GType type)

E. Methods that should be added to other classes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

/**
 * ges_timeline_layer_add_asset:
 *
 * Creates TimelineObject from asset, adds it to layer and
 * returns reference to it.
 *
 * Returns: Created #GESTimelineObject
 */
GESTimelineObject * ges_timeline_layer_add_asset   (GESTimelineLayer *layer,
                                                       GESAssetTimelineObject *asset,
                                                       GstClockTime start,
                                                       GstClockTime inpoint,
                                                       GstClockTime duration,

/**
 * ges_timeline_remove_extracted_from_asset:
 * @timeline: A #GESTimeline from which to remove objects
 * @asset: The #GESAssetTimelineObject to remove from @timeline
 *
 * Removes all asset in @timeline that have been extracted from @asset
 *
 * Returns: %TRUE if everything could be done properly %FALSE otherwize
 */
gboolean ges_timeline_layer_add_asset   (GESTimeline *timeline, GESAsset *asset);

/**
 * ges_timeline_object_add_asset:
 * @object: Target #GESTimelineObject
 * @asset: a #GESAsset that must have a GES_TYPE_TRACK_OPERATION as extractable_type
 * @priority: The priority of the new #GESTrackObject
 *
 * Adds an operation (GESTrackObject(s)) to a GESTimelineObject
 *
 * Returns: (transfer full):The newly created #GESTrackObject.
 */
GESTrackObject
ges_timeline_object_add_asset (GESTimelineObject *object,
                                  GESAsset *asset,
                                  guint32 priority);