Synchronization passes

The mm-sync service synchronizes media information in three passes known as the files, metadata, and playlist passes. The default behavior is to perform all three passes but you can perform any subset of these passes by setting the right flags when requesting a synchronization.

Each pass uploads different information into the database. For the metadata pass, the tables updated depend on the media types of the files being synchronized. The following table shows the database tables updated during the three synchronization passes, based on the default database schema:
Pass Media type Tables updated
Files All files, folders, playlists, mediastore_metadata
Metadata Audio audio_metadata, genres, artists, albums, mediastore_metadata
Video video_metadata, genres, artists, mediastore_metadata
Photo photo_metadata, mediastore_metadata
Playlist All files, folders, playlists, playlist_entries, mediastore_metadata

Files pass

The files pass retrieves basic file information and then updates the files, folders, and playlists table entries for all media files and playlists found on the device. In this pass, mm-sync removes from the database any files, folders, or playlists that used to exist but are no longer on the device. For deleted playlists, mm-sync also removes their playlist entries.

No metadata has been gathered at this point, but the file information obtained lets you begin playing media.

Note: At the end of each pass, mm-sync updates the syncflags and last_sync fields in the mediastore_metadata table to mark synchronization progress.

Metadata pass

The metadata pass retrieves metadata associated with the files on the device. Metadata can include running time, display details, author, and other creation and playback information. The table entries that get updated depend on the media types (audio, video, or photo) of the mediastore files whose metadata is synchronized.

In the database schema definition file, you can change the tables that hold the metadata for different file types. The default configuration splits metadata for audio, video, and photo files into different tables, but you could define more or fewer tables to store the metadata, depending on the file types and media information you want to support. The files table is always present, but you can add fields to store more information in this table.

After the metadata pass, metadata is accurate for the mediastore files being synchronized, and you can display this information to the user.

Playlist pass

The playlist pass converts playlist entries into ordered lists of file IDs, which are stored in the playlist_entries table.

In this pass, mm-sync tries to match the filename in each playlist entry with a filename in the database. For playlists on devices with media-based filesystems, mm-sync searches for up to 100 database matches of a playlist filename (any matches beyond 100 matches are ignored), and then associates the playlist entry with the database file that is the best match.

Note: For new playlists, you must synchronize the playlist file by running the files pass with the appropriate synchronization path before running the playlist pass. This is because the new playlist must have an entry in the playlists table for the playlist pass to be able to resolve the file IDs of the playlist's entries.

If a playlist entry refers to a file no longer on the device, mm-sync doesn't delete the entry but instead sets its file ID (fid) to 0. To delete playlist entries that refer to nonexistent files, you must remove the names of those files from the playlists on the device and then run the playlist pass again.

When this pass has completed, you can display and use playlists.