## RBMetaData

RBMetaData — metadata reader and writer interface

## Synopsis

    enum                RBMetaDataField;
    enum                RBMetaDataError;
    GQuark              rb_metadata_error_quark             (void);
    struct              RBMetaData;
    struct              RBMetaDataClass;
    GType               rb_metadata_get_field_type          (RBMetaDataField field);
    const char *        rb_metadata_get_field_name          (RBMetaDataField field);
    RBMetaData *        rb_metadata_new                     (void);
    gboolean            rb_metadata_can_save                (RBMetaData *md,
                                                             const char *media_type);
    char **             rb_metadata_get_saveable_types      (RBMetaData *md);
    void                rb_metadata_reset                   (RBMetaData *md);
    void                rb_metadata_load                    (RBMetaData *md,
                                                             const char *uri,
                                                             GError **error);
    void                rb_metadata_save                    (RBMetaData *md,
                                                             const char *uri,
                                                             GError **error);
    const char *        rb_metadata_get_media_type          (RBMetaData *md);
    gboolean            rb_metadata_has_missing_plugins     (RBMetaData *md);
    gboolean            rb_metadata_get_missing_plugins     (RBMetaData *md,
                                                             char ***missing_plugins,
                                                             char ***plugin_descriptions);
    gboolean            rb_metadata_has_audio               (RBMetaData *md);
    gboolean            rb_metadata_has_video               (RBMetaData *md);
    gboolean            rb_metadata_has_other_data          (RBMetaData *md);
    gboolean            rb_metadata_get                     (RBMetaData *md,
                                                             RBMetaDataField field,
                                                             GValue *val);
    gboolean            rb_metadata_set                     (RBMetaData *md,
                                                             RBMetaDataField field,
                                                             const GValue *val);

## Object Hierarchy

      GObject
       +----RBMetaData

## Description

Provides a simple synchronous interface for metadata extraction and updating.

## Details

### enum RBMetaDataField

    typedef enum {
    	RB_METADATA_FIELD_TITLE,                   /* string */
    	RB_METADATA_FIELD_ARTIST,                  /* string */
    	RB_METADATA_FIELD_ALBUM,                   /* string */
    	RB_METADATA_FIELD_DATE,                    /* ulong */
    	RB_METADATA_FIELD_GENRE,                   /* string */
    	RB_METADATA_FIELD_COMMENT,                 /* string */
    	RB_METADATA_FIELD_TRACK_NUMBER,            /* ulong */
    	RB_METADATA_FIELD_MAX_TRACK_NUMBER,        /* ulong */
    	RB_METADATA_FIELD_DISC_NUMBER,             /* ulong */
    	RB_METADATA_FIELD_MAX_DISC_NUMBER,         /* ulong */
    	RB_METADATA_FIELD_DESCRIPTION,             /* string */
    	RB_METADATA_FIELD_VERSION,                 /* string */
    	RB_METADATA_FIELD_ISRC,                    /* string */
    	RB_METADATA_FIELD_ORGANIZATION,            /* string */
    	RB_METADATA_FIELD_COPYRIGHT,               /* string */
    	RB_METADATA_FIELD_CONTACT,                 /* string */
    	RB_METADATA_FIELD_LICENSE,                 /* string */
    	RB_METADATA_FIELD_PERFORMER,               /* string */
    	RB_METADATA_FIELD_DURATION,                /* ulong */
    	RB_METADATA_FIELD_CODEC,		   /* string */
    	RB_METADATA_FIELD_BITRATE,                 /* ulong */
    	RB_METADATA_FIELD_TRACK_GAIN,		   /* double */
    	RB_METADATA_FIELD_TRACK_PEAK,		   /* double */
    	RB_METADATA_FIELD_ALBUM_GAIN,		   /* double */
    	RB_METADATA_FIELD_ALBUM_PEAK,		   /* double */
    	RB_METADATA_FIELD_LANGUAGE_CODE,	   /* string */
    	RB_METADATA_FIELD_BPM,			   /* double */
    	RB_METADATA_FIELD_MUSICBRAINZ_TRACKID,     /* string */
    	RB_METADATA_FIELD_MUSICBRAINZ_ARTISTID,    /* string */
    	RB_METADATA_FIELD_MUSICBRAINZ_ALBUMID,     /* string */
    	RB_METADATA_FIELD_MUSICBRAINZ_ALBUMARTISTID,   /* string */
    	RB_METADATA_FIELD_ARTIST_SORTNAME,         /* string */
    	RB_METADATA_FIELD_ALBUM_SORTNAME,          /* string */
    	RB_METADATA_FIELD_ALBUM_ARTIST,            /* string */
    	RB_METADATA_FIELD_ALBUM_ARTIST_SORTNAME,   /* string */
    	RB_METADATA_FIELD_COMPOSER,            /* string */
    	RB_METADATA_FIELD_COMPOSER_SORTNAME,   /* string */

    	RB_METADATA_FIELD_LAST			   /* nothing */
    } RBMetaDataField;

Metadata fields that can be read from and written to files.

`RB_METADATA_FIELD_TITLE` | Title of the recording
`RB_METADATA_FIELD_ARTIST` | Person(s) responsible for the recording
`RB_METADATA_FIELD_ALBUM` | Album containing the recording
`RB_METADATA_FIELD_DATE` | Release date of the album
`RB_METADATA_FIELD_GENRE` | Genre of the recording
`RB_METADATA_FIELD_COMMENT` | Free form comment on the recording
`RB_METADATA_FIELD_TRACK_NUMBER` | Track number inside a collection
`RB_METADATA_FIELD_MAX_TRACK_NUMBER` | Count of tracks inside the collection
`RB_METADATA_FIELD_DISC_NUMBER` | Disc number inside a collection
`RB_METADATA_FIELD_MAX_DISC_NUMBER` | Count of discs inside the collection
`RB_METADATA_FIELD_DESCRIPTION` | Short text describing the recording
`RB_METADATA_FIELD_VERSION` | Version of the recording
`RB_METADATA_FIELD_ISRC` | International Standard Recording Code
`RB_METADATA_FIELD_ORGANIZATION` | Organization responsible for the recording
`RB_METADATA_FIELD_COPYRIGHT` | Copyright notice on the recording
`RB_METADATA_FIELD_CONTACT` | Contact information
`RB_METADATA_FIELD_LICENSE` | License of the recording
`RB_METADATA_FIELD_PERFORMER` | Person(s) performing in the recording
`RB_METADATA_FIELD_DURATION` | Duration of the recording
`RB_METADATA_FIELD_CODEC` | Codec used to store the recording
`RB_METADATA_FIELD_BITRATE` | Exact or average encoding bitrate in bits/s
`RB_METADATA_FIELD_TRACK_GAIN` | Track gain in dB for replaygain
`RB_METADATA_FIELD_TRACK_PEAK` | Track peak volume level
`RB_METADATA_FIELD_ALBUM_GAIN` | Album gain in dB for replaygain
`RB_METADATA_FIELD_ALBUM_PEAK` | Album peak volume level
`RB_METADATA_FIELD_LANGUAGE_CODE` | Language code (ISO-639-1)
`RB_METADATA_FIELD_BPM` | Beats Per Minute
`RB_METADATA_FIELD_MUSICBRAINZ_TRACKID` | MusicBrainz track ID
`RB_METADATA_FIELD_MUSICBRAINZ_ARTISTID` | MusicBrainz artist ID
`RB_METADATA_FIELD_MUSICBRAINZ_ALBUMID` | MusicBrainz album ID
`RB_METADATA_FIELD_MUSICBRAINZ_ALBUMARTISTID` | MusicBrainz album artist ID
`RB_METADATA_FIELD_ARTIST_SORTNAME` | Person(s) responsible for the recording, as used for sorting
`RB_METADATA_FIELD_ALBUM_SORTNAME` | Album containing the recording, as used for sorting
`RB_METADATA_FIELD_ALBUM_ARTIST` | The artist of the entire album
`RB_METADATA_FIELD_ALBUM_ARTIST_SORTNAME` | The artist of the entire album, as it should be sorted
`RB_METADATA_FIELD_COMPOSER` | The composer of the recording
`RB_METADATA_FIELD_COMPOSER_SORTNAME` | The composer of the recording, as it should be sorted
`RB_METADATA_FIELD_LAST` | invalid field

### enum RBMetaDataError

    typedef enum {
    	RB_METADATA_ERROR_IO,
    	RB_METADATA_ERROR_MISSING_PLUGIN,
    	RB_METADATA_ERROR_UNRECOGNIZED,
    	RB_METADATA_ERROR_UNSUPPORTED,
    	RB_METADATA_ERROR_GENERAL,
    	RB_METADATA_ERROR_INTERNAL,
    	RB_METADATA_ERROR_EMPTY_FILE
    } RBMetaDataError;

`RB_METADATA_ERROR_IO` |
`RB_METADATA_ERROR_MISSING_PLUGIN` |
`RB_METADATA_ERROR_UNRECOGNIZED` |
`RB_METADATA_ERROR_UNSUPPORTED` |
`RB_METADATA_ERROR_GENERAL` |
`RB_METADATA_ERROR_INTERNAL` |
`RB_METADATA_ERROR_EMPTY_FILE` |

### rb_metadata_error_quark ()

    GQuark              rb_metadata_error_quark             (void);

### struct RBMetaData

    struct RBMetaData;

### struct RBMetaDataClass

    struct RBMetaDataClass {
    	GObjectClass parent_class;
    };

### rb_metadata_get_field_type ()

    GType               rb_metadata_get_field_type          (RBMetaDataField field);

Returns the GType of the value for a metadata field.

`field` : | a RBMetaDataField
Returns : | value type

### rb_metadata_get_field_name ()

    const char *        rb_metadata_get_field_name          (RBMetaDataField field);

Returns the name of a metadata field.

`field` : | a RBMetaDataField
Returns : | field name

### rb_metadata_new ()

    RBMetaData *        rb_metadata_new                     (void);

Creates a new metadata backend instance.

Returns : | new RBMetaData instance

### rb_metadata_can_save ()

    gboolean            rb_metadata_can_save                (RBMetaData *md,
                                                             const char *media_type);

Checks if the metadata writer is capable of updating file metadata for a given media type.

`md` : | a RBMetaData
`media_type` : | the media type string to check
Returns : | TRUE if the file metadata for the given media type can be updated

### rb_metadata_get_saveable_types ()

    char **             rb_metadata_get_saveable_types      (RBMetaData *md);

Constructs a list of the media types for which the metadata backend implements tag saving.

`md` : | a RBMetaData
Returns : | a NULL-terminated array of media type strings. Use g_strfreev to free it. [transfer full][array zero-terminated=1]

### rb_metadata_reset ()

    void                rb_metadata_reset                   (RBMetaData *md);

Resets the state of the metadata interface. Call this before setting tags to be written to a file.

`md` : | a RBMetaData

### rb_metadata_load ()

    void                rb_metadata_load                    (RBMetaData *md,
                                                             const char *uri,
                                                             GError **error);

Reads metadata information from the specified URI. Once this has returned successfully (with *error == NULL), rb_metadata_get, rb_metadata_get_media_type, rb_metadata_has_missing_plugins, and rb_metadata_get_missing_plugins can usefully be called.

`md` : | a RBMetaData
`uri` : | URI from which to load metadata
`error` : | returns error information

### rb_metadata_save ()

    void                rb_metadata_save                    (RBMetaData *md,
                                                             const char *uri,
                                                             GError **error);

Saves all metadata changes made with rb_metadata_set to the target URI.

`md` : | a RBMetaData
`uri` : | the target URI
`error` : | returns error information

### rb_metadata_get_media_type ()

    const char *        rb_metadata_get_media_type          (RBMetaData *md);

Returns the type of the file from which metadata was read. This may look like a MIME type, but it isn't.

`md` : | a RBMetaData
Returns : | media type string

### rb_metadata_has_missing_plugins ()

    gboolean            rb_metadata_has_missing_plugins     (RBMetaData *md);

If the metadata reader could not decode the file it was asked to because one or more media framework plugins (specifically, for the existing implementations, GStreamer plugins) required are missing, this will return TRUE.

`md` : | a RBMetaData
Returns : | TRUE if required plugins are missing

### rb_metadata_get_missing_plugins ()

    gboolean            rb_metadata_get_missing_plugins     (RBMetaData *md,
                                                             char ***missing_plugins,
                                                             char ***plugin_descriptions);

This function returns the information used to request automatic installation of media framework plugins required to decode the target URI. Use `g_strfreev()` to free the returned information arrays.

`md` : | a RBMetaData
`missing_plugins` : | returns machine-readable missing plugin information. [out][array zero-terminated=1]
`plugin_descriptions` : | returns human-readable missing plugin descriptions. [out][array zero-terminated=1]
Returns : | TRUE if missing plugin information was returned

### rb_metadata_has_audio ()

    gboolean            rb_metadata_has_audio               (RBMetaData *md);

### rb_metadata_has_video ()

    gboolean            rb_metadata_has_video               (RBMetaData *md);

### rb_metadata_has_other_data ()

    gboolean            rb_metadata_has_other_data          (RBMetaData *md);

### rb_metadata_get ()

    gboolean            rb_metadata_get                     (RBMetaData *md,
                                                             RBMetaDataField field,
                                                             GValue *val);

Retrieves the value of a metadata field extracted from the target URI. If the target URI contained no value for the field, returns FALSE.

`md` : | a RBMetaData
`field` : | the RBMetaDataField to retrieve
`val` : | returns the field value. [out caller-allocates][transfer full]
Returns : | TRUE if a value was returned

### rb_metadata_set ()

    gboolean            rb_metadata_set                     (RBMetaData *md,
                                                             RBMetaDataField field,
                                                             const GValue *val);

Sets a metadata field value. The value is only stored inside the RBMetaData object until rb_metadata_save is called.

`md` : | a RBMetaData
`field` : | the RBMetaDataField to set
`val` : | the value to set
Returns : | TRUE if the field is valid