Configuring Metadata Support

This chapter explains how to configure the MME metadata support, including image pre-processing.

Metadata in the MME database

This section describes configuration settings that determine some metadata characteristics in the MME database:

For information about configuring synchronization behavior, see the chapter Configuring Media Synchronizations.

Populating the library table metadata during playback

The MME can be configured to write to the library table the metadata it has for the currently playing track in the nowplaying table.

This option is set by the <Synchronization> element <UpdateLibraryFromNowplaying> in the MME configuration file. The default setting is “off”: do not update the library metadata from the nowplaying table.

With this option enabled, depending on your environment and your performance requirements, you may configure your system to perfrom only the first synchronization pass, then populate the metadata in the library table only as tracks are played.

Limiting the length of metadata strings

The <MetadataStringMaximums> element contains <metadatastring> elements that you can use to limit the length of the metadata strings that the MME writes in its database.

The default configuration is to not limit the length of metadata strings. To change this configuration, remove the comments from around the <MetadataStringMaximums> element, and update the attributes for the <metadatastring> elements as required.

These attributes are:

Below is a sample <MetadataStringMaximums> element:

<MetadataStringMaximums>
	<metadatastring field="artist" maximum="1024"/>
	<metadatastring field="album" maximum="1024"/>
	<metadatastring field="genre" maximum="1024"/>
	<metadatastring field="composer" maximum="1024"/>
	<metadatastring field="category" maximum="1024"/>
	<metadatastring field="title" maximum="1024"/>
	<metadatastring field="conductor" maximum="1024"/>
	<metadatastring field="soloist" maximum="1024"/>
	<metadatastring field="ensemble" maximum="1024"/>
	<metadatastring field="opus" maximum="1024"/>
	<metadatastring field="description" maximum="1024"/>
</MetadataStringMaximums>

Artwork support

The MME's metadata interface is used to retrieve artwork associated with media files. This section describes MME metadata interface configuration options. Metadata interface configuration elements are under the <MetadataInterface> top-level container element in the MME configuration file mme.conf:

For information about how to use the metadata interface to retrieve artwork, see the chapter Metadata and Artwork in the MME Developer's Guide.

<MetadataInterface> elements

The table below lists the top-level container elements inside the in <MetadataInterface>:

Element Default Description
<ExternalArtwork> n/a Container for elements defining external artwork search behavior. See External artwork below.
<ImageExtraction> n/a Container element for image extraction configuration elements. See Image extraction below.
<ImageProcessing> n/a Container element for elements used to configure custom processing modules. See Image pre-processing below.

Example

Below is an example of a sample metadata interface configuration:

<MetadataInterface>
	<ImageExtraction>
        <TemporaryLocation path="/tmp"/>
		<PersistentLocation enabled="true" path="/imagecache" maxsize="0" prune_algorithm="0"/>
	</ImageExtraction>
</MetadataInterface>

Image extraction

The elements inside the <ImageExtraction> element configure locations and paths to be used by the MME's image extraction API. These elements are listed in the table below:

Element Attributes Default Description
<ImageExtension> value User-defined extension to append to the generated image URL that is returned when loading images. The default is to append no extension to the image URL.
<PersistentLocation> See below. "/imagecache" The permanent location for extracted images; see <PersistentLocation> attributes below.
<TemporaryLocation> path /tmp/ The path to a temporary location for storing images. This location needs to persist only for the duration of the MME life span. The MME must have read/write access to this location.

<PersistentLocation> attributes

The <PersistentLocation> element supports the following attributes:


Note: Support for the <PersistentLocation> element will be implemented in a future release.

External artwork

The MME includes configuration elements that define if and how the MME's metadata API functions search for external artwork (images not embedded in a media file, but placed in folders adjacent to the media file). The table below lists these elements:

Element Attributes Default Description
<ArtworkFileNames> Container element for <FileSpecifier> elements that define regular expressions used for external artwork searches. See <FileSpecifier> elements below.
<SearchBehaviour> See below. never Configure behavior for external artwork searches. See <SearchBehaviour> attributes below.

<SearchBehaviour> attributes

The <SearchBehaviour> element defines when and how the MME's metadata API searches for external artwork, if it has been requested to load artwork for a media file. This element has three attributes:

For example:

<ExternalArtwork>
    <SearchBehaviour when="always" ignore_case="true" search_limit="100"/>
	...
</ExternalArtwork>

<FileSpecifier> elements

The <FileSpecifier> elements defines regular expressions that the MME will match against when searching for external artwork files. You can define multiple <FileSpecifier> elements, up to the maximum set by CONFIG_MAX_ARTWORK_FILE_SPECIFIERS. A <FileSpecifier> element has one attribute, value, which specifies a foldername, and a file extension:

<ExternalArtwork>
    ...
    <ArtworkFileNames>
        <FileSpecifier value="folder\.jp[e]?g"/>
        <FileSpecifier value="album\.jp[e]?g"/>
		...
    </ArtworkFileNames>
</ExternalArtwork>

Note: Note that optional letters can be used in the file extension string. For example, the configuration below instructs the MME to search the folder and album directories for files with extensions of either .jpg or .jpeg. If the <SearchBehaviour> element's ignore_case attribute is set to true the MME will also search for files with .JPG or .JPEG extensions.

CONFIG_MAX_ARTWORK_* constants

The following constants specify limits used when searching for external artwork:

Name Value
CONFIG_MAX_ARTWORK_FILE_SPECIFIERS 32
CONFIG_MAX_ARTWORK_FILE_SPECIFIER_LENGTH 64
CONFIG_MAX_ARTWORK_FILE_EXTENSION_LENGTH 8
CONFIG_DEF_MDI_EXT_ARTWORK_SEARCH_LIMIT 100

Image pre-processing

The MME's image processing capabilities are configured through the <MetadataInterface>/<ImageProcessing> element.

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.

For information about image pre-processing, see the chapter Metadata and Artwork in the MME Developer's 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.

Configuring the image processing library

To enable image processing you must configure the image processing library by having the following configuration file /etc/system/config/img.conf present on the system and configured for the required codecs, as shown below:

[img_codec_bmp.so]
mime=image/bmp:image/x-bmp:image/x-bitmap:image/x-xbitmap:image/x-win-bitmap:image/x-windows-bmp:image/ms-bmp:image/x-ms-bmp:application/bmp:application/x-bmp:application/x-win-bitmap:application/preview
ext=bmp
[img_codec_gif.so]
mime=image/gif:/image/x-xbitmap:image/gi_
ext=gif
[img_codec_jpg.so]
mime=image/jpeg:image/jpg:image/jp_:application/jpg:application/x-jpg:image/pjpeg:image/pipeg:image/vnd.swiftview-jpeg:image/x-xbitmap
ext=jpg:jpeg
[img_codec_png.so]
mime=image/png:application/png:application/x-png
ext=png
[img_codec_sgi.so]
mime=image/sgi:image/x-sgi:image/x-sgi-rgba:image/x-sgi-bw:image/rgb:image/x-rgb
ext=sgi:rgb:rgba:bw
[img_codec_tga.so]
mime=application/tga:application/x-tga:application/x-targa:image/tga:image/x-tga:image/targa:image/x-targa
ext=tga
[img_codec_pcx.so]
mime=application/pcx:application/x-pcx:image/pcx:image/x-pcx:image/x-pc-paintbrush:zz-application/zz-winassoc-pcx
ext=pcx

For more information about the img.conf configuration file, see img_lib_attach() in the Advanced Graphics Developer's Guide.

Enabling an image processing module

The MME includes the image processing module mme-imgprc-gf.so. However, by default, no image processing modules are loaded into the MME.

The <ConversionThreadOptions> and <Libraries> elements, are located inside the <ImageProcessing> element in the MME configuration file.

The table below describes these elements:

Element Attributes Default Description
<ConversionThreadOptions> priority 0 Set attributes associated to the image conversion thread run when a image loading occurs, with a profile. The priority is an absolute priority. The default is 0: run at the same priority as the MME.
<Libraries> Container for one or more <dll> elements. See <dll> element below.

<dll> element

The table below describes the <dll> element:

Element Attributes Default Description
<dll> name empty Set the name of the image processing module. One or more of these elements must be set to enable the MME's image processing capabilties.

To enable the MME's image processing capabilties, you must remove the comments around the <Libraries> and <dll> configuration elements, then restart the MME. You can add new <dll> elements for new image processing modules, as required.

Example

The example below shows a portion of the MME configuration file enabling the mme-imgprc-gf.so image processing module:

<ImageProcessing>
	...
	<Libraries>
		<dll name="mme-imgprc-gf.so"/>
	</Libraries>
	...
</ImageProcessing>

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.

Configuring image processing profiles

Image processing profiles determine how an image is transformed and transcoded when it is loaded through the MME's metadata API. Image profiles are defined by multiple <Profile> elements and their sub-elements inside the <ImageProcessing> element.

The table below describes the <Profile> element:

Element Attributes Default Description
<Profile> index Multiple profile elements specify how an image should be processed when uploaded through the MME's metadata API. The index attribute is a required profile number, to which you set the mme_metadata_image_load() function's image_format_profile parameter so the the MME processes the image according to this profile.

The table below describes the <Profile> element's sub-elements that determine image processing specifics:

Element Attributes Default Description
<Transform> Container for one or more possible sub-elements, such as <Scale> and <Rotate> that define how to transform an image being loaded.
<Transcode> Container for transcoding elements, such as <Output>, which determines th output format for an image.

Note: Values passed to element attributes should be enclosed in double quotation marks. For example:
<SomeElement some_attribute="some_value">

The <Transform> element and its sub-elements

The <Transform> element contains sub-elements that define how to transform an image that is being loaded with the current profile. All sub-elements are processed in the order in which they are defined. Currently, supported elements are:

<Scale>

The <Scale> element supports the following attributes:

If only one of the width and height attributes is specified, the image is scaled to the specified size, maintaining its original aspect ratio.

<Rotate>

The <Rotate> element supports the following attribute:

The <Transcode> element and its sub-elements

The <Transcode> element contains sub-elements that define how to transcode an image that is being loaded with the current profile. All sub-elements are processed in the order in which they are defined. Currently, the only supported element is:


Note: If the <Transcode> element is:
  • not specified in a profile, the image will be encoded back into its original format
  • specified in a profile, it must be the last element listed inside the <Profile> element

<Output>

The <Output> element supports the following attributes:

Example

Below is an example of an image processing element and its sub-elements:

<ImageProcessing>
	<Libraries>
		<dll name="mme-imgprc-gf.so"/>
		...
	</Libraries>

	<Profile index="0">
	    <Transform>
	        <Scale width="500"/>
	    </Transform>
	</Profile>
	<Profile index="1">
	    <Transform>
	        <Rotate method="90cw"/>
	        <Scale width="150" height="100"/>
	    </Transform>
	    <Transcode>
	        <Output format="jpeg"/>
	    </Transcode>
	</Profile>
	...
</ImageProcessing>

Metadata synchronizers

The MME includes support for CDText, Gracenote and Musicbrainz metadata synchronizer plugins:

Metadata synchronizer ratings

The container elements for these plugins are used to enable or disable the plugins, and to set their ratings:

Element Attributes Default Description
<cdtext> enabled true Enable and set the rating for the CDText metadata synchronizer.
rating 80
<gracenote> enabled true Enable and set the rating for the Gracenote metadata synchronizer.
rating 71
<musicbrainz> enabled true Enable and set the rating for the MusicBrainz metadata synchronizer that performs internet HTTP queries to the Musicbrainz web service.
rating 71
<musicbrainz_embedded> enabled true Enable and set the rating for the MusicBrainz metadata synchronizer that uses a QDB database.
rating 70

Using synchronizer ratings

The metadata synchronizer container elements have attributes to enable or disable the relevant synchronizers, and to set their ratings. If more than one synchronizer is, the MME attempts to obtain metadata through the synchronizer with the highest rating.

If a synchronizer is not specifically disabled by its configuration element's enabled attribute, it is considered enabled. The example below shows the CDText synchronizer enabled, and the Gracenote synchronizer disabled:

<Synchronization>
    ...
    <MDP>
    ...
        <cdtext rating="80"/>
        <gracenote enabled="false" rating="70">
     </MDP>
</Synchronization>

Gracenote support

Configuration elements for the Gracenote plugin are under the element <MDP>, in element <gracenote>. As well as containing other elements for configuring Gracenote plugins, this element has two attributes that enable or disable the plugin, and rate the plugin if it is enabled.

The elements contained under the <gracenote> element are listed in the table below:

Element Attributes Default Description
<keyfile> empty Path to Gracenote key file.
<databasepath> empty Path to the Gracenote database.
<classical> enabled true See Gracenote classical genres below.

Note: Gracenote implementation requires special licensing. Contact QNX for more information.

Configurable rating for Gracenote server plugin

The MME includes support for a rating for the Gracenote client/server plugin. This feature uses the <MDP>/<gracenote_srvr> element and its sub-element <mountpath> to set a rating for the Gracenote metadata synchronizer plugin.

The table below describes the <gracenote_srvr> element:

Element Attributes Default Description
<gracenote_srvr> rating 88 Rating for the Gracenote server plugin.

The table below describes the <gracenote_srvr> sub-element <mountpath>:

Element Attributes Default Description
<mountpath> empty Path to the Gracenote server; defining this path enables the rating.

To set the rating for the Gracenote server plugin, simply adjust the rating value amd provide the path to the server. For example:

<MDP>
    <gracenote_srvr rating="88">
        <mountpath>/dev/gracenote</mountpath>
    </gracenote_srvr>
    ...
</MDP>

Gracenote classical genres

Setting the <classical> element's enabled attribute to true instructs the MME to extract the Gracenote metadata specified by the <genrekey> elements' genre attributes.

The code sample below shows the explicitly configured genres in the MME configuration file:

<classical enabled="true">
    <genrekey genre="Baroque"/>>
    <genrekey genre="Chamber Music"/>>
    <genrekey genre="Choral"/>>
    <genrekey genre="Classical Guitar"/>>
    <genrekey genre="Contemporary"/>>
    <genrekey genre="Ensembles"/>>
    <genrekey genre="General Classical"/>>
    <genrekey genre="Japanese Classical"/>>
    <genrekey genre="Medieval"/>>
    <genrekey genre="Romantic Era"/>>
    <genrekey genre="Piano"/>>
    <genrekey genre="Renaissance Era"/>>
    <genrekey genre="Strings"/>>
</classical>

MusicBrainz support

The MME supports using the MusicBrainz metadata synchronizer to retrieve metadata from a QDB database, and from the MusicBrainz web service.

Configuration elements for the MusicBrainz metadata synchronizersplugin are under the element <MDP>. These elements enable or disable the two types of metadata synchronization, and rate them plugin if they are enabled. These elements are described with the other metadata sychronizer configuration elements under the Metadata synchronizers heading above.

Path to Musicbrainz database

The <musicbrainz_embedded> element includes the <databasepath> element, which defines the path to the QDB database with the MusicBrainz metadata. The default path defined by this element is /dev/qdb/musicbrainz


Note: Music Brainz implementation requires special licensing. Contact QNX for more information.