## ClutterMedia

ClutterMedia — An interface for controlling playback of media data

## Synopsis

                        ClutterMedia;
    struct              ClutterMediaIface;
    void                clutter_media_set_uri               (ClutterMedia *media,
                                                             const gchar *uri);
    gchar *             clutter_media_get_uri               (ClutterMedia *media);
    void                clutter_media_set_playing           (ClutterMedia *media,
                                                             gboolean playing);
    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_subtitle_font_name
                                                            (ClutterMedia *media,
                                                             const char *font_name);
    gchar *             clutter_media_get_subtitle_font_name
                                                            (ClutterMedia *media);
    void                clutter_media_set_audio_volume      (ClutterMedia *media,
                                                             gdouble volume);
    gdouble             clutter_media_get_audio_volume      (ClutterMedia *media);
    gboolean            clutter_media_get_can_seek          (ClutterMedia *media);
    gdouble             clutter_media_get_buffer_fill       (ClutterMedia *media);
    gdouble             clutter_media_get_duration          (ClutterMedia *media);
    void                clutter_media_set_filename          (ClutterMedia *media,
                                                             const gchar *filename);

## Object Hierarchy

      GInterface
       +----ClutterMedia

## Prerequisites

ClutterMedia requires GObject.

## Properties

      "audio-volume"             gdouble               : Read / Write
      "buffer-fill"              gdouble               : Read
      "can-seek"                 gboolean              : Read
      "duration"                 gdouble               : Read
      "playing"                  gboolean              : Read / Write
      "progress"                 gdouble               : Read / Write
      "subtitle-font-name"       gchar*                : Read / Write
      "subtitle-uri"             gchar*                : Read / Write
      "uri"                      gchar*                : Read / Write

## Signals

      "eos"                                            : Run Last
      "error"                                          : Run Last

## Description

ClutterMedia is an interface for controlling playback of media sources.

Clutter core does not provide an implementation of this interface, but other integration libraries like Clutter-GStreamer implement it to offer a uniform API for applications.

ClutterMedia is available since Clutter 0.2

## Details

### ClutterMedia

    typedef struct _ClutterMedia ClutterMedia;

ClutterMedia is an opaque structure whose members cannot be directly accessed

Since 0.2

### struct ClutterMediaIface

    struct ClutterMediaIface {
      /* signals */
      void (* eos)   (ClutterMedia *media);
      void (* error) (ClutterMedia *media,
    		  const GError *error);
    };

Interface vtable for ClutterMedia implementations

`eos` () | handler for the "eos" signal
`error` () | handler for the "error" signal

Since 0.2

### clutter_media_set_uri ()

    void                clutter_media_set_uri               (ClutterMedia *media,
                                                             const gchar *uri);

Sets the URI of `media` to `uri`.

`media` : | a ClutterMedia
`uri` : | the URI of the media stream

Since 0.2

### clutter_media_get_uri ()

    gchar *             clutter_media_get_uri               (ClutterMedia *media);

Retrieves the URI from `media`.

`media` : | a ClutterMedia
Returns : | the URI of the media stream. Use `g_free()` to free the returned string

Since 0.2

### clutter_media_set_playing ()

    void                clutter_media_set_playing           (ClutterMedia *media,
                                                             gboolean playing);

Starts or stops playing of `media`. The implementation might be asynchronous, so the way to know whether the actual playing state of the `media` is to use the "notify" signal on the "playing" property and then retrieve the current state with `clutter_media_get_playing()`. ClutterGstVideoTexture in clutter-gst is an example of such an asynchronous implementation.

`media` : | a ClutterMedia
`playing` : | `TRUE` to start playing

Since 0.2

### clutter_media_get_playing ()

    gboolean            clutter_media_get_playing           (ClutterMedia *media);

Retrieves the playing status of `media`.

`media` : | A ClutterMedia object
Returns : | `TRUE` if playing, `FALSE` if stopped.

Since 0.2

### clutter_media_set_progress ()

    void                clutter_media_set_progress          (ClutterMedia *media,
                                                             gdouble progress);

Sets the playback progress of `media`. The `progress` is a normalized value between 0.0 (begin) and 1.0 (end).

`media` : | a ClutterMedia
`progress` : | the progress of the playback, between 0.0 and 1.0

Since 1.0

### clutter_media_get_progress ()

    gdouble             clutter_media_get_progress          (ClutterMedia *media);

Retrieves the playback progress of `media`.

`media` : | a ClutterMedia
Returns : | the playback progress, between 0.0 and 1.0

Since 1.0

### clutter_media_set_subtitle_uri ()

    void                clutter_media_set_subtitle_uri      (ClutterMedia *media,
                                                             const gchar *uri);

Sets the location of a subtitle file to display while playing `media`.

`media` : | a ClutterMedia
`uri` : | the URI of a subtitle file

Since 1.2

### clutter_media_get_subtitle_uri ()

    gchar *             clutter_media_get_subtitle_uri      (ClutterMedia *media);

Retrieves the URI of the subtitle file in use.

`media` : | a ClutterMedia
Returns : | the URI of the subtitle file. Use `g_free()` to free the returned string

Since 1.2

### clutter_media_set_subtitle_font_name ()

    void                clutter_media_set_subtitle_font_name
                                                            (ClutterMedia *media,
                                                             const char *font_name);

Sets the font used by the subtitle renderer. The `font_name` string must be either `NULL`, which means that the default font name of the underlying implementation will be used; or must follow the grammar recognized by `pango_font_description_from_string()` like:

    1

    clutter_media_set_subtitle_font_name (media, "Sans 24pt");

`media` : | a ClutterMedia
`font_name` : | a font name, or `NULL` to set the default font name

Since 1.2

### clutter_media_get_subtitle_font_name ()

    gchar *             clutter_media_get_subtitle_font_name
                                                            (ClutterMedia *media);

Retrieves the font name currently used.

`media` : | a ClutterMedia
Returns : | a string containing the font name. Use `g_free()` to free the returned string

Since 1.2

### clutter_media_set_audio_volume ()

    void                clutter_media_set_audio_volume      (ClutterMedia *media,
                                                             gdouble volume);

Sets the playback volume of `media` to `volume`.

`media` : | a ClutterMedia
`volume` : | the volume as a double between 0.0 and 1.0

Since 1.0

### clutter_media_get_audio_volume ()

    gdouble             clutter_media_get_audio_volume      (ClutterMedia *media);

Retrieves the playback volume of `media`.

`media` : | a ClutterMedia
Returns : | The playback volume between 0.0 and 1.0

Since 1.0

### clutter_media_get_can_seek ()

    gboolean            clutter_media_get_can_seek          (ClutterMedia *media);

Retrieves whether `media` is seekable or not.

`media` : | a ClutterMedia
Returns : | `TRUE` if `media` can seek, `FALSE` otherwise.

Since 0.2

### clutter_media_get_buffer_fill ()

    gdouble             clutter_media_get_buffer_fill       (ClutterMedia *media);

Retrieves the amount of the stream that is buffered.

`media` : | a ClutterMedia
Returns : | the fill level, between 0.0 and 1.0

Since 1.0

### clutter_media_get_duration ()

    gdouble             clutter_media_get_duration          (ClutterMedia *media);

Retrieves the duration of the media stream that `media` represents.

`media` : | a ClutterMedia
Returns : | the duration of the media stream, in seconds

Since 0.2

### clutter_media_set_filename ()

    void                clutter_media_set_filename          (ClutterMedia *media,
                                                             const gchar *filename);

Sets the source of `media` using a file path.

`media` : | a ClutterMedia
`filename` : | A filename

Since 0.2

## Property Details

### The `"audio-volume"` property

      "audio-volume"             gdouble               : Read / Write

The volume of the audio, as a normalized value between 0.0 and 1.0.

Allowed values: [0,1]

Default value: 0.5

Since 1.0

### The `"buffer-fill"` property

      "buffer-fill"              gdouble               : Read

The fill level of the buffer for the current stream, as a value between 0.0 and 1.0.

Allowed values: [0,1]

Default value: 0

Since 1.0

### The `"can-seek"` property

      "can-seek"                 gboolean              : Read

Whether the current stream is seekable.

Default value: FALSE

Since 0.2

### The `"duration"` property

      "duration"                 gdouble               : Read

The duration of the current stream, in seconds

Allowed values: >= 0

Default value: 0

Since 0.2

### The `"playing"` property

      "playing"                  gboolean              : Read / Write

Whether the ClutterMedia actor is playing.

Default value: FALSE

Since 0.2

### The `"progress"` property

      "progress"                 gdouble               : Read / Write

The current progress of the playback, as a normalized value between 0.0 and 1.0.

Allowed values: [0,1]

Default value: 0

Since 1.0

### The `"subtitle-font-name"` property

      "subtitle-font-name"       gchar*                : Read / Write

The font used to display subtitles. The font description has to follow the same grammar as the one recognized by `pango_font_description_from_string()`.

Default value: NULL

Since 1.2

### The `"subtitle-uri"` property

      "subtitle-uri"             gchar*                : Read / Write

The location of a subtitle file, expressed as a valid URI.

Default value: NULL

Since 1.2

### The `"uri"` property

      "uri"                      gchar*                : Read / Write

The location of a media file, expressed as a valid URI.

Default value: NULL

Since 0.2

## Signal Details

### The `"eos"` signal

    void                user_function                      (ClutterMedia *media,
                                                            gpointer      user_data)      : Run Last

The ::eos signal is emitted each time the media stream ends.

`media` : | the ClutterMedia instance that received the signal
`user_data` : | user data set when the signal handler was connected.

Since 0.2

### The `"error"` signal

    void                user_function                      (ClutterMedia *media,
                                                            GError       *error,
                                                            gpointer      user_data)      : Run Last

The ::error signal is emitted each time an error occurred.

`media` : | the ClutterMedia instance that received the signal
`error` : | the GError
`user_data` : | user data set when the signal handler was connected.

Since 0.2