Extraction: libmediaart Library Reference Manual

Extraction

Extraction — Extraction of music and movie art.

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.

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.

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.

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