![]() |
![]() |
![]() |
![]() |
This chapter explains how to synchronize media on these mediastores with the MME database.
![]() |
This chapter describes the MME default behavior. For information about how to configure the MME's synchronization behavior, see the chapter Configuring Media Synchronizations in the MME Configuration Guide.
For information specific to synchronizing iPods, see “Synchronizing iPods” in the chapter Working with iPods. |
Mediastore synchronization is the process by which the MME examines mediastores and updates its database with information about the media tracks on the stores and with the metadata for these media. Information and metadata includes, but is not limited to, media type and format (audio, video, etc.), track name and language, genre, cover art, and so on. This information and metadata is essential for the MME and client application to be able to find, organize and play media, and to display meaningful information to the end user.
The MME can be configured to automatically synchronize mediastores on system startup and on mediastore insertation, or to wait for requests to synchronize a mediastore. The default MME configuration is to automatically synchronize all mediastores except iPods. Automatic synchronization is always disabled for iPods; the MME only synchronizes these devices when it is explicitly requested to do so.
When it prepares to synchronize a mediastore, the MME selects the most appropriate synchronizer for the mediastore. The selection criteria include ensuring that the MME obtains the most accurate and complete metadata available for the files on the mediastore. For example, for a CDDA:
The MME includes a table, metadataplugins, that lists the different metadata synchronizers available to the MME. Its fields are:
The mediastores table implements the field metadatapluginidto identify the metadata synchronizer used for the mediastore, and thereby identify the origin of the metadata for the mediastore. If more than one metadata synchronizer is required for the mediastore, the metadatapluginid field in the mediastores table is set to 0 (zero).
For information about configuring ratings for metadata synchronizers, see “Metadata synchronizer ratings” in the MME Configuration Guide chapter Configuring Metadata Support.
For most mediastores, the MME uses a multiple synchronization passes process. This multiple pass process reduces the delay time between the insertion of a mediastore and readiness to play media by separating synchronization into separate passes, as follows:
The client application can register to receive synchronization events and use these events to monitor the progress of the MME synchronization activities. These events tell the client application what level of information is ready for use:
Each synchronization pass proceeds as follows:
This process ensures that all directories that share a common parent node are synchronized before directories deeper in the tree are examined. If you cancel a synchronization in progress, some directories may be fully synchronized while others may not have any of their contents synchronized.
Illustration of the order in which the MME synchronizes mediastores.
The MME maintains synchronization flags in its database to track the history of synchronization status of mediastores and folders. The column, syncflags, in the mediastores table is used to indicate which synchronization passes have been completed on a particular mediastore. It consists of three-bit fields, where a set value means the particular synchronization pass has been successfully completed:
For example, a value of 0 from this field means that no synchronization has completed, and a value of 5 (101) means that the file and playlist passes have been completed, but that the metadata has not been completed. A value of 7 (111) indicates that all synchronization passes have been completed.
These flags are not cleared if the device is made unavailable. When a disk is moved out of the active slot while in a multi-disk changer, the disk is not made unavailable, only inactive. Therefore this action does not clear any existing synchronization flag values.
For detailed information about what the MME does at each synchronization pass and a complete list of synchronization events, see the section “Synchronization events” in the chapter MME Events.
![]() |
The MME sets the synchronization flags when the synchronization process has finished inserting or updating the immediate contents of a folder. This behavior means that the client application can monitor the synchronization flags knowing that once the flag is set the contents for a mediastore folder in the MME database will not change. |
Synchronization function calls are all nonblocking; they leave the client application free to start media playback or perform other tasks.
This design means that the client application does not need to wait for synchronization to complete before it begins playing media for the end user. It can check for completion of the first synchronization pass and begin playing media while the MME synchronization process is updating its database with metadata and creating playlists.
If the MME receives a request to synchronize a mediastore but it does not have a thread available to perform the synchronization, it places the request in its “synchronization pending” queue until a thread becomes available.
Queued synchronizations can be canceled just like active synchronizations, by calling mme_sync_cancel().
To optimize system performance when starting playback on slow devices, the MME performs a foreground synchronization merge as soon as it has a file ID (fid) marked as a “first fid” (first playable) file. This action reduces the time required to start playback on slow devices.
You can configure the MME synchronization process to:
For efficient synchronization, you should configure your MME to skip files that begin with “.”, and to synchronize only specified file types. For more information, see the chapter Configuring Media Synchronizations in the MME Configuration Guide.
![]() |
The MME automatically always skips the files . (current directory) and .. (parent directory) because they would cause recursion. |
When it is completing synchronizations of a mediastore, the MME may attempt to cleanup unused references to metadata if:
The cleanup proceeds as follows:
The cleanup may:
![]() |
To prevent a track session “leak” — an accumulation of useless track sessions in the trksessions table — when a mediastore is pruned from your database, you should also delete from your database all track sessions that use tracks on that mediastore. For information about how to delete track sessions, see “Deleting track sessions” in the chapter Playing Media. |
The MME can be configured to deliver events when it starts and completes a folder synchronization. This capability may be used in association with prioritized folder synchronization, or as an alternative to polling a folder's synced column to monitor the progress of its synchronization. See the chapterConfiguring Media Synchronizations in the MME Configuration Guide for information about configuring the MME to deliver folder synchronization events.
The order of delivery of folder synchronization events for a specific folder is:
The MME delivers the MME_EVENT_MS_SYNC_FOLDER_STARTED event synchronously when it starts synchronization of a folder. At the same time, the MME queues the two other folder synchronization events for delivery, so that database changes associated with these two events are completed before the events are delivered.
This behavior means that it is normal for the client application to see MME_EVENT_MS_SYNC_FOLDER_STARTED events for child folders before it sees the MME_EVENT_MS_SYNC_FOLDER_COMPLETE event from the parent folder.
![]() |
Because the events MME_EVENT_MS_SYNC_FOLDER_COMPLETE and MME_EVENT_MS_SYNC_FOLDER_CONTENTS_COMPLETE are queued, they consume one slot in the synchronization merge buffer space, if this space is used. |
All folder synchronization events use the structure mme_folder_sync_data_t to deliver information, but all synchronization events do not use all members of this structure. The different folder synchronization events deliver data in mme_folder_sync_data_t as follows:
See also the documentation for the individual events.
Playlist synchronization converts playlist table entries into an ordered list of file IDs and places these file IDs in the playlistdata table.
Playlist synchronization includes the following behavior when finding a file in the MME database to match a playlist file:
![]() |
If a playlist file's timestamp or file size changes from what it was during the file synchronization pass, the synchronization process:
This new entry in the playlist table is not automatically synchronized. It requires a playlist synchronization pass to produce its ordered list of file IDs in the playlistdata table. |
To synchronize a specific playlist (rather than synchronizing all playlists on a mediastore) call the function mme_playlist_sync().
The MME supports the following kinds of synchronization:
The default behavior for the MME is to automatically initiate full, recursive synchronization on detection of a new mediastore. With full, recursive synchronization, the MME scans all files on the mediastore and updates the MME database with all relevant information and metadata. To initiate full, recursive synchronization, call mme_resync_mediastore().
Directed synchronization synchronizes only the folders and files on a specified path on a mediastore. This capability is particularly useful if you want to synchronize part of a large mediastore in order to start playing its contents, then synchronize the rest or other parts of the mediastore in the background, or even at a later time.
To initiate directed synchronization, call mme_sync_directed().
To improve the end user's ability to browse through a mediastore, such as an iPod, the MME makes available the MME_SYNC_OPTION_CANCEL_CURRENT flag. If the MME is performing a synchronization on a mediastore and the HMI needs to start a new directed synchronization (because, for example, the user has started browsing through a different folder), the HMI can use this flag when calling mme_sync_directed() to tell the MME to cancel the current synchronization and queue the new directed synchronization request for execution.
![]() |
Directed synchronization is available only for mediastores with hierarchical directory structures: HDDs, iPods, USB sticks, data CDs, etc. It is not available for mediastores, such as music CDs, that have a single level directory structure. |
If a directed synchronization is unable to find on a mediastore a folder that is in the MME database, it deletes the folder and its contents from the MME database.
This behavior means that the client application can remove a folder from a mediastore, then use directed synchronization to remove this folder from the MME database.
File synchronization allows the client application to have the MME synchronize only a specified file. This capability is typically used when the client application knows that a specific file change has occurred: a file has been deleted, added, moved, or renamed.
File synchronization can be performed only with certain media store types. For example, this functionality it is not supported for use with iPods.
To initiate file synchronization, call mme_sync_file().
The MME database tables listed below are updated during the synchronization process:
The MME library table provides a single view of metadata for different metadata formats (iTunes, Windows Media). If a metadata field is not supported in a file format, that field is simply left empty.
If the MME synchronization processes cannot find a title in a file, the MME sets the library title field to NULL. The client application can check a file's title field. If the field is set to NULL, it knows that the file does not have a decodable title, and it can handle the situation appropriately.
The MME has a customizable table, where you can add your own information tied to the MME library tables and access it as suits your needs. See the file mme_custom.sql for a sample schema.
For detailed information about when during the synchronization process specific tables are updated, see the section “Synchronization events” in the chapter MME Events.
The default configuration for the MME is to automatically detect mediastores and to automatically initiate their synchronization, updating the MME library and other tables with all relevant information and metadata. As a minimum, your client application should register to receive synchronization events in order to monitor the status and progress of synchronizations. You can also:
For information about how to configure the MME's synchronization options, see the chapter Configuring Media Synchronizations in the MME Configuration Guide.
You can compare the lastseen and last_sync fields in the mediastores table to determine if you need to resynchronize a mediastore, and skip unnecessary resynchronizations. Both fields use the MME's internally derived time.
The lastseen field contains the time when the mediastore was last inserted into the MME, and the last_sync field contains the time of the mediastore's most recent synchronization. If the lastseen field is greater than the last_sync field, the mediastore may have changed since the last synchronization — it left the system and returned, and could have been changed: it should be resynchronized.
The MME delivers the event MME_EVENT_SYNC_SKIPPED to indicate that it found a mediastore that could have been synchronized, but did not synchronize it for one of the following reasons:
The client application can instruct the MME to synchronize a specified folder first. You can use this feature to reduce the time required to make metadata available or start playback of media requested by the end user.
This capability can be useful when your client application is displaying the current view of synchronized directories during a synchronization process during startup, or when a new mediastore is inserted. If a user selects a displayed directory before the MME has completed synchronization, your client application can set the selected directory as a priority folder. The MME will synchronize this directory first and the client application can update its display for the user as it receives MME_EVENT_MS_UPDATE events.
Call mme_setpriorityfolder() to tell the MME to pause any ongoing synchronizations and synchronize the specified folder before resuming the rest of the synchronization.
The priority folder feature:
If during a synchronization you set a priority folder, and you then set a new priority folder before synchronization of the first priority folder has completed, in most, but not all cases, the MME will:
In the event that you attempt to set a new priority folder before the synchronization process has checked for the first priority folder you requested, the MME will drop the first priority folder request, and start synchronization with the newly requested priority folder. The first priority folder requested will be synchronized with the other folders in the general synchronization process.
You can instruct the MME to remove specific files from its database. To remove information for a specific file from the MME database, call mme_sync_file() with the new_msid set to 0 and new_filename set to NULL.
When the MME copies or rips a file, it places the file ID fid for the destination file in the copied_id field for the source file in the library table. If at a later time the destination file is deleted, this copied_id field becomes invalid, because it points to a file that is no longer in the MME library.
Checking the validity of copied_id fields is potentially a very costly (time-consuming) operation and is not performed by normal synchronizations. However, the options parameter for the synchronization functions mme_sync_directed() and mme_resync_mediastore() includes a flag (MME_SYNC_OPTION_CLR_INV_COPIED) that you can set to force the synchronization to check the validity of copied_id fields and set all invalid instances of this field to zero (file not copied).
To clean up invalid copied_id fields, call either mme_sync_directed() or mme_resync_mediastore() with the mask for the options parameter set to MME_SYNC_OPTION_CLR_INV_COPIED. With this option set, the synchronization operation will clean up invalid copied_id fields at the end of the file synchronization pass, if the following are true:
![]() |
Calling either mme_sync_directed() or mme_resync_mediastore() with MME_SYNC_OPTION_CLR_INV_COPIED set will clean up invalid copied_id fields for the entire MME database, not just for the library entries that correspond to the mediastore being synchronized. This operation can take a long time, and you should use it only after deleting from your database media files that were created by a copy or ripping operation (using the mme_mediacopy_*() functions). |
If you encounter problems with a folder and its child items (files and subfolders) after a synchronization, you may be able to use mme_sync_db_check() to repair inconsistencies between the MME database and mediastores with POSIX compliant filesystems.
For more detailed information about checking for and correcting inconsistencies, see the information provided with the mme_sync_db_check() function in the MME API Library Reference.
The MME's file synchronization pass deletes from the MME database items no longer found on their mediastore before adding new items.
A client application may use the seen columns in MME tables to determine if a file on a mediastore can be shown to end-users. Only files marked as “seen” should be shown (files with their seen column set to 1, meaning that the file synchronization pass found them on the mediastore).
Client applications should show end-users only files that have been found on a mediastore by the file synchronization pass, using logic based on timestamps: if the last_sync value of a library table entry for a file is greater than the lastseen time of the mediastores table entry for the mediastore that file is on, the file is on the system (because the entry has gone through a first synchronization pass since the mediastore was last placed in the system).
The MME supports Gracenote classical music metadata in its library. To enable support for Gracenote classical music:
For more information about how to make these changes, see “Gracenote support” in the MME Configuration Guide chapter Configuring Metadata Support.
The fields described in the table below are used in the MME library to support Gracenote classical music metadata. You should use the metadata in these fields primarily for display purposes, because at this time many classical music entries in the Gracenote database do not carry sufficiently precise metadata.
A single field in the MME library table may hold more than one instance and type of metadata, presented as comma separated strings. For example, when the artist field in the MME library table is built from Gracenote metadata, it can contain zero or more soloists followed by zero or one conductor; if, for instance, the field contains two names, it is not possible to deduce whether these two names are for two soloists or for a single soloist and a conductor.
In the table below, mandatory metadata is shown in square brackets: [mandatory string], and optional metadata is shown in curly braces: {optional string}.
Field | Content |
---|---|
artist | 0 or more {soloist(s)}, 0 or 1 conductor |
composer | composer short name |
ensemble | 0 or 1 {ensemble}, 0 or 1 {choral ensemble} |
opus | [opus title] {In key}, {opus number}, {catalogue number}, {opus nickname} |
title | [movement number], [movement tempo or text title] |
The remaining fields in the MME library hold their normal values.
![]() |
For Gracenote classical music, the MME doesn't use the soloist_id or conductor_id fields, because the Gracenote metadata doesn't provide unique identifiers for these metadata. |
![]() |
![]() |
![]() |
![]() |