libmediaart Library Reference Manual: Extraction

Extraction

Extraction — Extraction of music and movie art.

Functions

gboolean	media_art_init ()
void	media_art_shutdown ()
gboolean	media_art_process_file ()
gboolean	media_art_process ()

Types and Values

enum	MediaArtType

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() 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.

Functions

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.

Parameters

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.

Parameters

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

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