The <Configuration>/<Database>/<Synchronization> element defines the settings that control synchronization, including the optimization of system resources, the file types to include or exclude, the mapping of metadata provider fields to database fields, and policies for media data and playlists.
The elements that define the synchronization settings make up the bulk of the configuration file. It's helpful to visualize the synchronization elements based on the area of functionality they control.
| Tag name | Attribute | Default | Description |
|---|---|---|---|
| <Priority> | 0 | Sets the priority of the foreground synchronization threads. A setting of 0 enforces the default priority, which is the same priority that the mm-sync service uses at startup. Nonzero values assign absolute priorities. | |
| <MergePriorityAdjust> | 1 | Sets the synchronization merge thread's priority adjustment. This value is added to the synchronization thread priority to derive the merge thread priority. The default behavior is to add 1 to the synchronization thread priority. | |
| <MaxThreads> | 8 | Sets the maximum number of foreground synchronization threads permitted to run at a time. | |
| <MaxRecursionDepth> | 8 | Sets the maximum directory structure depth to recursively visit when synchronizing a mediastore. This setting also applies to priority folders. | |
| <MaxSyncBuffers> | 250 | Sets the maximum number of synchronization records in the buffers between the foreground and background synchronization threads. More buffers increases memory usage, but speeds up synchronization. |
| Tag name | Attribute | Default | Description |
|---|---|---|---|
| <ChangedFilesHaveConstantId> | enabled | off | When enabled, ensures media and playlist files with a changed size or modification date keep the same ID value in the database. In such cases, the files and playlists table entries for the changed items have their accurate flags cleared, but there's no other indication that these items have changed. This setting helps limit the database size by preventing new rows from being created whenever a file is changed, which happens when the ID values are not kept the same. For more information on how this setting impacts synchronization, see Maintaining constant IDs for updated files and playlists. |
| <StopOnDbLimit> | enabled | false | Controls whether or not synchronization stops when a database limit is reached. |
| Tag name | Attribute | Default | Description |
|---|---|---|---|
| <Events> | folder | trimonly | Controls what optional synchronization events are delivered. Currently, only the delivery of folder events is controllable. Acceptable values are on, off, and trimonly. Use trimonly to send folder events only when a folder object (file, folder, playlist) is deleted. Use on to send events following folder object additions, modifications, and deletions. Use off to disable event sending. |
| <MaxFirstFidEvent> | 1 | Sets the maximum number of MMSYNC_EVENT_MS_SYNC_FIRST_EXISTING_FID events sent during synchronization. These events are sent during the files pass when mm-sync finds a media file that's playable and is already in the database. A setting of n causes mm-sync to return this event for the first n existing files found. |
| Tag name | Attribute | Default | Description |
|---|---|---|---|
| <SyncFileMask> | (empty) | Defines a POSIX regular expression (regex) pattern for naming files you do not want synchronized. Only one SyncFileMask can be specified. The default setting is an empty mask, meaning no files will be skipped during synchronization. | |
| <NonMediaItems> | Controls the prescan done on each folder. You can configure mm-sync to skip the synchronization of folders found to have too much nonmedia content during the prescan. The prescan parameters are set through the elements contained in the <NonMediaItems> element. | ||
| <NonMediaItems>/<MaxItems> | 0 | Limits how many nonmedia files can be found in a folder before that folder is skipped from synchronization. A setting of 0 disables this limit. | |
| consecutive | false | Sets whether the limit of nonmedia files is a consecutive file limit. The file order is generally not guaranteed, so using a consecutive limit could yield nondeterministic results. When this setting is disabled, as is the default, MaxItems is a limit of total files. | |
| <NonMediaItems>/<PrescanLimit> | 0 | Limits how many files can be scanned when searching for media content in a folder. A setting of 0 disables this limit and forces the entire folder to be scanned; nonzero values enforce a limit on the files scanned. | |
| <MaxFolderItems> | 0 | Controls the maximum number of items read from a folder. This limit excludes "." and "..", but includes any items whose filenames match the pattern in <SyncFileMask>. A setting of 0 disables this limit; nonzero values enforce it. | |
| <MaxMediaStoreItemsConfiguration> | Controls the maximum number of items read from mediastores. For each mediastore on which you want to impose a limit of items read, define a separate <MaxMediaStoreItems> element. | ||
| <MaxMediaStoreItemsConfiguration> /<MaxMediaStoreItems> | 100 | Limits the number of items read from a mediastore. This limit excludes "." and "..", but includes any items whose filenames match the pattern in <SyncFileMask>. A setting of 0 disables this limit; nonzero values enforce it. | |
| mediastore | (none) | Names the mediastore the limit of items read applies to. | |
| <extensions> | Specifies which file extensions are supported, allowing you to filter the synchronization of content by file type. This element contains the <playlists> element, which lists supported playlist extensions, and the <library> element, which lists supported media file extensions. Files with unlisted extensions aren't synchronized. |
Some synchronization elements contain many other elements that collectively configure helper utilities such as plugins and playlist synchronizers used by mm-sync to perform advanced tasks.
| Name | Description |
|---|---|
| <ConfigurableMetadata> | Defines the metadata provider fields that are copied into specific database fields. The mm-sync service has no special knowledge of this metadata but will pass it along to the database. |
| <MSS> | Contains elements that configure mediastore synchronizers (MSSs). Currently, only the synchronizers for Apple devices can be configured in this area. |
| <PLSS> | Defines resource usage limits and filename-matching parameters for playlist session synchronizers (PLSSs). This element can also name a nondefault configuration file for the library that mm-sync uses to synchronize playlists. |