Application icon

Sync Files

This document describes version 5.x of the Sync File utilities. Version 5 is a complete rewrite of the UI and includes new syncing capabilities.

This suite contains actions to convert files via Permute 3 and XLD and to synchronize metadata between two copies of files.

If you are using the Permute 3 functionality of these actions please note that version 3.6.4 or later is required. Version 3.6.4 enabled the ability of Yate to specify the destination folder. You should read the Working With Permute 3 Presets topic to learn about matching presets based on audio properties.



Convert Files

Sync Files Utility - Overview

Sync Files Utility

Sync Files With Default Profile

Configuring Permute 3

Permute 3 Preset Information Display

Permute 3 Best Match

XLD Profile Information Display

Ignoring Files and Folders

Deleting Extra Folders

Content List, Requirements & History





Convert Files

This action is used to convert all selected files to a different file format using Permute 3 or XLD. Note that all metadata is preserved. The action only processes selected files. The panel displayed if you have both Permute 3 and XLD on your Mac, is as follows:



Permute Panel

The Converter setting is only displayed if you have both Permute 3 and XLD on your Mac.

If you have Permute 3 on your Mac the Permute 3 preset and Permute 3 best match settings will be displayed. If you have XLD on your Mac, the XLD preset and XLD profile settings will be displayed. If you have both applications on your Mac, only the settings appropriate to the selected Converter will be enabled.

When Permute 3 is the chosen or defaulted converter, Permute 3 preset must contain the name of a preset. Active presets can be chosen from the menu button (down triangle) to the right of the field. You can also edit the field and type the value.

When Permute 3 is the chosen or defaulted converter, you can check the Best match checkbox will enable the ability to attempt to match the bit depth in an audio file to a preset. More information can be found in Permute 3 Best Match.

When XLD is the chosen or defaulted converter, you must specify a preset or profile name. When the XLD preset and XLD profile settings are enabled there will be a menu button (down triangle) to the right of each field which display the value names. You can also edit the fields and type the value. Note that if you eneter an name in one of the fields, the other will be disabled. Simply delete the contents of a field to re-enable both.

Convert files in place places the new files in the same folder as each source file. When Convert files in place is not checked you must place a folder path into the Destination folder setting. You can display a panel to select the folder by double clicking in the Setting column of the Destination folder row or from same row's context menu's Get Folder Path item.

This action attempts to preserve filenames and will not overwrite existing files unless you enable the Overwrite existing files setting. The setting will not effect files loaded in Yate or files produced during the execution of the action.

By enabling the Delete source files setting, you can delete source files after a successful conversion. An attempt is first made to delete files by moving them to the trash. If the files cannot be moved to the trash they will be permanently deleted.


The help button displays context sensitive help for the selected row. To display this document, hold down the Option key when clicking on the help button.


The P3 Preset Info button, only displayed when appropriate, displays information on the available Permute 3 presets. The format of the panel displayed is discussed in Permute 3 Preset Information Display.

The XLD Profile Info button, only displayed when appropriate, displays information on the available XLD profiles. The format of the panel displayed is discussed in XLD Profile Information Display.

The Convert Files button will start the process to convert the files. When done a panel will appear displaying the number of errors and the location of the produced log file. There will be a View Log button to display the produced file in the Log Viewer. Note that the log file is overwritten after each conversion. The log file displays the steps that were performed for each audio file and will contain the final name of each produced file. A produced file's name might have a duplicate indicator appended if the source filename was already used.

After a conversion deleted files will be removed from the main window and newly created files will be loaded and selected. With the exception of the encoder related fields, all metadata will have been copied from the source files to the produced files.



Back to top of page





Sync Files Utility - Overview

Many users have two or more activate copies of their audio files. Sometimes the copy is a one-to-one copy and sometimes the audio files are encoded differently.

These actions provide a means of syncing any changes to the metadata in the originals to a copy. The sync trigger is simple ... the two files have different modification dates. When a sync occurs, metadata is copied from the source file to the destination file.

Note that files or entire folders can be marked as never sync. See Ignoring Files and Folders for more information.

Note that the process does not mirror the data ... they only ensure that the destination contains everything at the source.

These actions only work if filenames and folder structures under the roots are exactly the same. For example if you are syncing /Users/Me/Music to /Volumes/Music/Copy, the following files are a match:

/Users/Me/Music/John Doe/His Best/song.mp3
/Volumes/Music/Copy/John Doe/His Best/song.???

The filename extension on the second file is described as ??? as how files get matched is controlled by the actions.

Two user facing actions are supplied:

Sync Files Utility
This is the main action which provides all the configurability.

Sync Files With Default Profile
The Sync Files Utility lets you create different profiles for different processes. This action runs the default profile without presenting any configuration options.

These actions let you optionally copy or convert the source files when the file at the destination is missing. When conversion is required, Permute 3 is used. Permute 3's automation via Yate was jointly designed. If you do not have Permute 3 on your Mac, the options to convert files will not be presented. These actions require Permute 3.6.4 or later.



Back to top of page





Sync Files Utility

This action is used to configure and edit profiles. It can also be used to execute a profile. Whenever this action is run, if there are no defined profiles you will be immediately prompted to create a profile. If at least one profile is defined you will be presented with the following panel:



Utility Panel

You can manually enter profile names or select them from the popup menu displayed by the disclosure button. The default profile (used by the Sync Files With Default Profile) action, if any is identified by a on the menu.

The Help button will display this document.

The Run button will execute the profile specified in the text field.

The Remove button will display a panel allowing you to select which profiles you want to be removed.

The Create / View button is used to view, edit, rename and duplicate a profile. If the text field is empty a new profile will be created. If the text field is not empty and the specified name is not a defined profile, a profile of that name will be created. If the specified name is an existing profile, it will be edited.

When you want to close the action, use the Done button.

If Permute 3 is on you Mac, the context menu will have an Active Permute 3 Audio Presets menu item. More information can be found in the Permute 3 Preset Information Display topic.

If XLD is on you Mac, the context menu will have an XLD Profiles menu item. More information can be found in the XLD Profile Information Display topic.




The Create/View Panel - Configuring Profiles

The Create/View Button will display the following panel:



Config Image

The following section describes each row of the configuration panel:

Profile name

This field contains the name of the profile. If you change the name of a profile that already exists, you are either renaming or duplicating. If the Create a duplicate profile when saving checkbox at the bottom of the panel is checked, a duplicate will be created. The field cannot be empty.

Default profile

Use the popup menu to select Yes or No to establish if the displayed profile will be the default profile when saved.

Source folder

This root folder is the folder which will be passed to the Batch Processor. All files in or under the chosen folder will be processed. You select a folder by double clicking in the row's Setting column or from Get Folder Path menu item on the row's context menu. The value cannot be empty.

Destination folder

This root folder is the folder containing the files to be modified, if required. You select a folder by double clicking in the row's Setting column or from Get Folder Path menu item on the row's context menu. The value cannot be empty.

Source filename extensions

If you want to sync all encountered audio files leave the field empty. Alternately you can choose file types from the menu displayed by the row's popup menu. You can manually enter filename extensions if you wish. Items are separated by commas. Do not precede a filename extension by a period. ie. mp3 not .mp3

Destination filename extension

The row's popup menu displays the audio filename extensions supported by Yate. You only have to choose something from the popup menu if you are synching to different audio file types than in the source. If your libraries are copies nothing need be chosen. If you intend to use Permute 3 or XLD to produce missing files, you must specify a filename extension on this panel. You can manually enter an extension if you wish. If you want some audio file types to be copied and some to be converted, this field must contain the file type of the files after converting.

Missing files

You must select an item from the popup menu to specify how you want to handle missing files. You can also manually enter the values. Depending on other settings, files can still be copied in certain circumstances even if Permute 3 nd XLD are chosen. The choices are:
Ignore
Ignore missing files.
Copy
Copy the source file to the destination.
Permute 3
This is only displayed if the Permute 3 application is located on your Mac. When this item is selected, Permute 3 may be used to produce missing destination files.
XLD
This is only displayed if the XLD application is located on your Mac. When this item is selected, XLD may be used to produce missing destination files.
Only convert audio types
This is only enabled if you selected Permute 3 or XLD to produce missing files. If the field is empty, all missing files will be passed to the chosen converter, even if the source and destination file types are the same. If you want only certain file types to be converted and the others copied, select those audio types that you want converted. Note that MPEG-4 files are divided into AAC and ALAC. Similarly OGG files are divided into Opus and Vorbis.

Permute 3 preset

If you specified Permute 3 for Missing files you must specify which active Permute 3 preset to use. The popup menu will display the name of all enabled Premute 3 audio presets. You can also manually enter the name. The row is only displayed if the Permute 3 application is located on your Mac.

Permute 3 best match

The Best match methodology enables the ability to attempt to match the bit depth in an audio file to a preset. More information can be found in Permute 3 Best Match. You must select Yes or No to specify if you want to use the Best Match methodology. The row is only displayed if the Permute 3 application is located on your Mac.

XLD preset
XLD profile

If you specified XLD for Missing files you must specify one of a preset or profile name. The popup menus will display the appropriate identified presets or profiles. You can also manually enter the names. The rows are only displayed if the XLD application is located on your Mac. The rows are only displayed if the XLD application is located on your Mac.

Copy non audio files

This setting specifies how to handle non audio files and folders in each source folder containing audio files. The choices are:
Never
Ignore non audio files and folders.
New Folder
If the destination folder corresponding to the source folder containing audio files currently being processed by the batch processor had to be created, all non audio folders and contained folders which do not have an audio file as a descendent, will be copied. Note that the copied folder completely overwrites a preexisting folder of the same name.
On Changes
Changes can be: creating the destination folder; copying a source file; converting a source file or synchronizing metadata to a file in the destination folder.
Always
An attempt is made to always copy the non audio files and folders.
Set folder icon

You can choose to set the icon of the destination folder. The choices are the same as with non audio files.

Search for extra folders

When folders are renamed on the source it is entirely possible that there may be redundant orphaned folders on the destination. When a sync run finishes you can optionally look for folders on the destination which do not exist on the source. If you enable this process and redundant folders are located you will be given the opportunity to selectively delete them.

Single folder

Typically you want to process all subfolders in the source folder. By using the Batch Processor, these actions can sync files in an entire folder tree. However there are times that you may only wish to process audio files directly in the source folder. ie. ignore subfolders. If you choose Yes for Single folder, only a single folder will be processed. If you enable single folder processing, Search for extra folders will be ignored.

When syncing ignore:
You can elect to ignore the following UDTIs: Apple App PID, Yate Album ID, Yate Track ID. When a UDTI is ignored, it is not overwritten when syncing. When copying a missing file, they are cleared after the copy. One possible use is you're maintaining two libraries for use with Apple's Music application. Each library requires its own PIDs.

The Help button is context sensitive and displays popup help for the selected row in the table. If you want to display this document, hold down the Option key while clicking on the Help button.

Clicking on the Run button will validate the values, save the profile and then start it.

Cancel will cancel any changes that you've made and will redisplay the main panel. It will not cancel the action.

When a profile is saved, via Save or Run, the following holds:




The Remove Panel - Deleting Profiles

The Remove Button will display the following panel:



Remove Image

The table's context menu has Remove All and Remove None context menu items.



Back to top of page





Sync Files With Default Profile

If a default profile has been designed via the Sync Files Utility action and the profile information can be validated, the batch processor will be launched to run the profile.



Back to top of page





Configuring Permute 3

It is recommended that you make the following Permute 3 - Preferences - General settings:

These actions can interact with any enabled Permute 3 audio preset. Presets are enabled, created, duplicated and edited in Permute 3 - Preferences - Presets. Changes are not applied until Permute 3 - Preferences is closed.

Note that Permute 3's AAC preset does not refer to AAC in m4a files! More than likely these are the out of the box presets that you should be working with: AIFF, Apple Lossless, FLAC, M4A, MP3, Ogg (Audio) and WAV.


Back to top of page





Permute 3 Preset Information Display

Each item in the displayed panel describes a Permute 3 preset. The preset's settings are displayed. The first setting (and possible only setting) is the internal class name for the type of audio file being produced. If a C item is displayed, the value is Channels setting (0 for As Source). If an S item is displayed, the value is the Sample Rate setting (0 for Same as Source). If a B item is displayed, the value is the Sample Bits setting.




Permute 3 Preset Image

Back to top of page





Permute 3 Best Match

Permute 3 presets can mark the Channels and Sample Rate settings to match the source. However, there is no equivalent setting for the Sample Bits setting. When choosing a Permute preset you can also elect to enable Best match. When Best match is enabled the preset used is determined as follows:


Back to top of page





XLD Profile Information Display

This panel displays names of XLD profiles and their associated produced filename extension.




XLF Profiles Image

Back to top of page





Ignoring Files and Folders

When using the Sync Files or Sync Files With Default Profile actions you can elect to always ignore specific files or entire folders. A UDTI named NOSYNC or a custom field of the same name (case insensitive) is examined.

If any file in a folder has a NOSYNC value of 2, the entire folder is ignored. Any files which has a NOSYNC value of 1 are ignored. Any other value of NOSYNC is ignored.

If you wish to create a custom field, configure it as follows in Preferences - General - Custom Fields:



NOSYNC Custom Field


Back to top of page





Deleting Extra Files

If the Sync Files action is processing a profile where the Search for extra folders option is enabled, the source and destination folder trees will be compared. If extra folders, (folders in the destination but not in the source), are found they will be identified in a table.

You can select any folders that you want to delete. The context menu has items to select all or no folders for deletion.

Note that the selection of some folders may be redundant. For example if the following folders are displayed:

Album 1
Album 1/Disc 1
Album 1/Disc 2

Selecting Album 1 will delete its contained folders even if they are not selected.

Warning: This function deletes folders. It does not move them to the trash!



Back to top of page





Content List, Requirements & History


Content List:

Action : Convert Files

Action : Sync Files Utility

Action : Sync Files With Default Profile

Action : Sync Files - Batch Processor

Action : Helper: Create/Edit Profile

Action : Helper: Update Profile

Action : Display Active Permute Presets

Action : Display XLD Profiles

Action : Helper: Check for Old Actions

Action : Helper: Extension for Permute 3 Preset

Action : Helper: Extract Permute 3 Presets

Action : Helper: Read XLD Profile Names

Action : Helper: Extract Profile Metadata

Action : Helper: Validate Profile

Action : Helper: Run Batch Processor

Action : Helper: Convert Engine

Action : Helper: Process Best Match

Action : Helper: Walk Folder

Action : Helper: Setup Common Help

Rename Template: Variable 12

Replacement Set: HTML

Requirements:

Yate v6.10

History:


Date Version Information
2021-05-18 v1.0 First release. The Sync File utilities and the convert utilities were bundled in separate downloads.
2021-06-24 v2.0 Combined PerMute 3 and Sync Files in this bundle. New Preset handling. Bundled the utilities together to take advantage of common helper actions. Introduced an Exact Match scheme to attempt to match specific Permute 3 presets based on audio file settings. Released to the Preview List.
2021-07-04 v2.1 Support for Permute 3 installed by SetApp. Released to the Preview List.
2021-07-12 v2.2 Changes for Yate v6.6. Released to the Preview List.
2021-07-17 v2.3 Various cosmetic changes.
2021-07-18 v2.4 Files passed to Permute 3 which contained special characters were not escaped properly.
2021-07-20 v2.5 Accumulated changes for Yate v6.6.
2021-07-20 v2.6 Minor adjustments.
2021-07-26 v2.7 Patched Helper: Is Permute 3 Preset Active.
2021-08-10 v3.0 Introduced XLD support. Replaced Exact Match support with Best Match scheme. Many other changes. Version 3 renamed a number of the actions. When you update to version 3 or later by Yate's Action Updater, previously installed components which are no longer used will be removed.
2021-12-04 v4.0 Added NOSYNC support. Cleaned up UI with new features in Yate v6.7.
2022-01-02 v4.1 Fixed issue with the display of XLD profiles.
2022-02-06 v4.2 Updated to read the Permute 3 and XLD preferences to a container. Released to the preview list.
2022-03-08 v4.21 General release.
2022-03-18 v4.3 Removed debug code left in by mistake.
2022-04-05 v4.4 Fixed numerous XLD issues. Removed Direct Stream Digital for XLD as it is not available from the command line.
2022-04-09 v4.5 Fixed numerous XLD issues. Patched XLD presets but not profiles.
2022-04-09 v4.6 Patches for XLD in the Convert Files action.
2022-05-18 v5.0 Completely redesigned the UI. Added new capabilities.
2022-05-19 v5.1 XLD displayed preset names were not converted to the names required on the command line.
2022-05-19 v5.11 Cleaned up the display of some error messages.
2022-06-28 v5.12 The Convert Files action did not work with XLD, if no profiles were defined in XLD.

Download


Back to Yate Resources