rb-metadata

rb-metadata — 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,
                                                         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_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_LAST

invalid field

enum RBMetaDataError

typedef enum
{
	RB_METADATA_ERROR_GNOMEVFS,
	RB_METADATA_ERROR_MISSING_PLUGIN,
	RB_METADATA_ERROR_UNRECOGNIZED,
	RB_METADATA_ERROR_UNSUPPORTED,
	RB_METADATA_ERROR_GENERAL,
	RB_METADATA_ERROR_INTERNAL,
	RB_METADATA_ERROR_NOT_AUDIO,
	RB_METADATA_ERROR_NOT_AUDIO_IGNORE,
	RB_METADATA_ERROR_EMPTY_FILE
} RBMetaDataError;


rb_metadata_new ()

RBMetaData*         rb_metadata_new                     (void);

Returns :

new RBMetaData instance

rb_metadata_get_field_type ()

GType               rb_metadata_get_field_type          (RBMetaDataField field);

field :

a RBMetaDataField

Returns :

the GType of the value for the metadata field

rb_metadata_get_field_name ()

const char*         rb_metadata_get_field_name          (RBMetaDataField field);

field :

a RBMetaDataField

Returns :

the name of the metadata field

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,
                                                         GError **error);

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

md :

a RBMetaData

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