Rhythmbox Development Reference Manual: RBMetaData

## RBMetaData RBMetaData — metadata reader and writer interface |

## Functions

GQuark | rb_metadata_error_quark ()
GType | rb_metadata_get_field_type ()
const char * | rb_metadata_get_field_name ()
RBMetaData * | rb_metadata_new ()
gboolean | rb_metadata_can_save ()
char ** | rb_metadata_get_saveable_types ()
void | rb_metadata_reset ()
void | rb_metadata_load ()
void | rb_metadata_save ()
const char * | rb_metadata_get_media_type ()
gboolean | rb_metadata_has_missing_plugins ()
gboolean | rb_metadata_get_missing_plugins ()
gboolean | rb_metadata_has_audio ()
gboolean | rb_metadata_has_video ()
gboolean | rb_metadata_has_other_data ()
gboolean | rb_metadata_get ()
gboolean | rb_metadata_set ()

## Types and Values

enum | RBMetaDataField
enum | RBMetaDataError
struct | RBMetaData
struct | RBMetaDataClass

## Object Hierarchy

        GObject
        ╰── RBMetaData

## Description

Provides a simple synchronous interface for metadata extraction and updating.

## Functions

### rb_metadata_error_quark ()

    GQuark
    rb_metadata_error_quark (void);

#### Returns

### rb_metadata_get_field_type ()

    GType
    rb_metadata_get_field_type (RBMetaDataField field);

Returns the GType of the value for a metadata field.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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);

#### Returns

### rb_metadata_has_video ()

    gboolean
    rb_metadata_has_video (RBMetaData *md);

#### Returns

### rb_metadata_has_other_data ()

    gboolean
    rb_metadata_has_other_data (RBMetaData *md);

#### Returns

### 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.

#### Parameters

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.

#### Parameters

md | a RBMetaData |
field | the RBMetaDataField to set |
val | the value to set |

#### Returns

TRUE if the field is valid

## Types and Values

### enum RBMetaDataField

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

#### Members

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

#### Members

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 |  |

### struct RBMetaData

    struct RBMetaData;

### struct RBMetaDataClass

    struct RBMetaDataClass {
    	GObjectClass parent_class;
    };