Full versus directed synchronizations

The multimedia synchronizer offers the same command for synchronizing content at all scopes, from the entire mediastore, which is known as a full recursive synchronization, or from certain folders or files only, which is known as a directed synchronization.

The sync_start command for the mmsyncclient utility and the mm_sync_start() API function both take an argument that specifies the synchronization path. The following table shows the path argument syntax and the additional options needed to perform synchronizations of varying scope:

Scope	Path syntax	Additional options
Entire mediastore	`"/"`	MMSYNC_OPTION_RECURSIVE (required)
Existing folder	`"/$folderpath/"` You can find a folder's path by looking up its `folderid` in the folders table and then reading the `basepath` field from the result row.	MMSYNC_OPTION_RECURSIVE (optional; use to synchronize contents of all subfolders)
Existing file	`"/$filepath"` You can find an existing file's path by looking up its `fid` in the files table, reading the result row's `folderid` field, and then looking up the folder's path, as when synchronizing a folder.	MMSYNC_OPTION_PASS_FILES (required), MMSYNC_OPTION_PASS_METADATA (required)
New files (including playlists and subfolders)	`"/$folderpath/"` You can find the path of the folder containing the new media files, playlists, and possibly subfolders by looking up the folder's `folderid` value, as when synchronizing a folder.	MMSYNC_OPTION_PASS_FILES (required), MMSYNC_OPTION_PASS_METADATA (required), MMSYNC_OPTION_RECURSIVE (optional; use to synchronize contents of all subfolders)
Entries for an existing playlist	`"/$playlistpath"` You can find a playlist's path by joining the playlists and folders tables on the `folderid` field and then reading the `basepath` field from the join result.	MMSYNC_OPTION_PASS_PLAYLISTS (required)

Note: Mediastores with a single directory level, such as music CDs, don't support synchronizations directed at folders or files. For these mediastore types, synchronizations must be done for the entire device by setting the path to "/". Only mediastores with hierarchical directory structures, such as HDDs, Apple devices, USB sticks, and data CDs, support directed synchronizations. For some of these latter mediastore types, the performance may not be as good when synchronizing the entire mediastore as opposed to targeted folders or files.

When to use directed synchronizations

Directed synchronizations are useful when you need information on certain folders or files but you don't want to do an expensive synchronization of all mediastore content. By restricting the synchronization to a given mediastore path, you can upload some media information to make it available sooner to users, then upload the remaining information later (if needed).

During a directed synchronization, if mm-sync notices a folder that's in the database but not on the mediastore, the folder and its contents are deleted from the database. With this design, a client application can remove a folder from a mediastore and then use a directed synchronization to efficiently remove the folder's information from the database.

Synchronization of individual files is typically done when an application knows about a specific file, such as a file being deleted, added, moved, or renamed. Running the files and metadata synchronization passes on that file will update its information in the database.

Cancelling a synchronization in progress

To improve the end user's ability to browse a mediastore, the mm-sync service supports the MMSYNC_OPTION_CANCEL_CURRENT flag. If mm-sync is performing a synchronization but your client application needs to respond to a user action, such as navigating to another folder in the mediastore file explorer, your application can set this flag when calling mm_sync_start() to cancel the current synchronization and start a new one. Through the mmsyncclient utility, you can issue the sync_cancel command.

The cancellation feature helps reduce resource consumption by allowing you to stop synchronizations that become unnecessary when the user goals change.