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,
                       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_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_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`
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

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 {
	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