Assigning media to a renderer

In order to play content in a renderer, a playlist should be created and assigned to it. For this purpose developers have to use mafw_renderer_assign_playlist. Once a playlist has been assigned to the renderer the user may choose to start playback right away (starting from the first item in the playlist) or choose a specific item to start from. For the latter case, the renderer offers the methods mafw_renderer_next, mafw_renderer_previous and mafw_renderer_goto_index, that allow the user to select the next and previous items to the one currently selected or move directly to a particular item in the playlist. Also, the currently selected media may change due to other factors, for example, when playback of the current item in the playlist finishes the renderer will move to the next automatically, it might also happen in the case of errors that do not allow to play the current item, in this scenario the renderer may choose to automatically move to the next item in the playlist too.

No matter the reason that has triggered a change in the current media selected in the renderer, it will notify the application about the change by emitting a "media-changed" signal. Application developers should connect to this signal to update the application accordingly whenever new media is selected in the renderer. It is also possible to query a renderer about its current media by using mafw_renderer_get_status.

Here is a small code snippet illustrating this:

static void
media_changed_cb(MafwRenderer *renderer, gint index, gchar *object_id,
                 gpointer user_data)
{
        if (index >= 0) {
                /* Update UI: select item at position 'index' */
        } else {
               /* Playlist playback interrupted, maybe inform the user
                  about this and then wait until it is resumed, then we
                  will get a new media-changed signal */
        }
}

static void
assign_playlist_cb(MafwRenderer *renderer, gpointer user_data,
                   const GError *error)
{
        if (error != NULL) {
                /* error management code here */
        }
}

static void
assign_playlist(MafwRenderer *renderer, MafwPlaylist *playlist)
{
        g_signal_connect(renderer, "media-changed",
                         G_CALLBACK(media_changed_cb), NULL);

        mafw_renderer_assign_playlist(renderer, playlist,
                                      assign_playlist_cb, NULL);
}

In the code above, the "media-changed" handler checks if the index is positive, if that is the case it could now use this information to update the application, ensuring that the user knows what item is currently selected in the renderer. This index parameter can be negative, this happens when the playlist playback has been interrupted. This may happen, for example, if mafw_renderer_play_object was invoked, which puts off playlist playback to play another individual item, resuming playlist playback when finished.