## Writing applications with Grilo

This section intends to be a starting point for developers interested in getting started with Grilo, and as such it does not try to be a comprehensive tutorial covering all topics and features of Grilo, instead, this is intends to focus on typical use case scenarios and code examples to put the developer on the right track.

### Basic concepts

#### Understanding Grilo

Grilo provides a high-level API that application developers can use to interact with heterogeneous media providers using an homogeneous language, reducing remarkably the effort required to integrate media content from multiple sources.

This high-level, provider-independent API is then implemented for all the providers supported by Grilo by means of plugins. These plugins encapsulate all the provider-specific details, effectively hiding all the technical tidbits and particularities of specific media providers from application developers.

There are two kinds of plugins in Grilo:

- Media Sources, which provide access to media content that can be browsed or searched.
- Metadata Sources, which provide additional metadata about media content obtained through media sources.

Management of available plugins is done through the Plugin Registry. This object exposes API to load plugins and retrieve available media source and metadata source objects.

Some plugins may require certain configuration information in order to work properly. Examples of configuration information that may be needed include API keys, service credentials, etc. Please check the section Configuring you plugins for more details on this subject.

You can instruct Grilo to load all available plugins via grl_registry_load_all_plugins(). This will look into the default installation directory for the plugins and also the paths included via the environment variable GRL_PLUGIN_PATH. Please check section Running Grilo based programs for more details on this subject.

Users can also load plugins using their plugin identifiers. These plugin identifier strings can be obtained by running the tool 'grl-inspect'.

Users have two options to gain access to the media source and metadata source objects loaded by the plugin registry:

- Call grl_registry_get_sources* or grl_registry_lookup_source . These should be used when plugins have already been loaded.
- By connecting to the source-added signal, that is emitted whenever a new media source or metadata source object is found.

For more information on how to use the plugin registry, please check its API reference or any of the code examples below.

Media source and metadata source objects are the objects application developers will be interacting with for most of their Grilo work. These objects provide developers with a well known interface (API) to interact with media content that is provider-independent. Typically, each media source object provides access to content delivered by one particular media provider.

#### Media Sources

Media Source objects provide access to media content. Application developers would usually interact with these objects issuing Browse, Search or Query operations on them. The purpose of these operations is explained below:

- Search. Instructs the media source to look for media matching specific keywords. Example: YouTube search.
- Browse:. Navigates through a hierarchy of content exposed by the media provider. Example: Filesystem browsing.
- Query: An advanced search mode that uses service-specific commands to exploit features specific to a particular media provider.
- Metadata Obtain (more) metadata information for a particular media resource.
- Store and Remove Push and remove content from the media provider.

#### Metadata Sources

Metadata Source objects provide means to acquire additional metadata that was not provided by the original media source that delivered the media. Application developers would usually interact with metadata sources via Resolve or SetMetadata operations, which are described below:

- Resolve: Acquire additional metadata for a particular media resource.
- SetMetadata: Update metadata information available for a particular media resource.

#### Asynchronous APIs

Most of the APIs exposed by Media Source and Metadata Source objects are asynchronous. The reason for this is that these operations usually involve I/O which would block the user interface if executed synchronously, specially for the more heavy operations like Browse or Search, leading to unresponsive GUIs and bad user experience.

For this reason, most of the APIs in Grilo accept a user callback and user data parameters that are used to hand over the result of the operation to the client asynchronously.

In cases where asynchrony is not needed, for example for programs that do not have a graphical user interface and are designed to run in the background, Grilo also provides synchronous versions of some of the APIs, but for situations other than this, use of the asynchronous APIs is strongly encouraged.

For operations that can produce multiple results, like Browse, Search or Query, callbacks are invoked once per matching result. For operations that are expected to produce a single result, like Metadata or Resolve, callbacks are invoked just once.

In any case, clients should always expect the result callback to be invoked at least once after an asynchronous operation has been issued, even if the operation fails or is cancelled (in which case the error parameter of the callback will be set to a non-NULL value).

#### Operation identifiers

Some Media Source and Metadata Source operations will return an operation identifier that serves various purposes:

- Identify the operation within the framework.
- Match asynchronously results with the issuing operations.
- Provide an operation identifier that can be used to cancel the operation.

For example, issuing an asynchronous Search operation on a Media Source object would synchronously return an operation identifier. The developer can store this identifier and use it to cancel.

Also, if the operation was not cancelled, the results callback will be invoked at least once (actually, for the case of a Browse operation is will be invoked once per matching result) handing the results of the operation to the application. Each time the results callback is invoked, the operation identifier will be provided so that the callback can identify the operation that triggered the result (there can be multiple operations ongoing simultaneously).

#### Media objects

As discussed before, Media Source objects provide means to access media content exposed by media providers through operations like Search, Browse or Query. Media content is represented in Grilo via GrlMedia objects that contain metadata information related with a particular media resource.

There are various subclasses of GrlMedia, which provide specific APIs to get and set metadata associated with specific media types, like video, audio or image resources.

Typically, these GrlMedia objects will be obtained by issuing Search, Browse or Query operations on Media Source objects, which produce these objects as results. Upon reception, clients would usually use the API exposed by these objects to collect the information of interest.

Grilo also supports the concept of media container, represented by the GrlMediaBox subclass. These objects represent categories or folders that contain other media objects (including maybe more GrlMediaBox objects), allowing tree-like hierarchies of content, like the ones would usually traverse during Browse operations.

Please, check the GrlMedia API reference for more information on this subject.

#### Metadata keys

Metadata keys identify pieces of information (metadata). They are often an input parameter for many operations in Grilo, with the purpose of specifying what pieces of information are relevant for a particular operations.

Grilo has a list of predefined supported keys. For each of these keys, Grilo provides definitions (identifiers) that clients can use to refer to specific pieces of information. Some examples are GRL_METADATA_KEY_TITLE or GRL_METADATA_KEY_ARTIST.

For a complete list of all System Keys, please check grl-metadata-key.h.

Some plugins can also introduce additional metadata keys known as User Keys. The difference with the System Keys is that these do not have definitions available, and hence clients must query the plugin registry to know their identifiers first using grl_registry_lookup_metadata_key .

### Typical use cases explained

The following sections will guide the reader through some of the typical use cases of Grilo, using code examples to make the ideas even more clear.

#### Configuring your plugins

For some plugins to work properly, it is required that the user (or application developer) provides certain configuration. For example, some plugins may require a username and a password, others may require an API token to gain access to the underlying media provider.

These configuration options could be mandatory (without them the plugin cannot operate and will fail to load), or optional, in which case they are intended to allow users to tweak certain aspects of how a particular plugin should work.

An example of a mandatory configuration is in the Youtube plugin: in order for it to work a valid API key must be provided. It is the responsibility of the user (or the application developer) to get that key (usually registering in Youtube and applying for an application key) and provide it to the plugin.

In order to know what configuration options are available for a certain plugin, users/developers must check the plugin documentation.

Here is a small program illustrating how to configure a plugin form your application:

            <xi:include></xi:include>

For more information on how to configure plugins please check the GrlConfig API reference.

#### Browsing media content

Here is a small program illustrating how you can browse content from a particular media source (a similar approach can be used for searching content instead of browsing):

            <xi:include></xi:include>

Please notice:

- Finalization of the Browse operation is always indicated by setting the 'remaining' parameter to 0.
- The user callback used to receive the results is guaranteed to be invoked at least once (with remaining set to 0), even if the operation fails or is cancelled (in these cases the error parameter will be set to a non-NULL value).
- Received GrlMedia objects are owned by the application and must be freed when no longer needed.
- If an error occurs, the GError parameter is set in the callback, but this error parameter is owned by Grilo and will be freed immediately after the callback. If you want to keep the error beyond the scope of the callback you must add a reference to it in the callback code.
- When the media source cannot estimate the number of remaining items, remaining is set to GRL_SOURCE_REMAINING_UNKNOWN.

For more information on how to operate media sources please check the GrlMediaSource API reference.

#### Searching media content

Here is a small program illustrating how you can search content by text from a particular media source (Jamendo in this example):

            <xi:include></xi:include>

Please notice that all the considerations remarked for the Browse operations above apply also to Search operations.

For more information on how to operate media sources please check the GrlMediaSource API reference.

#### Handling multi-valued metadata

When working with multimedia content, it can happen that certain attributes of a particular media resource are multi-valued. For example, a particular video resource may have multiple URIs associated, considering different resolutions, streaming protocols and/or formats.

Grilo provides plugin and application developers with means to handle multi-valued properties.

One issue concerning multi-valued properties are their relations with other properties. Following the example of the video resource with multiple URIs, each of these URIs should have its own mime-type associated, as well as its own width and height values. When dealing with multi-valued properties it is necessary to make this relations among keys more explicit.

Grilo provides application and plugin developers with a high-level APIs to handle certain relations among keys consistently. Continuing with the example of the video resource with multiple URIs, there is grl_media_video_add_url_data and grl_media_video_get_url_data_nth to add and retrieve all the metadata associated with a particular instance of the video resource (URI, mime-type, framerate, width and height, etc) in one go.

Grilo allows plugin developers to define their own metadata keys. In this case, the plugin developer must also provide information on the relations that these keys hold with others. In this scenario plugin developers must use GrlRelatedKeys objects to group related keys together.

Here is a small program illustrating how get all available URLs from a video resource, as well the corresponding MIME value for each one. We use GrlRelatedKeys instead of the high-level API from GrlMediaVideo to illustrate how to use it:

            <xi:include></xi:include>

For more information on how to operate with media objects please check the GrlData hierarchy API reference.

#### Efficient metadata resolution

When executing operations that return lists of media items (like Browse or Search) it is convenient to ensure that we do not request metadata that could slow down the operation unless it is really necessary.

A clear example of this situation is the way Youtube video URLs are resolved: a browse operation on Youtube can usually be resolved in a single HTTP query, however, if one wants to obtain the URLs of the videos then for each video in the result set another HTTP request is needed. This would slow down the browse operation remarkably and would spam Youtube with requests to obtain URLs that may not be ever needed. Indeed, a normal player would browse a list of videos and show information useful for the user to select the one he/she is interested in (title, duration, artist, etc), the URL is not interesting at this stage, it is only interesting when the user selected a video to play, and we would be interested only in that single URL and not in all the URLs of the videos we are displaying.

Grilo provides methods to application developers to query the keys (if any) that may have an impact on the performance for a particular source (like the URL in the case of Youtube), but it is usually easier to just use the GRL_RESOLVE_FAST_ONLY flag when issuing Search, Browse or Query operations.

By using this flag, Grilo will resolve only the keys that do not have an impact on performance. If you browse Youtube with this flag Grilo won't request the URL key to the Youtube source. However, if the source could resolve the URL without performance penalties, it would do so normally.

Usually, for operations like Browse or Search that operate with large result sets it is recommended to use GRL_RESOLVE_FAST_ONLY. If you really need to get the metadata you requested for a specific item (for example if you want to play a video from Youtube you really need the URL), then you can safely use the Metadata operation without the GRL_RESOLVE_FAST_ONLY flag, which would only operate on this particular item, reducing the performance penalty and providing a more efficient solution.

The program below demonstrates how this works, it accepts as argument the id of the source we want to operate with, when the source is registered it will issue a search operation requesting only fast keys. When the search callback is invoked we will print both the title information and the URL of the first media that matched the search text.

If we run the program using grl-jamendo as target source, we will see that it retrieves both the title and the URL of the media immediately, however, if we use grl-youtube, it won't and in order to obtain the URL we issue a new Metadata operation, this time without the GRL_RESOLVE_FAST_ONLY flag.

Of course this is a very simple example, in a real application the way this would work is that we would request the URL in a Browse/Search that could return hundreds of results and we may or may not get the URLs depending on the source we are operating with, but in any case we will ensure the operation will run as fast as possible: the user will see the results of the search fast. Then, when the user selects a media item to be played from that result set we would check if we have the URL already (and we will have the URL ready if the source could resolve it fast) in which case we can play the media right away (no time penalty at all from the user point of view). If the URL could not be resolved because it was slow for the source (like in the case of Youtube) then we just have to issue a Metadata operation requesting the URL, but that won't be too bad because we are requesting it only for the item that the user selected, so from the user's perspective the playback will take slightly more to start but would still be an acceptable delay.

            <xi:include></xi:include>