Extraction

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

## Synopsis

    #include <libmediaart/mediaart.h>

    enum                MediaArtType;
    gboolean            media_art_init                      (void);
    void                media_art_shutdown                  (void);
    gboolean            media_art_process_file              (const guchar *buffer,
                                                             gsize len,
                                                             const gchar *mime,
                                                             MediaArtType type,
                                                             const gchar *artist,
                                                             const gchar *title,
                                                             GFile *file);
    gboolean            media_art_process                   (const unsigned char *buffer,
                                                             size_t len,
                                                             const gchar *mime,
                                                             MediaArtType type,
                                                             const gchar *artist,
                                                             const gchar *title,
                                                             const gchar *uri);

## 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()` 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()` 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()` functions will look in the directory that contains the media file for likely media art using a simple heuristic.

You must call `media_art_init()` before using the functions in libmediaart, and call `media_art_shutdown()` to free the resources it uses.

## Details

### enum MediaArtType

    typedef enum {
    	MEDIA_ART_NONE,
    	MEDIA_ART_ALBUM,
    	MEDIA_ART_VIDEO,
    } MediaArtType;

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

`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

### media_art_init ()

    gboolean            media_art_init                      (void);

Initialize libmediaart.

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

Returns : | `TRUE` if initialisation was successful, `FALSE` otherwise.

Since 0.2.0

### media_art_shutdown ()

    void                media_art_shutdown                  (void);

Clean up and free the resources created and mentioned in `media_art_init()`.

Since 0.2.0

### media_art_process_file ()

    gboolean            media_art_process_file              (const guchar *buffer,
                                                             gsize len,
                                                             const gchar *mime,
                                                             MediaArtType type,
                                                             const gchar *artist,
                                                             const gchar *title,
                                                             GFile *file);

Processes a media file. 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.

If `buffer` is `NULL`, libmediaart will search the parent directory of `file` for image files that are likely to be media art for `file`, and if one is found it will be saved in the media art cache.

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.

`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`
`type` : | The type of media
`artist` : | The media file artist name, or `NULL`
`title` : | The media file title, or `NULL`
`file` : | File to be processed
Returns : | TRUE if the file could be processed.

Since 0.2.0

### media_art_process ()

    gboolean            media_art_process                   (const unsigned char *buffer,
                                                             size_t len,
                                                             const gchar *mime,
                                                             MediaArtType type,
                                                             const gchar *artist,
                                                             const gchar *title,
                                                             const gchar *uri);

This function is the same as `media_art_process_file()`, but takes the URI as a string rather than a GFile object.

`buffer` : | A buffer of binary image data. [array length=len]
`len` : | The length of `buffer`, in bytes
`mime` : | The MIME type of the data stored in `buffer`
`type` : | The type of media that contained the image data
`artist` : | Artist name of the media. [allow-none]
`title` : | Title of the media. [allow-none]
`uri` : | URI of the media file that contained the image data
Returns : | `TRUE` in case of success, `FALSE` otherwise.

Since 0.2.0