Cache

Cache — Caching and lookup of stored media art.

Functions

Includes

#include <libmediaart/mediaart.h>

Description

These functions give you access to the media art that has been extracted and saved. There are normally two places the media art will be located in. These locations store symlinks not real copies of the content:

  • The user's XDG_CACHE_HOME directory (usually ~/.cache/media-art/)

  • The local file system's top level .mediaartlocal directory (for example /media/martyn/pendrive/.mediaartlocal/)

To find the media art for a given media file, use the function media_art_get_file() (you can also use media_art_get_path(), which does the same thing but for path strings instead of GFile objects).

If media art for the file is not found in the cache, these functions will return NULL. You may find some embedded media art upon loading the file, and you can use media_art_process_buffer() to convert it to the correct format and save it in the cache for next time. The media_art_process_file() function also supports searching for external media art images using a basic heuristic.

Functions

media_art_get_path ()

gboolean
media_art_get_path (const gchar *artist,
                    const gchar *title,
                    const gchar *prefix,
                    const gchar *uri,
                    gchar **cache_path,
                    gchar **local_uri);

This function calls media_art_get_file() by creating a GFile for uri and passing the same arguments to media_art_get_file(). For more details about what this function does, see media_art_get_file().

Get the path to media art for a given resource. Newly allocated data returned in cache_path and local_uri must be freed with g_free().

Parameters

artist

the artist

 

title

the title

 

prefix

the prefix, for example "album"

 

uri

the uri of the file or NULL.

[allow-none]

cache_path

a string representing the path to the cache for this media art path or NULL.

[out][transfer full][allow-none]

local_uri

a string representing the URI to the local media art or NULL.

[out][transfer full][allow-none]

Returns

TRUE if cache_path or local_uri were returned, otherwise FALSE.

Since 0.2.0


media_art_get_file ()

gboolean
media_art_get_file (const gchar *artist,
                    const gchar *title,
                    const gchar *prefix,
                    GFile *file,
                    GFile **cache_file,
                    GFile **local_file);

Gets the files pointing to cache files suitable for storing the media art provided by the artist , title and file arguments. cache_file will point to a location in the XDG user cache directory, meanwhile local_file will point to a cache file that resides in the same filesystem than file .

The file provided is required if local_file is to be returned. The local_file relates to a location on the media the local file system or media storage it is found on, so for example, if you have a mounted volume with MP3s on it in file:///media/martyn/pendrive, the local_file will point to a URI that looks like file:///media/martyn/pendrive/.mediaartlocal/....

The cache_file is very different to the local_file , the cache_file relates to a symlink stored in XDG cache directories for the user. A cache_file would be expected to look like file:///home/martyn/.cache/media-art/.... This is normally the location that is most useful (assuming the cache has been extracted in the first place).

When done, both GFiles must be freed with g_object_unref() if non-NULL.

Parameters

artist

the artist

 

title

the title

 

prefix

the prefix for cache files, for example "album"

 

file

a GFile representing the actual media art or NULL.

[allow-none]

cache_file

a pointer to a GFile which represents the cached file for media art, or NULL a GFile representing the user's cache path, or NULL.

[out][transfer full][allow-none]

local_file

a pointer to a GFile representing the location of the local media art.

[out][transfer full][allow-none]

Returns

TRUE if cache_file or local_file were returned, otherwise FALSE.

Since 0.2.0


media_art_remove ()

gboolean
media_art_remove (const gchar *artist,
                  const gchar *album);

Removes media art for given album/artist provided.

Parameters

artist

artist the media art belongs to

 

album

album the media art belongs or NULL.

[allow-none]

Returns

TRUE on success, otherwise FALSE.

Since 0.2.0


media_art_strip_invalid_entities ()

gchar *
media_art_strip_invalid_entities (const gchar *original);

Strip a albumname or artistname string to prepare it for calculating the media art path with it. Certain characters and charactersets will be stripped and a newly allocated string returned which you must free with g_free().

This functions is used internally by media_art_get_file() and media_art_get_path(). You will not normally need to call it yourself.

This function provides the following features:

  1. Invalid characters include: ()[]<>{}_!@#$^&*+=|\/"'?~;

  2. Text inside brackets of(), {}, [] and <> pairs are removed.

  3. Multiples of space characters are removed.

Parameters

original

original string

 

Returns

original stripped of invalid characters which must be freed. On error or if original is empty, NULL is returned.

Since 0.2.0

Types and Values