# Transfer Metadata

This function is used to transfer metadata in or out of a track from/to the path of an audio file stored in a variable. The variable must contain an absolute path to the file.

When transferring in you have no access to the track's properties as they cannot be copied to the track receiving the metadata. You can elect to create a key/value list in in a specified variable. The list will contain all of the relevant properties defined in the Get Property statement. The key value separator is the default ≔ character. The list delimiter is \n. You would use the List Key statement to access the values. .

You can transfer all metadata, all metadata except Unhandled or you can select which metadata items are to be transferred or not transferred. While Unhandled items can be selected, they are never transferred unless the source and destination have the same audio file type. If you have specifed that Unhandled should be copied and the source and destination files have a different audio file type, all Unhandled items in the destination file are removed. Note that when transferring all fields not selected, an empty list will transfer all fields. This method will properly handle the addition of additional field types in the future.

When transferring User Defined Text Info items you can supply a list of exclusions in named variable Transfer UDTI Exclusions. The named variable contains a list of UDTIs delimited by commas (,), newline characters (\n) and the default list delimiter (\~). Items in the exclusion list are not copied and are not removed. As an example this could be used to copy all UDTIs except the Apple App PIDs.

When transferring out there are additional options:

only if modified
  If the source file has not been modified, no transfer of metadata will take place. None of the remaining out options are processed.
copy mod date
  If the destination file is written, it's modification date will be set to the modification date of the source file. It is not recommended to do this if the source file has unsaved changes as its modification date will change when written and the two dates will not be the same. For that reason, using this setting in conjunction with the only if modified setting is not recommended. You can always test the modified property external to this statement and save the file first if required.
only if required
  For historic reasons, the destination file is by default always written if metadata was transferred. If this option is set, the destination file will only be written if the transfer of metadata changed something. If copy mod date is enabled, the setting of the modification date always occurs if metadata was transferred, regardless as to whether the file is written.

When transferring out the process is as follows:

- if the source file is not modified and only if modified is enabled, no other steps are performed.
- The destination file is loaded and the requested metadata is copied to the file's memory image.
- If anything has changed in the destination or the only if required option is not enabled, the destination file is written. Note that the Preferences - Audio - Common - Set Tagging Time when saving audio files setting is effectively disabled. All container errors including the elimination of leading padding before the start of the audio stream will be corrected.
- if the copy mod date option is enabled, the destination file's modification date will be set to the modification date of the source file.

If the statement succeeds, the action test state will be set to true, otherwise it will be set to false. When running stepwise the action test state will be false if there were any failures.

On a per file basis, status is retained by the use of the Save Error and Network Response properties. The following combinations can occur:

Save Error (0), Network Response (200)
  Success.
Save Error (0), Network Response (400)
  The path in the variable is not absolute or does not reference an audio file.
Save Error (0), Network Response (404)
  An error occurred while reading the file you are tranferring in from or transferring out to.
Save Error (1), Network Response (0)
  An error occurred while transferring out and saving the file.
Save Error (0), Network Response (500)
  An error occurred while copying the modification date.

The Once setting is only meaningful when running stepwise. When Once is set a transfer is only attempted for the first selected file.