Configuring Media Synchronizations

This chapter explains how to configure the MME synchronization behavior.

You can configure the MME synchronization processes to optimize the use of system resources in your environment. Many default values, such as thread priority and folder depth are set as mme startup options. See mme-generic in the MME Utilities Reference for details.

The <Synchronization> elements

The table below lists the first level of synchronization configuration elements under the <Configuration>/<Database>/<Synchronization> element.

Element Attributes Default Description
<Automatic> enabled true Automatically initiate synchronizations on newly detected mediastores. See Automatic and on-demand synchronizations.
<ChangedFilesHaveConstantId> enabled off Determine how MME synchronization handles files whose size or date has changed. See Configurable handling of updated files and folders below.
options all,recursive When automatic synchronization is enabled, determine specific behaviors. See Automatic and on-demand synchronizations.
<DelayAfterMerge> 0 The time, in milliseconds, to delay after completing a synchronization merge operation.
<DeviceDetection> enabled true Automatically detect devices. See Device detection below. This setting is independent of synchronizations.
<Events> off If the folder attribute is set to “on” send events at start and completion of folder synchronizations.
<extensions> empty If sub-elements are specified, synchronize only media files with listed extensions for the specified sub-element. See Filtering synchronization by file type below.
<ForceAccurateAfterFullSync> false Set the mediastores table accurate column to 1 (accurate) after a full synchronization of a mediastore.
<MaxFolderItems> 0 Limit the number of items the MME will synchronize in any one folder. See Limiting the number of items synchronized in a folder below.
<MaxRecursionDepth> 8 The maximum depth (number of folders) to recurse when synchronizing media.
<MaxSyncBuffers> 250 The maximum number of synchronization records in synchronization buffers between the foreground and background synchronization threads.
<MaxThreads> 8 The maximum number of synchronization threads allowed to run in the foreground.
<MonitorPriority> 0 The priority of the device-detection thread.
<PassTwoSetsLastSync> true Have the synchronization metadata pass (pass 2) update the last_sync column in the library table. Caution: see Item selection based on time of entry below.
<PLSS> n/a Container element for playlist configuration elements. See Limiting playlist synchronizations below.
<Priority> 0 The priority of synchronization threads. Set to 0 to use mme startup options. See Configuring synchronization thread priorities below.
<StopOnDbLimit> enabled false Stop synchronization when a database limit has been reached. Default is to not stop a synchronization when a database limit has been reached.
<SyncFileMask> empty Don't synchronize files with this string in their names. See Configurable file skipping: <SyncFileMask> below.
<UnknownTitlesNull> enabled If enabled, use NULL values for unknown file names. If disabled, build file names. See Configurable handling of unknown track titles below.

Note: Configuration elements that are used to configure metadata support are described in the chapter Configuring Metadata Support. These elements include some elements under the <Synchronization> element.

Synchronization thread priorities

Adjusting the priorities of the synchronization threads can have significant impact on system performance. Note that:

Device detection

The <DeviceDetection> element can be used to change the MME's default behavior and have it detect devices only when specifically requested to do so by the client application.

If you have set <DeviceDetection> to false to configure the MME not to automatically detect devices and mediastores, you must call the function mme_start_device_detection() to start device and mediastore detection.


Caution: Failure to call mme_start_device_detection() before attempting any task that accesses mediastores will produce unexpected results that may compromise the integrity of your system.

Automatic and on-demand synchronizations

By default, the MME automatically synchronizes any newly detected mediastore. However, you can configure the MME to require an explicit request from the client application to synchronize a mediastore by setting the <Automatic> element's enabled attribute to false.

This configuration prevents the MME from performing a synchronization on every mediastore change, and makes the client application responsible for selecting what levels of synchronization are done on what mediastores and at what times. The MME waits to synchronize a mediastore until the client application calls mme_resync_mediastore() to request a synchronization.

The <Automatic> element's options attribute

When automatic synchronization is enabled (the default), the <Automatic> element's options attribute determines the tasks to perform when synchronizing a mediastore. It can be assigned a comma-separated list of words. For example, the default configuration, which is to perform all configuration tasks recursively, is configured as follows:

<Automatic enabled="true" options="all,recursive"/>

If the options attribute is not specified, the MME synchronization assumes the default confirguration and performs all synchronization passes recursively.

The words that can be used for the options attribute and their implications for synchronizations are listed below:

Filtering synchronizations

This section describes configuration options for filtering synchronizations. It includes:

Filtering synchronization by storage type

You can configure the MME to not synchronize specified storage types. The <nosync> element accepts <path> elements, which have storagetype attributes.

The <nosync> and <path> elements

The <MSS>/<nosync> element is a container element for one or more <path> elements specifying storage types that should not be synchronized. Two default <path> elements are listed in the table below:

Element Attribute Default Description
<path> storagetype 17 Don't synchronize navigation storage types (NAV/MAP0001).
<path> storagetype 18 Don't synchronize upgrade storage types (UPDATE/DATA01.DAT).

Using <path> elements

If any of the paths specified in the <path> elements exist on a mediastore, the MME:

The paths specified in the <path> elements are relative to the mediastore root folder.

The MME can be configured to not synchronize the following storage types:

The default MME configuration is to not synchronize navigation and upgrade storage types.

Composing <nosync> pathnames

When composing pathnames for the <nosync> element, note that the pathname:

Examples

Navigation storage type:

<nosync>
	<path storagetype="17">NAV/MAP0001</path>
</nosync>

If a mediastore has a NAV/MAP0001 folder on it, the MME marks the mediastore in the database as MMPL_STORAGETYPE_NAVIGATION and does not synchronize it.

For example, if a CD is inserted it will not be synchronized if:

Upgrade storage type:

<nosync>
	<path storagetype="18">UPDATE/DATA01.DAT</path>
</nosynch>

If a mediastore has a UPDATE/DATA01.DAT file on it, the MME marks the mediastore in the database as MMPL_STORAGETYPE_UPGRADE and does not synchronize it.

For example, if a CD is inserted it will not be synchronized if:

Custom storage type:

<nosync>
	<path storagetype="100">SOME/DIRECTORY/FILE.INFO</path>
</nosynch>

If a mediastore has a SOME/DIRECTORY/FILE.INFO file on it, the MME marks the mediastore in the database as 100 (MMPL_STORAGETYPE_CUSTOM1) and does not synchronize it.

For example, if a USB disk on key is inserted, it will not be synchronized if:


Note: In all cases:
  • the mediastore is added to the mediastores table
  • the mediastore content is not synchronized

Filtering synchronization by file type

The MME offers client application developers the ability to choose the file types that the MME synchronizes. To have the MME synchronize a file type, you need only to list the file type in the <extensions> element in the MME configuration file mme.conf.

The table below lists the elements inside the <extensions> element:

Element Attributes Default Description
<library> empty If specified, synchronize only media files with the listed extensions.
<playlists> empty If specified, synchronize only playlist files with the listed extensions.

The default (i.e. elements not specified) is to synchronize all media files. If you specify the <playlist> or <library> element, you tell the MME to synchronize only files that match the extensions listed. You must, therefore, explicitly list the extensions for all the media file types you want to synchronize.

Library extensions require an ftype attribute specifying the ftype field in the library. The ftype must be one of:

For example:

<library>
<!-- Audio types -->
	<extension value="3g2"   ftype="audio"/>
	<extension value="3gp"   ftype="audio"/>
	<extension value="aac"   ftype="audio"/>
	<extension value="cda"   ftype="audio"/>
	<extension value="m4a"   ftype="audio"/>
	<extension value="m4b"   ftype="audio"/>
	<extension value="mp3"   ftype="audio"/>
	<extension value="wav"   ftype="audio"/>
	<extension value="wma"   ftype="audio"/>
	<extension value="ogg"   ftype="audio"/>
	<!-- Photo types -->
	<extension value="bmp"   ftype="photo"/>
	<extension value="gif"   ftype="photo"/>
	<extension value="jpeg"  ftype="photo"/>
	<extension value="jpg"   ftype="photo"/>
	<extension value="png"   ftype="photo"/>

	<!-- Video types -->
	<extension value="m4v"   ftype="video"/>
	<extension value="mp4"   ftype="video"/>
	<extension value="mpeg4" ftype="video"/>
	<extension value="mpg"   ftype="video"/>
</library>

For a current list of extensions, see the configuration file mme.conf.

Playlist extensions do not require attributes. For example:

<playlists>
	<extension value="m3u"/>
	<extension value="pls"/>
	<extension value="wpl"/>
	<extension value="asx"/>
	<extension value="rmp"/>
	<extension value="xml"/>
</playlists>

Configurable file skipping

The <SyncFileMask> element allows you to configure MME synchronization to ignore files based on a specific character string in the file name (including the file extension). This configuration is set in the MME configuration file mme.conf.


Note:
  • The default configuration is to not skip any files based on the file name.
  • There can be only one instance of <SyncFileMask> in the configuration file.

Syntax

Use the regular expressions described in the table below to create the mask defining the character string or strings identifying files to be ignored by the MME synchronization:

Character Meaning
\ Treat the next character as a literal.
^ Begins with.
$ Ends with

The <SyncFileMask> element supports POSIX regular expressions, so you can use AND (&) and OR (|) operators to create your mask.

Examples

Below are some simple examples of masks to ignore files with names that:

Begin with .
<SyncFileMask>^\./<SyncFileMask>. The ., which usually means any character, here means the . (dot) character, because it is preceded by a “\”.
Contain w
<SyncFileMask>w/<SyncFileMask>
End with “roy”
<SyncFileMask>roy$/<SyncFileMask>
Begin with . or end with “.mp3”.
<SyncFileMask>(^\.)|(\.mp3$)/<SyncFileMask>

Note: If you create a complex mask with multiple operators, you should make sure that you don't configure the MME to ignore files that you want synchronized.

Configurable handling of updated files and folders

The <ChangedFilesHaveConstantId> element determines how, during a file and folder discovery synchronization pass, the MME handles a media or playlist file whose size or date has changed since the previous file and folder discovery pass.

Default behavior

The default MME behavior is to consider a file or folder whose size or date has changed as new, and to synchronize it accordingly, assigning it a new file ID (fid).

Behavior with <ChangedFilesHaveConstantId> enabled

If the <ChangedFilesHaveConstantId> enabled attribute is set to true, the MME's file and folder discovery synchronization pass does not consider files and folders whose dates or sizes have changed to be new files or folders, and:

Thus, if you configure the MME to maintain the file ID of a file or folder whose sizes or date has changed, to determine if file metadata is accurate, you must check its accurate field. If the field is 0, then the file requires a metadata synchronization pass.


Note: If media files have not been successfully synchronized during the metadata pass, or playlist files have not been synchronized during the playlist synchronization pass, the accurate field for these files will be 0, regardless of the <ChangedFilesHaveConstantId> configuration.

Playlist synchronization behavior

Playlist synchronization differs from media file synchronization:

Setting limits on synchronizations

This section describes configuration options for limiting the folders and items the MME synchronizes. It includes:

Limiting the entries in the library table

You can configure the maximum number of entries you allow at one time in the MME library table, for any given slot.

To limit the number of entries permitted in the MME's library table, update the value in the slots table column max_lib_entries with the maximum number of entries permitted for the mediastore type associated with a slot. For example, to set the maximum for the mediastore “Hardrive” to 4000 entries:

INSERT INTO slots(path,zoneid,name,slottype,max_lib_entries)
    VALUES('/media/drive', 1, 'HardDrive', 3, 4000);

Note:
  • A limit on entries can only be set for BFS (Block File System) mediastores (HHD, USB, SD cards, data CDs, DVDs and PFS devices).
  • If the max_lib_entries column is 0, there is no limit to the number of entries permitted for the mediastore in the slot.
  • The MME does not include device file IDs when it counts the number of entries in the library table.
  • If the MME is configured to add now playing entries to the database (<UpdateLibraryFromNowplaying enabled="true"/>) and an external CD changer plays tracks that are not in the database, the MME will add entries for these track without checking the limit, and the number of entries in the library table may exceed the set limit. To prevent this situation from occurring, set the limit to a value higher than the maximum number of tracks supported by the mediastore.

See also the events associated with maximum entries in the library in the MME API Library Reference:

Limiting the number of items synchronized in a folder

Excessively large numbers of files in folders on a mediastore can make using that mediastore very slow, and cause poor response to synchronization operations, such as changing of priority folders or determination of changes to the mediastore.

The MME includes the <Database>/<Synchronization> configuration element: <MaxFolderItems>. This element limits the number of items the MME will synchronize in any one folder.

For information about limiting folder synchronization on iPods, see Limiting the number of iPod folders synchronized below.

MME behavior when <MaxFolderItems> is implemented

Note the following about MME behavior when <MaxFolderItems> is implemented:


Note: When the MME is configured to limit the number of items it synchronizes in any one folder (<MaxFolderItems> is set to non-zero), the filesystem readdir() determines the items that the MME sees. The MME does not see any items in a folder that are beyond the limit specified by <MaxFolderItems>, and does not consider them when performing folder change checks. These unseen items may include media files, playlist files, folders, and files that have been filtered out or that, by definition, the MME does not handle (i.e. .xls files).

Adding or deleting items from a folder on a mediastore affects the presentation of the items to the MME, depending on the operation of the filesystem readdir() function, and may cause unexpected changes in the MME database.


Limiting playlist synchronizations

Playlists created by end users can be extremely large and processing them can strain limited sytem resources. The <MaxBytes> and <MaxLines> configuration elements in the <PLSS> element can be used to set a limit to the memory the MME will use to synchronize playlists, as well as the number of lines in a playlist the MME will process:

Element Attributes Default Description
<MaxBytes> 500000 The maximum number of bytes to allocating during processing of a playlist.
<MaxLines> 5000 The maximum number of lines (files listed) permitted for a playlist. If used, this value overrides the value set by CONFIG_MAX_PLAYLIST_LINES in config.h.

Configurable handling of unknown track titles

You can configure how the MME handles entries for unknown track titles in the MME database, by setting the attribute for the <Synchronization> element <UnknownTitlesNull>.

Depending on the attribute setting for this element, the MME will either:

The default setting for <UnknownTitlesNull> is “enabled” — use NULL and do not attempt to build titles for tracks with unknown titles. If <UnknownTitlesNull> is set to disabled, the MME will build names for tracks, based on the type of mediastore on which the track is found, as follows:

This feature uses language strings in mme_data.sql to fill in information in the following fields in the languages table:

iPod synchronization

This section describes configuration options specific to iPod synchronizations. It includes:


Note: iPods devices may hold a very large number of media files. The preferred method for working with iPod devices is to not synchronize them, but instead to use the MME's explore API functions to explore specific folders as requested by the end user.

For more information, see the chapter Working with iPods in the MME Developer's Guide.


The <ipod> elements

The <MSS>/<ipod> element is a container element for elements specifying behaviors for iPod synchronizations. It contains the elements listed in the table below:

Element Attributes Default Description
<synced_folders> limit 32 The maximum number of synchronized iPod folders permitted in the MME library. Set the limit attribute to 0 (zero) for no limits. See Limiting the number of iPod folders synchronized below.
<auto_sync> permitted false Override the MME's default iPod synchronization behavior, and automatically synchronize iPod devices on discovery. See Enabling automatic and complete iPod synchronizations below.
<full_sync> everything false Override the MME's default iPod synchronization behavior, and synchroniz all paths in order to avoid redundant work. See Enabling automatic and complete iPod synchronizations below.

Limiting the number of iPod folders synchronized

In order to better manage its database, the MME provides a control for limiting the number of folders with files added to its database during the synchronization of iPod devices. This limit is set by the .../<Synchronization>/<MSS>/<ipod>/<synced_folders> element. The default is 32 folders. A value of 0 means no folder limit.

When it synchronizes an iPod device, the MME synchronizes all the requested folders on the iPod. There is no limit (other than available space for the MME database) to the number of folders or files synchronized. However, on completion of the synchronization, the MME checks for old folders with files from previous synchronizations of the newly synchronized iPod device and, if necessary, it deletes folders from old synchronizations to bring the total number of folders synchronized to be equal to or as close as possible to the value specified in <synced_folders>.

For example, assuming the value of 32 for <synced_folders>:

Similary, assuming the default value of 32 for <synced_folders>, if a previous synchronization of an iPod yielded 40 folders, and the new synchronization of the same iPod (or, what is more likely, of a portion of the iPod) yields 36 folders, the MME will delete the 40 folders from the previous synchronization, leaving the information and metadata for the 36 new folders in the MME database.

Enabling automatic and complete iPod synchronizations

The MME release implements two new configuration elements that allow you to change the MME's default behavior when it synchronizes iPods. Both these elements are contained in the <MSS>/<ipod> element:


Note:
  • The MME's explorer API is the preferred method for discovering and accessing files on iPods. If you synchronize an iPod device, it is best to use directed synchronization so that you synchronize only the directories requested by the user.
  • Setting <auto_sync permitted="true"/> and <full_sync everything="true"/> to have the MME automatically synchronize the complete contents of iPod devices can be useful to demonstrate iPod integration in the MME, but this configuration is not recommended for production environments.

For more information about synchronizing iPods, see:

Displaying the .FS_info folder contents during iPod exploration

The <Configuration>/<Explorer> element sets behavior characteristics for the MME's Explorer API. It contains the <MSX> element, which in turn contains the <ipod> element.

The <ipod> element has one attribute, show_all, which determines whether the .FS_info folder and its contents are visible during exploration of an iPod. The default is false: do not show the .FS_info folder and its contents.

Plugin support

Like the MME, plugins can take their configuration values from the MME configuration file, mme.conf, or from built-in defaults. Plugins should provide their built-in defaults so they can be used if the MME configuration file is not specified or available.

The MME configuration file includes a reserved media data (MDP) plugin configuration area under the <Synchronization>/<MDS>/<plugin name>. In this part of the configuration file, you may create your own structure for assigning your initial configuration, using the <dvdifo> elements as an example.

DVD IFO parser support

The MME has configuration elements to allow control over DVD IFO parsing and for adding DVD device types to the library. These elements are the same for DVD-audio and DVD-video mediastores, and are found under the elements <Configuration>/<Database>/<Synchronization>/<MDP>/<dvdifo>/<dvdaudio | dvdvideo>. They are described in the table below.

Element Attributes Default Description
<devicefid> create true Determines if a device file ID for the entire mediastore is added to the library during synchronization.
<chapterfids> create true Enables or disables the IFO parser. If the IFO parser is enabled, synchronization will find individual tracks on the DVD.

Item selection based on time of entry

The MME includes a configuration option that you can set to prevent the synchronization metadata pass (pass 2) from updating the last_sync column in the library table. This capability allows you to select entries from the library table based on the time the entries were first entered in the database by the synchronization file and folder discovery pass (pass 1), instead of based on when the metadata for these entries was updated.

The default for the <PassTwoSetsLastSync> element is true: update the last_sync column during the synchronization metadata pass.

Synchronization constants

The table below lists the default synchronization management constants.

Constant Value Description
CONFIG_DEF_SYNC_AUTOMATIC true Automatically synchronize mediastores on detection.
CONFIG_DEF_THREAD_PRIORITY 0 The priority for synchronization threads. Set to 0 to use mme startup values. See Configuring synchronization thread priorities above.
CONFIG_DEV_DVDA_FID_CREATION true Add a device file ID for the entire mediastore to the library during synchronization.
CONFIG_DEV_DVDA_IFO_PARSING true Enable or disable the IFO parser. If the IFO parser is enabled, synchronization will find individual tracks on a DVD-audio.
CONFIG_DEV_DVDV_FID_CREATION true Add a device file ID for the entire mediastore to the library during synchronization.
CONFIG_DEV_DVDV_IFO_PARSING true Enable or disable the IFO parser. If the IFO parser is enabled, synchronization will find individual tracks on a DVD-video.
CONFIG_DEF_DVD_SKIP_DURATION_ZERO true Don't synchronize entries (i.e. DVD-video chapters) with a duration of 0 milliseconds.