## Extraction

Extraction — Extraction of music and movie art.

## Functions

MediaArtProcess * | media_art_process_new ()
gboolean | media_art_process_uri ()
void | media_art_process_uri_async ()
gboolean | media_art_process_uri_finish ()
gboolean | media_art_process_file ()
void | media_art_process_file_async ()
gboolean | media_art_process_file_finish ()
gboolean | media_art_process_buffer ()
void | media_art_process_buffer_async ()
gboolean | media_art_process_buffer_finish ()
GQuark | media_art_error_quark ()

## Types and Values

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

## Object Hierarchy

        GObject
        ╰── MediaArtProcess

## Implemented Interfaces

MediaArtProcess implements GInitable.

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

    MediaArtProcess *
    media_art_process_new (GError **error);

Initialize a GObject for processing and extracting media art.

This function initializes cache hash tables and backend plugins,

#### 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,
                           GCancellable *cancellable,
                           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]
cancellable | optional GCancellable object, `NULL` to ignore. | [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_uri_async ()

    void
    media_art_process_uri_async (MediaArtProcess *process,
                                 MediaArtType type,
                                 MediaArtProcessFlags flags,
                                 const gchar *uri,
                                 const gchar *artist,
                                 const gchar *title,
                                 gint io_priority,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

Processes media art. Precisely the same operation as `media_art_process_uri()` is performing, but asynchronously.

When all i/o for the operation is finished the `callback` will be called.

In case of a partial error the callback will be called with any succeeding items and no error, and on the next request the error will be reported. If a request is cancelled the callback will be called with `G_IO_ERROR_CANCELLED`.

During an async request no other sync and async calls are allowed, and will result in `G_IO_ERROR_PENDING` errors.

Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`.

#### Parameters

process | Media art process object |
type | The type of media |
flags | The options given for how to process the media art |
uri | A string representing a URI to be processed |
artist | The artist name `file` or `NULL`. | [allow-none]
title | The title for `file` or `NULL`. | [allow-none]
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 0.7.0

### media_art_process_uri_finish ()

    gboolean
    media_art_process_uri_finish (MediaArtProcess *process,
                                  GAsyncResult *result,
                                  GError **error);

Finishes the asynchronous operation started with `media_art_process_file_async()`.

#### Parameters

process | the MediaArtProcess |
result | a GAsyncResult. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` on success, otherwise `FALSE` when `error` will be set.

Since: 0.7.0

### media_art_process_file ()

    gboolean
    media_art_process_file (MediaArtProcess *process,
                            MediaArtType type,
                            MediaArtProcessFlags flags,
                            GFile *file,
                            const gchar *artist,
                            const gchar *title,
                            GCancellable *cancellable,
                            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]
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

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

Since: 0.3.0

### media_art_process_file_async ()

    void
    media_art_process_file_async (MediaArtProcess *process,
                                  MediaArtType type,
                                  MediaArtProcessFlags flags,
                                  GFile *file,
                                  const gchar *artist,
                                  const gchar *title,
                                  gint io_priority,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Processes media art. Precisely the same operation as `media_art_process_file()` is performing, but asynchronously.

When all i/o for the operation is finished the `callback` will be called.

In case of a partial error the callback will be called with any succeeding items and no error, and on the next request the error will be reported. If a request is cancelled the callback will be called with `G_IO_ERROR_CANCELLED`.

During an async request no other sync and async calls are allowed, and will result in `G_IO_ERROR_PENDING` errors.

Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`.

#### 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]
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 0.7.0

### media_art_process_file_finish ()

    gboolean
    media_art_process_file_finish (MediaArtProcess *process,
                                   GAsyncResult *result,
                                   GError **error);

Finishes the asynchronous operation started with `media_art_process_file_async()`.

#### Parameters

process | the MediaArtProcess |
result | a GAsyncResult. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` on success, otherwise `FALSE` when `error` will be set.

Since: 0.7.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,
                              GCancellable *cancellable,
                              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`. | [allow-none]
artist | The artist name `file` or `NULL`. | [allow-none]
title | The title for `file` or `NULL`. | [allow-none]
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

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

Since: 0.5.0

### media_art_process_buffer_async ()

    void
    media_art_process_buffer_async (MediaArtProcess *process,
                                    MediaArtType type,
                                    MediaArtProcessFlags flags,
                                    GFile *related_file,
                                    const guchar *buffer,
                                    gsize len,
                                    const gchar *mime,
                                    const gchar *artist,
                                    const gchar *title,
                                    gint io_priority,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Processes media art. Precisely the same operation as `media_art_process_buffer()` is performing, but asynchronously.

When all i/o for the operation is finished the `callback` will be called.

In case of a partial error the callback will be called with any succeeding items and no error, and on the next request the error will be reported. If a request is cancelled the callback will be called with `G_IO_ERROR_CANCELLED`.

Dbufferng an async request no other sync and async calls are allowed, and will result in `G_IO_ERROR_PENDING` errors.

Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is `G_PRIORITY_DEFAULT`.

#### 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]
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 0.7.0

### media_art_process_buffer_finish ()

    gboolean
    media_art_process_buffer_finish (MediaArtProcess *process,
                                     GAsyncResult *result,
                                     GError **error);

Finishes the asynchronous operation started with `media_art_process_file_async()`.

#### Parameters

process | the MediaArtProcess |
result | a GAsyncResult. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` on success, otherwise `FALSE` when `error` will be set.

Since: 0.7.0

### media_art_error_quark ()

    GQuark
    media_art_error_quark (void);

The error domain for MediaArtError.

#### Returns

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

Since: 0.2.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. |
MEDIA_ART_ERROR_NO_CACHE_DIR | This is given when the XDG_CACHE_HOME directory could not be used to create the 'media-art' subdirectory used for caching media art. This is usually an initiation error. |

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;

A class implementation for processing and extracting media art.

### struct MediaArtProcessClass

    struct MediaArtProcessClass {
    };

Prototype for the class.