Getting Album Art

MediaFS supports retrieval of album art associated with media files, if this capability is supported by the media device:

How to retrieve album art

To retrieve album art associated with a media file, a high-level multimedia application, such as the MME, and the device driver must perform the following steps in sequence:

  1. Client application: Issue a DCMD_MEDIA_ALBART_INFO message to the MediaFS control file, or to another specified file to find out if there is artwork associated with the file.

    Device controller: Retrieve the required information from the device and return it in the _media_albart_entry data structure. If artwork is available, set the appropriate values in this structure's flag and pos members.

  2. Client application: If artwork is available, issue a DCMD_MEDIA_ALBART_LOAD message.

    Device controller: Complete and return the _media_albart_entry structure with the image description, so that the client application can know the size of the image and prepare to read it.

  3. Client application: Issue DCMD_MEDIA_ALBART_READ messages to read the artwork and place it in a buffer, managing the returned image blocks and using them to reconstruct the image after the complete image has been read.

    Device controller: Retrieve as requested the artwork in blocks from the media device, returning to the client application, as appropriate, one of:

Album art messages

To support album art retrieval, a device controller must support the following control messages from a higher-level application:


Note: If the queried media device does no support the album art retrieval, the devctl() call with the DCMD_MEDIA_ALBART_* message returns ENOTSUP.

DCMD_MEDIA_ALBART_INFO

The DCMD_MEDIA_ALBART_INFO message is used to query a media file for the presence of album artwork. The album art information for the file is placed in the _media_albart_entry data structure.

On success, a call to devctl() with this message returns EOK; the devctl() dev_info_ptr parameter points to the number or entries in the array with the album artwork.

Buffer: _media_albart_entry

DCMD_MEDIA_ALBART_LOAD

The DCMD_MEDIA_ALBART_LOAD message is used to retrieve the index information for a file whose album artwork is to be retrieved. The requested information is placed in the _media_albart_entry data structure.

On success, a call to devctl() with this message returns EOK; the devctl() dev_info_ptr parameter points to the index for the specified file.

Buffer: _media_albart_entry

DCMD_MEDIA_ALBART_READ

The DCMD_MEDIA_ALBART_READ message is used to read an album artwork image. The read process starts with the devctl() call with the DCMD_MEDIA_ALBART_READ message and ends when the entire image has been read.

Image data is read only once and returned; once a portion of an image has been read and returned, it is not returned again. The device controller must manage reading data blocks from the device, and the calling application must manage the returned data blocks until the entire image has read and can be passed up to an HMI application for display.

The total size of the image, in bytes, and other image information is placed in the _media_img_desc data structure.

When a call to devctl() with the DCMD_MEDIA_ALBART_READ message completes the device controller must return one of:

In addition, on completion of a successful call the dev_info_ptr parameter must point to the number of bytes received.

Buffer: _media_albart

Album art structures

MediaFS uses the following data structures to process the album art for media files:

_media_albart

struct _media_albart {
    uint32_t                flags;
    uint32_t                pos;
    uint32_t                reserved[6];
    struct _media_img_desc  desc;
    uint8_t                 data[1];
};

The _media_albart structure contains the album art data retrieved from a media file. It is populated and returned by devctl() when it successfully issues a DCMD_MEDIA_ALBART_READ message to a MediaFS file.

The data in this structure may not be the complete requested image, and multiple reads may be required to read a complete image. See DCMD_MEDIA_ALBART_READ in the chapter MediaFS Messages.

Member Type Description
flags uint32_t Flags specifying how to interpret position information for the album art. See the descriptions of the ALBART_FLAG_POS_* constants under Album art constants below.
pos uint32_t Position at which to display the album art. This position is either the offset, in milliseconds, in the track if ALBART_FLAG_POS_TRKPOS is set; or the chapter, if ALBART_FLAG_POS_CHPIDX is set.
reserved [6] uint32_t Reserved for future use.
desc struct The _media_img_desc structure with the image description.
data [1] uint8_t An array for the album art data.

_media_albart_entry

struct _media_albart_entry {
    uint16_t                index;
    uint16_t                reserved[3];
    uint32_t                flags;
    uint32_t                pos;
    struct _media_img_desc  desc;
};
Member Type Description
index uint16_t The index to match for this album art entry.
reserved [3] uint16_t Reserved for future use.
flags uint32_t Flags specifying how to interpret position information for the album art. See the descriptions of the ALBART_FLAG_POS_* constants under Album art constants below.
pos uint32_t Position at which to display the album art. This position is either the offset, in milliseconds, in the track if ALBART_FLAG_POS_TRKPOS is set; or the chapter, if ALBART_FLAG_POS_CHPIDX is set.
desc struct The _media_img_desc structure with the image description.

_media_img_desc

struct _media_img_desc {
    uint32_t  width;
    uint32_t  height;
    uint32_t  size;
    uint32_t  reserved;
    char      mimetype[64];
};
Member Type Description
width uint32_t The album art image width, in pixels.
height uint32_t The album art image height, in pixels.
size uint32_t The album art image size, in bytes.
reserved uint32_t Reserved for future use.
mimetype [64] char A string with the album art MIME type.

Album art constants

The table below lists the constants defined in dcmd_media.h for album artwork processing.

Constant Value Description
ALBART_FLAG_POS_NONE 0x00000000 No position information is available.
ALBART_FLAG_POS_TRKPOS 0x00000001 The position is expressed in milliseconds from the start of the track.
ALBART_FLAG_POS_CHPIDX 0x00000002 The position is the chapter number.
ALBART_FLAG_POS_MASK 0x0000000F A mask for stripping out bits not relevant to the flags member of the _media_img_desc data structure.
ALBART_INDEX_NONE 0xFFFF Indicate that no specific index is used, so that a call to devctl() with the DCMD_MEDIA_ALBART_LOAD message attempts to load the best match rather than a specific file.