Metadata and Artwork

This chapter describes how to get metadata and artwork for your media files. It includes:

Getting metadata

The MME provides a variety of methods for retrieving metadata. You can use the MME to retrieve metadata:

Getting metadata for synchronized media

You can provide your end users with information, such as album title, artist, and composer, for the currently playing file or track in a library-based track session by retrieving this metadata from the MME's library table.

To retrieve metadata for the currently playing file or track from the library table:

  1. Call mme_play_get_info() to get the current file ID (fid).
  2. Query the MME database for the metadata.

The sample query shown below retrieves title, album name, artist name, genre name, and composer name, assuming that you know only the fid for a track:

SELECT title, artist, album, genre, composer
    FROM library NATURAL JOIN (
    library_albums, library_artists, library_genres, library_composers)
    WHERE fid=%lld;

A library-based track session is a track session created with synchronized media files. For more information, see About track sessions in the chapter Playing Audio.


Note: If an MP3 file contains more than one version of ID3 tags, the MP3 file parser parses the most recent tag and ignores the older tag version. That is, if a file contains both ID3v1 and ID3v2 metadata tags, the MP3 file parser ignores the ID3v1 tags. Only the metadata from the the ID3v2 tags is made available to the MME.

For information about getting metadata for tracks in a file-based track session; that is track sessions created with unsynchronized media, see Getting metadata for unsyncrhonized media below.

Getting metadata for unsynchronized media

The MME includes an API that can be used to retrieve metadata for files on an both synchronized and unsynchronized mediastores and devices.

This feature is particularly useful for quickly retrieving metadata for specific files from large mediastores or devices, such as iPods, that would take a long time to synchronize completely. For example, you can use this feature to retrieve metadata for a single file or a small number of files, to display it to a user exploring the contents of a mediastore or device.

This API includes the following functions, structures and constants:

The metadata extraction functions listed above require the filepath and filename of the file whose metadata is needed — for example, to display to a user who requests more information about a track on an iPod.

Thus, to retrieve and make available metadata for unsynchronized media, you must:

How to get the metadata

Once you have the path for the file whose metadata is needed:

  1. Call mme_ms_metadata_get(), passing it the path to the file whose metadata you need, and the types of. It returns the mme_metadata_hdl_t with the metadata for the file.
  2. Call mme_metadata_extract_string() to extract metadata strings and mme_metadata_extract_unsigned() to extract unsigned metadata.
  3. Use the metadata as required — for example, display to the end-user.
  4. Call mme_ms_metadata_done() to complete the operation and release the metadata handle.

Managing explorer structures and metadata handles

Metadata extraction from unsynchronized media requires that the client application manage the explorer information structures and the metadata and explorer handles it uses. The client application must:

The client application must use mme_metadata_alloc() to copy the metadata handle. This copied metadata handle returned by mme_metadata_alloc() maintains valid information until the client application releases it.

Simply copying the mme_explore_info_t data structure does not guarantee valid information because:


Note: The pointer to the path is a normal C-string; the client application:
  • may use any method, such as strdup() or strcpy(), to copy the source string
  • is responsible for managing the memory required for these copies

Getting metadata from the nowplaying table

The nowplaying table may contain more complete metadata than is available in the library table — for example, when playing an iPod track session, because an iPod makes information, such as track duration, available only during playback.

When the MME starts playing a new track it updates the information in the nowplaying table and delivers an MME_EVENT_TRACKCHANGE event. When it updates metadata in the nowplaying table it delivers the event MME_EVENT_NOWPLAYING_METADATA, which you can use to trigger queries to retrieve the updated metadata.

See also the description of the nowplaying table in the appendix: MME Database Schema Reference of the MME API Library Reference.

Getting metadata from a remote source

The MME supports metadata from remote sources, such as CDText, Gracenote and MusicBrainz. To use these capabilities, you must change the MME configuration file, mme.conf, to enable the relevant MME modules and configure the specific behaviors required by your environment.

For information about how to configure the MME to support these modules, see Metadata synchronizers in the chapter Configuring Metadata Support in the MME Configuration Guide.


Note: Support for these features may require special licensing. Contact QNX for more information.

Metadata ratings

This MME supports metadata rating extractions for the following formats:

MP3 files

If the ratings are available, the MME's MMF module extracts metadata ratings in MP3 files from the following tags:

Tag Frame
ID3v2.2 POP
ID3v2.3 POPM
ID3v2.4 POPM

WMA files

If the ratings are available, the MME's MMF module extracts metadata ratings in WMA files from the Extended Content Description Object's WM/SharedUserRating record.

Ratings conversions

The MME stores metatdata ratings in the rating field in the:

The rating field in the nowplaying table makes a file's rating available even when the file does not have an entry in the library; for example, when the file is accessed through the MME's Explorer API.

Rating values are stored as follows:

The MME stores ratings from MP3 file ID3 tags without conversion. It converts WMA file WM/SharedUserRating record ratings from their 1 to 99 range to a 1 to 255 range.

The table below shows how the the MME's 1 to 255 rating system maps to WMA 1 to 99 rating system and to the WMA five star rating system:

MME WMA Stars
1-60 1-24 *
61-125 25-49 **
126-190 50-74 ***
191-254 75-98 ****
255 99 *****

Getting artwork

The MME includes a “Load-on-Demand” API for retrieving metadata. This API is designed to support on-demand retrieval of all types of metadata, but it is currently implemented for artwork, such as album art images.


Note:
  • The Load-on-Demand metadata API can be used to retrieve artwork from synchronized or unsychronized media. It requires only that you specify the file for which you want to retrieve the artwork.
  • For information about retrieving artword from Zune devices, see Retrieving artwork from Zune devices in the chapter Working with PFS Devices.

Functions and data structures

The MME's Load-on-Demand metadata extraction API includes the following functions and data structures:

Information for images stored in the MME's metadata image persistent cache is kept in the mdi_image_cache table.

For information about how to set configuration options for the MME's metadata extraction API, see the chapter MME Configuration Guide chapter Configuring Metadata Support.

libxml2.so library and headers

MME releases include the libxml2.so library and appropriate headers; this library and the headers are required by clients of the MME in order to parse the metadata structures delivered by the MME metadata extraction functions.

The libxml2 library delivered with the MME includes only a small subset of the full libxml2 library; it includes only the modules required for reading, parsing and writing XML files. The xmlversion.h header file indicates exactly what functional modules are in the included library.

Documentation for libxml2 is available at xmlsoft.org.

Feature limitations

The current release support is limited, as follows:

Using the metadata extraction API

The MME's metadata extraction API uses metadata sessions. A metadata session uses a metadata session identifier used by the metadata extraction functions.

Metadata extraction includes the following tasks:

  1. Call mme_metadata_create_session() to create a metadata session and reserve the required system resouces.
  2. Call one of the mme_metadata_getinfo_*() functions to retrieve the required metadata for a specified file and place it in the mme_metadata_info_t data structure.
  3. If an image is available and required, call mme_metadata_image_load() to load the image into the image cache.
  4. Call mme_metadata_free_session() to close the metadata session and free the system resources it was using.

The metadata extraction functions deliver metadata information as XML in the mme_metadata_info_t structure. For more information, and examples, see XML content on the mme_metadata_info_t structure reference page.

As required, the client application can also:


Note: The MME supports extraction of album artwork from iPods for the currently playing track only. To retrieve album artwork from iPods, use the metadata extraction API as you do to retrieve artwork from other devices and mediastores.

See also Retrieving artwork from iPods in the chapter Working with iPods.


Image pre-processing

The MME supports image pre-processing with the following capabilities:


Note: Images encoded into the BMP format may not be readable by some external applications.

Enabling image pre-processing

The MME's image processing capabilities are configured through the <MetadataInterface>/<ImageProcessing> element in the MME's configuration file, mme.conf.

To enable image pre-processing, you must:

  1. Configure the image processing library.
  2. Enable one or more image processing modules.
  3. Configure image processing profiles to be used by the MME's metadata Load-on-Demand API.

Caution: If you do not enable the image processing module, or if there are no image processing modules configured, attempts to use a defined image processing profile through the MME's metadata interface will fail with an EINVAL error.

For information about how to configure and enable the MME for image pre-processing, see Image pre-processing in the chapter Configuring Metadata Support in the MME Configuration Guide.


Note: A patch is required to enable the selection of JPEG image quality when performing image pre-processing. This patch is available in the archive patch-640-1383-img-quality.tar, under the Foundry27 Multimedia project's Downloads tab.

Using image pre-processing

The MME's metadata API implements the mme_metadata_image_load() function to load and, if requested, process images. Image processing is specified through the function's image_format_profile parameter. This parameter can be set to either -1 if no image processing is required, or the number of a pre-defined image processing profile. For more information about these profiles and how to configure then, see Configuring image processing profiles in the chapter Configuring Metadata Support in the MME Configuration Guide.

For more information about mme_metadata_image_load(), see the MME API Library Reference.