[media] Add an API to play a subtitle file along with the media

Allow the user of the ClutterMedia interface to specify an external (as
in not multiplexed with the audio/video streams) location of a subtitle
stream.

clutter/clutter-media.c

@@ -109,6 +109,20 @@ clutter_media_base_init (gpointer g_iface)
                                    CLUTTER_PARAM_READWRITE);
       g_object_interface_install_property (g_iface, pspec);
 
+      /**
+       * ClutterMedia:subtitle-uri:
+       *
+       * The location of a subtitle file, expressed as a valid URI.
+       *
+       * Since: 1.2
+       */
+      pspec = g_param_spec_string ("subtitle-uri",
+                                   "Subtitle URI",
+                                   "URI of a subtitle file",
+                                   NULL,
+                                   CLUTTER_PARAM_READWRITE);
+      g_object_interface_install_property (g_iface, pspec);
+
       /**
        * ClutterMedia:audio-volume:
        *
@@ -348,6 +362,47 @@ clutter_media_get_progress (ClutterMedia *media)
   return retval;
 }
 
+/**
+ * clutter_media_set_subtitle_uri:
+ * @media: a #ClutterMedia
+ * @uri: the URI of a subtitle file
+ *
+ * Sets the location of a subtitle file to display while playing @media.
+ *
+ * Since: 1.2
+ */
+void
+clutter_media_set_subtitle_uri (ClutterMedia *media,
+                                 const char   *uri)
+{
+  g_return_if_fail (CLUTTER_IS_MEDIA (media));
+
+  g_object_set (G_OBJECT (media), "subtitle-uri", uri, NULL);
+}
+
+/**
+ * clutter_media_get_subtitle_uri:
+ * @media: a #ClutterMedia
+ *
+ * Retrieves the URI of the subtitle file in use.
+ *
+ * Return value: the URI of the subtitle file. Use g_free()
+ *   to free the returned string
+ *
+ * Since: 1.2
+ */
+gchar *
+clutter_media_get_subtitle_uri (ClutterMedia *media)
+{
+  gchar *retval = NULL;
+
+  g_return_val_if_fail (CLUTTER_IS_MEDIA(media), NULL);
+
+  g_object_get (G_OBJECT (media), "subtitle-uri", &retval, NULL);
+
+  return retval;
+}
+
 /**
  * clutter_media_set_audio_volume:
  * @media: a #ClutterMedia

clutter/clutter-media.h

@@ -76,6 +76,9 @@ gboolean clutter_media_get_playing      (ClutterMedia *media);
 void     clutter_media_set_progress     (ClutterMedia *media,
                                          gdouble       progress);
 gdouble  clutter_media_get_progress     (ClutterMedia *media);
+void     clutter_media_set_subtitle_uri (ClutterMedia *media,
+                                         const gchar  *uri);
+gchar *  clutter_media_get_subtitle_uri (ClutterMedia *media);
 void     clutter_media_set_audio_volume (ClutterMedia *media,
                                          gdouble       volume);
 gdouble  clutter_media_get_audio_volume (ClutterMedia *media);

doc/reference/clutter/clutter-sections.txt

@@ -9,6 +9,8 @@ clutter_media_set_playing
 clutter_media_get_playing
 clutter_media_set_progress
 clutter_media_get_progress
+clutter_media_set_subtitles_uri
+clutter_media_get_subtitles_uri
 clutter_media_set_audio_volume
 clutter_media_get_audio_volume
 clutter_media_get_can_seek