libmediaart Library Reference Manual: Extraction

## Extraction Extraction — Extraction of music and movie art. |

## Functions

GQuark | media_art_error_quark ()
GType | media_art_process_get_type ()
MediaArtProcess * | media_art_process_new ()
gboolean | media_art_process_uri ()
gboolean | media_art_process_file ()
gboolean | media_art_process_buffer ()

## Types and Values

enum | MediaArtType
enum | MediaArtError
enum | MediaArtProcessFlags
struct | MediaArtProcess
struct | MediaArtProcessClass

## Includes

    #include <libmediaart/mediaart.h>

## Description

The libmediaart library supports taking image data that you have extracted from a media file and saving it into the media art cache, so that future applications can display the media art without having to extract the image again. This is done using the `media_art_process_file()` or `media_art_process_buffer()` functions.

Extracting new media art from a file needs to be done by your application. Usually, when an application loads a media file any embedded images will be made available as a side effect. For example, if you are using GStreamer any images will be returned through the GstTagList interface as `GST_TAG_IMAGE` tags.

The media art cache requires that all images are saved as 'application/jpeg' files. Embedded images can be in several formats, and `media_art_process_file()` and `media_art_process_buffer()` functions will convert the supplied image data into the correct format if necessary. There are multiple backends that can be used for this, and you can choose which is used at build time using the library's 'configure' script.

If there is no embedded media art in a file, `media_art_process_file()` and `media_art_process_buffer()` functions will look in the directory that contains the media file for likely media art using a simple heuristic.

## Functions

### media_art_error_quark ()

    GQuark
    media_art_error_quark (void);

#### Returns

the GQuark used to identify media art errors in GError structures.

Since 0.2.0

### media_art_process_get_type ()

    GType
    media_art_process_get_type (void);

#### Returns

### media_art_process_new ()

    MediaArtProcess *
    media_art_process_new (GError **error);

Initialize a GObject for processing and extracting media art.

This function initializes cache hash tables, backend plugins, storage modules used for removable devices and a connection to D-Bus.

#### Parameters

error | Pointer to potential GLib / MediaArt error, or `NULL` |

#### Returns

A new MediaArtProcess object on success or `NULL` if `error` is set. This object must be freed using `g_object_unref()`.

Since 0.5.0

### media_art_process_uri ()

    gboolean
    media_art_process_uri (MediaArtProcess *process,
                           MediaArtType type,
                           MediaArtProcessFlags flags,
                           const gchar *uri,
                           const gchar *artist,
                           const gchar *title,
                           GError **error);

This function calls `media_art_process_file()`, but takes the `uri` as a string rather than a GFile object. Either `artist` OR `title` can be `NULL`, but they can not both be `NULL`.

#### Parameters

process | Media art process object |
type | The type of media that contained the image data |
flags | How the media art is processed |
uri | URI of the media file that contained the data |
artist | The artist name `uri` or `NULL`. | [allow-none]
title | The title for `uri` or `NULL`. | [allow-none]
error | Pointer to potential GLib / MediaArt error, or `NULL` |

#### Returns

`TRUE` if `uri` could be processed or `FALSE` if `error` is set.

Since 0.5.0

### media_art_process_file ()

    gboolean
    media_art_process_file (MediaArtProcess *process,
                            MediaArtType type,
                            MediaArtProcessFlags flags,
                            GFile *file,
                            const gchar *artist,
                            const gchar *title,
                            GError **error);

Process `file` and check if media art exists and if it is up to date with `artist` and `title` provided. Either `artist` OR `title` can be `NULL`, but they can not both be `NULL`.

NOTE: This function MAY retrieve media art for `artist` and `title` combinations. It is not guaranteed and depends on download services available over DBus at the time.

In cases where download is unavailable, `media_art_process_file()` will only try to procure a cache for possible media art found in directories surrounding the location of `file` . If a buffer or memory chunk needs to be saved to disk which has been retrieved from an MP3 (for example), you should use `media_art_process_buffer()`.

The modification time (mtime) of `file` is checked against the cached stored for `artist` and `title` . If the cache is old or doesn't exist, it will be updated. What this actually does is update the mtime of the cache (a symlink) on the disk.

If there is no actual media art stored locally (for example, it's stored in a directory on a removable device), it is copied locally (usually to an XDG cache directory).

If `file` is on a removable filesystem, the media art file will be saved in a cache on the removable file system rather than on the host machine.

#### Parameters

process | Media art process object |
type | The type of media |
flags | The options given for how to process the media art |
file | File to be processed |
artist | The artist name `file` or `NULL`. | [allow-none]
title | The title for `file` or `NULL`. | [allow-none]
error | Pointer to potential GLib / MediaArt error, or `NULL` |

#### Returns

`TRUE` if `file` could be processed or `FALSE` if `error` is set.

Since 0.3.0

### media_art_process_buffer ()

    gboolean
    media_art_process_buffer (MediaArtProcess *process,
                              MediaArtType type,
                              MediaArtProcessFlags flags,
                              GFile *related_file,
                              const guchar *buffer,
                              gsize len,
                              const gchar *mime,
                              const gchar *artist,
                              const gchar *title,
                              GError **error);

Processes a memory buffer represented by `buffer` and `len` . If you have extracted any embedded media art and passed this in as `buffer` , the image data will be converted to the correct format and saved in the media art cache.

Either `artist` OR `title` can be `NULL`, but they can not both be `NULL`.

If `file` is on a removable filesystem, the media art file will be saved in a cache on the removable file system rather than on the host machine.

#### Parameters

process | Media art process object |
type | The type of media |
flags | The options given for how to process the media art |
related_file | File related to the media art |
buffer | a buffer containing `file` data, or `NULL`. | [array length=len][allow-none]
len | length of `buffer` , or 0 |
mime | MIME type of `buffer` , or `NULL` |
artist | The artist name `file` or `NULL`. | [allow-none]
title | The title for `file` or `NULL`. | [allow-none]
error | Pointer to potential GLib / MediaArt error, or `NULL` |

#### Returns

`TRUE` if `file` could be processed or `FALSE` if `error` is set.

Since 0.5.0

## Types and Values

### enum MediaArtType

This type categorized the type of media art we're dealing with.

#### Members

MEDIA_ART_NONE | No media art is available |
MEDIA_ART_ALBUM | Media art is an album |
MEDIA_ART_VIDEO | Media art is a movie or video |

### enum MediaArtError

Enumeration values used in errors returned by the MediaArtError API.

#### Members

MEDIA_ART_ERROR_NO_STORAGE | Storage information is unknown, we have no knowledge about removable media. |
MEDIA_ART_ERROR_NO_TITLE | Title is required, but was not provided, or was empty. |
MEDIA_ART_ERROR_SYMLINK_FAILED | A call to `symlink()` failed resulting in the incorrect storage of media art. |
MEDIA_ART_ERROR_RENAME_FAILED | File could not be renamed. |

Since 0.2.0

### enum MediaArtProcessFlags

This type categorized the flags used when processing media art.

#### Members

MEDIA_ART_PROCESS_FLAGS_NONE | Normal operation. |
MEDIA_ART_PROCESS_FLAGS_FORCE | Force media art to be re-saved to disk even if it already exists and the related file or URI has the same modified time (mtime). |

Since 0.3.0

### struct MediaArtProcess

    struct MediaArtProcess {
    	GObject parent;
    };

A class implementation for processing and extracting media art.

#### Members

GObject `parent`; | parent object |

### struct MediaArtProcessClass

    struct MediaArtProcessClass {
    	GObjectClass parent;
    };

Prototype for the class.

#### Members

GObjectClass `parent`; | parent object class |