RBMetaData

## RBMetaData RBMetaData — metadata reader and writer interface |

## Synopsis

                        RBMetaData;
                        RBMetaDataClass;
    enum                RBMetaDataField;
    enum                RBMetaDataError;
    RBMetaData *        rb_metadata_new                     (void);
    GType               rb_metadata_get_field_type          (RBMetaDataField field);
    const char *        rb_metadata_get_field_name          (RBMetaDataField field);
    gboolean            rb_metadata_can_save                (RBMetaData *md,
                                                             const char *mimetype);
    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_mime                (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_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

### RBMetaData

    typedef struct _RBMetaData RBMetaData;

### RBMetaDataClass

    typedef struct {
    	GObjectClass parent_class;
    } RBMetaDataClass;

### 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_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_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_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_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_new ()

    RBMetaData *        rb_metadata_new                     (void);

Creates a new metadata backend instance.

Returns : | new RBMetaData instance

### 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_can_save ()

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

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

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

### 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_mime, 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_mime ()

    const char *        rb_metadata_get_mime                (RBMetaData *md);

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

`md` : | a RBMetaData
Returns : | MIME type-ish 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
`plugin_descriptions` : | returns human-readable missing plugin descriptions
Returns : | TRUE if missing plugin information was returned

### 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
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 vaule to set
Returns : | TRUE if the field is valid