Functions¶

	`buffer_to_jpeg` (buffer, buffer_mime, target)
	`error_quark` ()
	`file_to_jpeg` (filename, target)
	`get_file` (artist, title, prefix)
	`get_path` (artist, title, prefix)
	`plugin_init` (max_width)
	`plugin_shutdown` ()
	`remove` (artist, album, cancellable)
	`remove_async` (artist, album, io_priority, source_object, cancellable, callback, *user_data)
	`remove_finish` (source_object, result)
	`strip_invalid_entities` (original)

Details¶

MediaArt.buffer_to_jpeg(buffer, buffer_mime, target)¶

Parameters:

buffer (bytes) – Raw buffer representing content to save
buffer_mime (str) – MIME type for buffer
target (str) – Output file name (not URI) to save converted content to

Raises:

GLib.Error

Returns:

True if conversion was successful, otherwise False is returned if error is set.

Return type:

bool

This function performs the same operation as MediaArt.file_to_jpeg() with the exception that a raw buffer can be used instead providing len and the buffer_mime too.

New in version 0.1.0.

MediaArt.error_quark()¶

Returns:: the #GQuark used to identify media art errors in GLib.Error structures.
Return type:: int

The error domain for MediaArt.Error.

New in version 0.2.0.

MediaArt.file_to_jpeg(filename, target)¶

Parameters:

filename (str) – Original file name (not URI) to convert
target (str) – Output file name (not URI) to save converted content to

Raises:

GLib.Error

Returns:

True if conversion was successful, otherwise False is returned if error is set.

Return type:

bool

Save filename to target as JPEG format. The filename may not be a JPEG in the first place.

New in version 0.1.0.

MediaArt.get_file(artist, title, prefix)¶

Parameters:

artist (str or None) – the artist
title (str or None) – the title
prefix (str or None) – the prefix for cache files, for example “album”

Returns:

True if cache_file was returned, otherwise False.

cache_file:: a pointer to a Gio.File which represents the cached file for media art, or None a Gio.File representing the user’s cache path, or None Gio.File representing the location of the local media art

Return type:

(bool, cache_file: Gio.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..

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 Gio.File s must be freed with GObject.Object.unref() if non-None.

This operation should not use i/o, but it depends on the backend Gio.File implementation.

All string inputs must be valid UTF8. Use GLib.utf8_validate() if the input has not already been validated.

New in version 0.2.0.

MediaArt.get_path(artist, title, prefix)¶

Parameters:

artist (str or None) – the artist
title (str or None) – the title
prefix (str or None) – the prefix, for example “album”

Returns:

True if cache_path was returned, otherwise False.

cache_path:: a string representing the path to the cache for this media art path or None

Return type:

(bool, cache_path: str)

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

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

All string inputs must be valid UTF8. Use GLib.utf8_validate() if the input has not already been validated.

New in version 0.2.0.

MediaArt.plugin_init(max_width)¶

Parameters:: max_width (int) – The maximum width that an image is allowed to be

This function facilitates a plugin’s need to create any internal caches before anything else is done. This function must exist in each plugin and is called immediately after the plugin is loaded. Conversely, MediaArt.plugin_shutdown() is called before tear down of the plugin system or plugin itself.

New in version 0.1.0.

MediaArt.plugin_shutdown()¶: This function facilitates a plugin’s need to clean up any internal caches. This function must exist in each plugin and is called immediately after the plugin is loaded. Conversely, MediaArt.plugin_init() is called after the plugin is loaded.

New in version 0.1.0.

MediaArt.remove(artist, album, cancellable)¶

Parameters:

artist (str) – artist the media art belongs to
album (str or None) – album the media art belongs or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

GLib.Error

Returns:

True on success, otherwise False where error will be set.

Return type:

bool

Removes media art for given album/artist provided.

If artist and album are None, ALL media art cache is removed.

All string inputs must be valid UTF8. Use GLib.utf8_validate() if the input has not already been validated.

New in version 0.2.0.

MediaArt.remove_async(artist, album, io_priority, source_object, cancellable, callback, *user_data)¶

Parameters:

artist (str) – artist the media art belongs to
album (str or None) – album the media art belongs or None
io_priority (int) – the I/O priority of the request
source_object (GObject.Object or None) – the GObject.Object this task belongs to, can be None.
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – the data to pass to callback function

Removes media art for given album/artist provided. Precisely the same operation as MediaArt.remove() 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 Gio.IOErrorEnum.CANCELLED.

During an async request no other sync and async calls are allowed, and will result in Gio.IOErrorEnum.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 GLib.PRIORITY_DEFAULT.

All string inputs must be valid UTF8. Use GLib.utf8_validate() if the input has not already been validated.

New in version 0.7.0.

MediaArt.remove_finish(source_object, result)¶

Parameters:

source_object (GObject.Object or None) – the GObject.Object this task belongs to, can be None.
result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

True on success, otherwise False when error will be set.

Return type:

bool

Finishes the asynchronous operation started with MediaArt.remove_async().

New in version 0.7.0.

MediaArt.strip_invalid_entities(original)¶

Parameters:: original (str or None) – original string
Returns:: original stripped of invalid characters which must be freed. On error or if original is None, None is returned.
Return type:: str

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

This functions is used internally by MediaArt.get_file() and MediaArt.get_path(). You will not normally need to call it yourself.

This function provides the following features:

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

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

Multiples of space characters are removed.

This function expects that the input is valid UTF-8. Use GLib.utf8_validate() if the input has not already been validated.

New in version 0.2.0.