Artwork Management

This module handles the artwork (cover) of albums. Its main task is to cache, scale and provide them to the GUI.

Artwork Related Database Entries

The artwork data is part of the album entry in the MusicDB Database. The artwork part consists of the following entries:

artworkpath

bgcolor

fgcolor

hlcolor

artworkpath (string)

The path to the cover relative to the artwork root directory set in the MusicDB Configuration. To access a scaled version of the artwork, the scale as prefix can be used.

For example, to access a cover, the absolute path would be $ARTWORKCACHE/$ARTWORKPATH, a scaled version can be found in $ARTWORKCACHE/50x50/$ARTWORKPATH. Of cause only if the scale of 50x50 is supported (= configured in the Config-File).

bgcolor, fgcolor, hlcolor (string)

HTML-Color-Code that shall be used by the UI. This color is set by the user. Its format is "#" + RR + GG + BB with RR, GG, BB as a two digit hexadecimal number.

bgcolor is for background, fgcolor is the primary foreground color and hlcolor is the secondary color for less important elements in the foreground (like frames). For a complementary color scheme use bgcolor and fgcolor only. For a monochromatic scheme use bgcolor in a darker and less saturated variant for the background. The lighter and more saturated variant for the foreground. Keep in mind that the user may set all three colors to the same hue so that a monochromatic scheme gets forced.

Artwork Path structure

The artwork root directory can be configured in the MusicDB Configuration file. Everything related to artwork takes place in this directory. To use the artwork inside a web frontend, the HTTPS server needs access to this directory.

Relative to the artwork root directory are the artwork paths stored in the database. Source-Artworks, those who are not scaled, are in this directory. All scaled artworks are in sub-directories named by the resolution of the images.

The name of an image, scaled and non-scaled, consists of the artist name and album name. The file format is JPEG. So a name looks like this: $Artistname - $Albumname.jpg. This guarantees unique file names that are human readable at the same time. To get the 100x100 scaled version of this artwork just prepend 100x100/ to the path set in the database: 100x100/$Artistname - $Albumname.jpg

The file name gets created by the method CreateArtworkName(). This method replaces “/” by an Unicode division slash to avoid problems with the filesystem.

In case there is no artwork given for an album, the default artwork is default.jpg.

All new creates files were set to the ownership [musicdb]->username:[musicdb]->groupname and gets the permission rw-rw-r--

Web Browsers

Web browsers have to prefix the path with artwork/. So, the server must be configured.

Scaled Artwork

Scales that shall be provides are set in the MusicDB Configuration as list of edge-lengths. For example, to generate 50x50, 100x100 and 500x500 versions of an artwork, the configuration would look like this: scales=50, 100, 500 The scaled artwork gets stored as progressive JPEGs to get a better responsiveness for the WebUI.

Configuration for Artworks

[albumcover]
scales=50, 150, 500

Algorithm to Create Artworks

To update the album artwork cache the following steps are done:

1. Read metadata from file in GetArtworkFromFile()

   1. If there is no artwork, use default settings

   2. If there is an artwork, copy it to the artwork-directory

2. Create scaled versions of the new artwork in SetArtwork()

3. Create database entry in SetArtwork()

MusicDBArtwork Class

class musicdb.mdbapi.artwork.MusicDBArtwork(config, database)

Parameters

• config – MusicDB configuration object

• database – MusicDB database

Raises

• TypeError – if config or database are not of the correct type

• ValueError – If one of the working-paths set in the config file does not exist

static CreateArtworkName(artistname, albumname)

This method creates the name for an artwork regarding the following schema: $Artistname - $Albumname.jpg. If there is a / in the name, it gets replaced by ∕ (U+2215, DIVISION SLASH)

Parameters

• artistname (str) – Name of an artist

• albumname (str) – Name of an album

Returns

valid artwork filename

GetArtworkFromFile(album, tmpawfile)

This method tries to get an artwork from the metadata of the first song of an album. With the first song, the first one in the database related to the album is meant. The metadata gets loaded and the artwork stored to a temporary file using the method musicdb.lib.metatags.MetaTags.StoreArtwork().

Parameters

• album – Album entry from the MusicDB Database

• tmpawfile (str) – Temporary artwork path (incl filename) to which the artwork shall be written

Returns

True on success, otherwise False

SetArtwork(albumid, artworkpath, artworkname)

This method sets a new artwork for an album. It does the following things:

1. Copy the artwork from artworkpath to the artwork root directory under the name artworkname

2. Create scaled Versions of the artwork by calling musicdb.lib.cache.ArtworkCache.GetArtwork() for each resolution.

3. Update entry in the database

All new creates files ownership will be set to [music]->owner:[music]->group and gets the permission rw-rw-r--

Parameters

• albumid – ID of the Album that artwork shall be set

• artworkpath (str, NoneType) – The absolute path of an artwork that shall be added to the database. If None the method assumes that the default artwork shall be set. artworkname will be ignored in this case.

• artworkname (str) – The relative path of the final artwork.

Returns

True on success, otherwise False

Examples

# Copy from metadata extracted temporary artwork to the artwork directory
self.SetArtwork(albumid, "/tmp/musicdbtmpartwork.jpg", "Artist - Album.jpg")

# Copy a user-defined artwork to the artwork directory
self.SetArtwork(albumid, "/home/username/downloads/fromzeintanetz.jpg", "Artist - Album.jpg")

# Set the default artwork
self.SetArtwork(albumid, None, any)

UpdateAlbumArtwork(album, artworkpath=None)

This method updates the artwork path entry of an album and the artwork files in the artwork directory. If a specific artwork shall be forced to use, artworkpath can be set to this artwork file. Following the concept The Filesystem Is Always Right and Do Not Trust Metadata, the user specified artwork path has higher priority. Metadata will only be processed if artworkpath is None

So an update takes place if at least one of the following condition is true:

1. The database entry points to default.jpg

2. artworkpath is not None

3. If the database entry points to a nonexistent file

Parameters

• album – An Album Entry from the MusicDB Database

• artworkpath (str, NoneType) – Absolute path of an artwork that shall be used as album artwork. If None the Method tries to extract the artwork from the meta data of an albums song.

Returns

True If either the update was successful or there was no update necessary. False If the update failed. Reasons can be an invalid artworkpath-Argument

UpdateFileAttributes(path)

Tries to set the on owner of a file as configured in the MusicDB Configuration and the access permission to rw-rw-r--.

If the path is "default.jpg" only True gets returned without changing anything. The default artwork is part of the MusicDB data and gets managed by high level classes.

Parameters

path – path to the artwork

Returns

True on success, otherwise False

ArtworkCache Class

class musicdb.lib.cache.ArtworkCache(artworkdir)

This class handles the artwork cache. Its main job is to scale an image if a special resolution is requested.

Parameters

artworkdir – Absolute path to the artwork root directory

GetArtwork(artworkname, resolution)

This method returns a valid path to an artwork with the specified resolution.

The final path will consist of the artworkdir given as class parameter, the resolution as subdirectory and the artworkname as filename. ({artworkdir}/{resolution}/{artworkname})

If the artwork does not exist for this resolution it will be generated. If the directory for that scale does not exist, it will be created. Its permission will be musicdb:musicdb drwxrwxr-x In case an error occurs, an exception gets raised.

The resolution is given as string in the format {X}x{Y} (For example: 100x100). X and Y must have the same value. This method expects an aspect ratio of 1:1.

Beside scaling the JPEG, it will be made progressive.

Parameters

• artworkname (str) – filename of the source artwork (Usually $Artist - $Album.jpg)

• resolution (str) – resolution of the requested artwork

Returns

Relative path to the artwork in the specified resolution. None on error.

Raises

ValueError – When the source file does not exist

Example

cache = ArtworkCache("/data/artwork")
path  = cache.GetArtwork("example.jpg", "150x150")
# returned path: "150x150/example.jpg"
# absolute path: "/data/artwork/150x150/example.jpg"

RebuildArtwork(artworkname, resolution)

This method rebuilds an artwork with the specified resolution.

If the artwork does not exist for this resolution it will be generated. If the directory for that scale does not exist, it will be created. Its permission will be musicdb:musicdb drwxrwxr-x In case an error occurs, an exception gets raised.

The resolution is given as string in the format {X}x{Y} (For example: 100x100). X and Y must have the same value. This method expects an aspect ratio of 1:1.

Beside scaling the JPEG, it will be made progressive.

Parameters

• artworkname (str) – filename of the source artwork (Usually $Artist - $Album.jpg)

• resolution (str) – resolution of the requested artwork

Returns

True on success

Example

cache = ArtworkCache("/data/artwork")
if not cache.RebuildArtwork("example.jpg", "150x150"):
    print("creating a 150x150 thumbnail failed")