Extracting artwork

Media content often has artwork. For example, audio and video files can have embedded images, thumbnail graphics, and album artwork residing in their folder. The libmd library can read image metadata, allowing clients to discover artwork on connected mediastores and to retrieve images so they can display them during playback and enhance the user experience.

To extract artwork, you must:

Enable and configure artwork plugins.

The libmd library extracts artwork with these plugins:

Extart

Searches folders on connected mediastores to find artwork associated with media files, and retrieves image data, URLs, and other properties

iPod

Reads image data, file information, and display dimensions from specified artwork files on Apple devices

MediaFS

Reads image data, file information, and display dimensions from specified artwork files on MTP devices

MMF

Reads image data, descriptions, and properties of artwork accessed through network sources and POSIX devices

In the default configuration file, the MMF plugin is the only artwork-supporting plugin that's enabled. To enable another plugin, uncomment the [plugin] line that starts its configuration section and the dll setting on the next line. The Extart plugin has additional settings that you can uncomment to control some aspects of artwork extraction, such as the maximum number of images to read. These settings are explained in “MDP Settings”.
Add artwork plugins to lists of preferred plugins.
For all file types for which you want to retrieve artwork, you must name at least one artwork-supporting plugin in their lists of preferred plugins. Suppose you want to read artwork for media files found in POSIX filesystems and on MTP devices. You can modify the [typeratings] section in the configuration file as follows:
```
[typeratings]
file=extart,mmf,img
mtp=extart,mediafs
```
This tells libmd to use the Extart plugin for reading metadata when given a URL starting with file: or mtp:, or with no prefix and containing only a POSIX path (which is equivalent to using the file: prefix). In both cases, libmd tries to read the metadata with Extart. If it can't retrieve some fields with this plugin, the library may try the other listed plugins, depending on the parameters passed in by the client when requesting metadata.
Retrieve artwork through the libmd API.
The API call sequence for retrieving artwork is the same as that for reading other metadata. See the Metadata Provider API chapter for a summary of the commands used to read metadata. The key point to remember when extracting artwork is that not all information gets copied into the memory space referenced by the md parameter in the mmmd_get() call. Image details such as size or URL are stored in this library-allocated memory but the image data (which is much larger) is copied to the path specified in the md_artwork::image metadata type, which is named in the types parameter.

Suppose the client configures the Extart plugin to read POSIX files and then makes this API call:
```
mmmd_get( hdl, "/mediastore/1.mp3",
          md_artwork::image?file=/tmp/img1.jpg", NULL,
          0, &md );
```
Although the second argument defines a file path, the Extart plugin looks in the enclosing folder (/mediastore in this case) for artwork images. Because no image index is given in this example, the library writes the first image found that matches the search pattern defined by the regex# configuration settings into /tmp/img1.jpg.

For any artwork-supporting plugin, you can define the index parameter to extract a particular image. To know if more than one image is present in a given folder, you must first read one of the following types in an mmmd_get() call:

md_artwork::count

Indicates the number of images in the folder

md_artwork::size

Stores the sizes of all images found, in a comma-separated list of values

md_artwork::urls

(Supported only by Extart)

Stores the URLs of the images, in a comma-separated list of values. Some clients may not want to copy images and instead read and display them directly from devices. In this case, they can request the md_artwork::urls field, read the URLs within this field, and then specify these URLs in POSIX system calls to access images individually.

Suppose you learn of multiple artwork images associated with an audio track and you want to display these images at specific time offsets (e.g., 0s, 30s, 60s, and so on) during playback. At the appropriate times, you can request new images by specifying their indexes in calls like this:
```
mmmd_get( hdl, "/mediastore/1.mp3",
          md_artwork::image?file=/tmp/img1.jpg,index=1", NULL,
          0, &md );
```
This command retrieves the image at index 1 (i.e., the second image in the /mediastore folder). You could retrieve this image if you want to refresh the display after, say, 30 seconds of playback.