Transfer Metadata

This statement 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 a specified variable. The list will contain all of the relevant properties defined in the File Properties topic. 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.

You can also select Runtime Override to process a list of fields in named variable Runtime Field List. The contents of the named variable are interpreted as a list of symbolic field names. The list can be delimited by default list delimiters (\~), newline characters (\n) and commas. Items which do not represent field names are ignored. The list of valid fields are processed exactly as if they were specified in the Transfer Fields in Table mode. This effectively provides a means of specifying which fields are to be processed at runtime. The complete list of available fields can be viewed in the table in the Multi Field Editor. Most field names can be inserted by the holding down the Shift key and selecting Insert Field on the Yate Transformations text field context menu. Fields which cannot be associated with single values (such as User Defined Text Info) are not available on the menu.

When copying User Defined Text Info, User Defined URLs and Comments, exclusions or inclusions can be specified in named variable Multi Item Transfer Rules. The Multi Item Transfer Rules topic describes the formatting.

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 Settings - 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.

Save Error (0), Network Response (501)

The Multi Item Transfer Rules named variable is not formatted correctly (empty is valid). This can only happen if exclusion and inclusion are specified for the same field type.

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