The Copy Metadata Between Files and Transfer Metadata action statements allow you additional granularity when copying Comments, User Defined Text Items and User Defined URLs. The Actions>Copy Metadata menu items also support the granularity via settings on the Configure Copy Metadata panel. In order to be processed, a field type must be included in the list of fields to be copied.
The action statements take the granularity rules from a Multi Item Transfer Rules named variable. Note that prior to v8.0 of Yate, named variable Transfer UDTI Exclusions was used. Transfer UDTI Exclusions supported commas as delimiters. Multi Item Transfer Rules does not support commas.
All internal functionality which analyzes Multi Item Transfer Rules operates as follows:
When copying metadata via the Actions>Copy Metadata menu items, the optional supplied list of exclusions/inclusions follows the same formatting as the Multi Item Transfer Rules named variable.
Items and tokens in the rules list are delimited by newline (\n) or default list delimiter (\~) sequences.
Case insensitive tokens can be entered to specify which field is associated with items which follow the token. (Note that the names of items to be included or excluded are not case insensitive). These tokens can specify exclusion or inclusion. It is an error if there are items which are excluded and included for the same field type. If for any strange reason you have an item with the same name as one of the tokens, you can escape it by preceding it with a backslash (\) character in the UI or two backslash characters (\\) in an action.
If nothing is included or excluded for any of Comments, UDTIs or User Defined URLs, the default processing occurs for the empty field type. The default processing is that the destination becomes an exact copy of the source.
The following field type tokens are supported:
- <-udtis>
Subsequent items are User Defined Text Info items marked for exclusion. This token is implied when parsing of the text commences. udtis: is equivalent but is deprecated.- <+udtis>
Subsequent items are User Defined Text Info items marked for inclusion.- <-urls>
Subsequent items are User Defined URLs marked for exclusion. urls: is equivalent but is deprecated.- <+urls>
Subsequent items are User Defined URLs marked for inclusion.- <-comments>
Subsequent items are Comments marked for exclusion. comments: is equivalent but is deprecated.- <+commants>
Subsequent items are Comments marked for inclusion.
If the corresponding type is not effectively marked for copy/transfer, a section is ignored. For example if User Defined Text Info is not enabled, all udti tokens are ignored. Section header tokens which are not followed by items are ignored. In Comments, the language property is used to determine uniqueness. However, when this list is used only names are evaluated and language is ignored.
When specifying UDTI names, use the names as displayed. Many UDTIs are normalized so that they are consistent acroos all audio file types. Normalized UDTI names can be found on the Tag Mapping Table. Normalized field names are displayed as blue.
When an item is marked for exclusion it is never copied. The semantics are that all items are copied except those marked for exclusion. When an item is marked for exclusion it is copied. The semantics are that only those items marked for inclusion are copied.
Tokens can be freely interspersed but you cannot have both inclusion and exclusion items for any given field type. It's the only possible parsing error.
When items are copied and the associated field type has a non zero number of exclusions or inclusions, the items copied are added to the destination. This differs from a normal copy where field types are entirely replaced.
The following examples present different scenarios and additional tokens: <empty>, <flush>, <preserve>
Example 1 copying UDTIs from file A to file B
File A contains UDTIs: U1=1, U2=1, U3=1, U5=1, U6=1, U7=1
File B contains UDTIs: U2=2, U4=2, U6=2, U7=2
U5
U6
or
<-udtis>
U5
U6
After the copy File B will contain UDTIs: U1=1, U2=1, U3=1, U4=2, U6=2, U7=1
U1, U2, U3 and U7 were copied. U4 preexisted. U5 was excluded. U6 was excluded but preexisted.
The default comment has essentially has an empty name. When copying comments you can specify that you want to include or exclude the default comment by using the <empty> token.
Example 2 only copy the default comment
File A contains Comments: default=1,C1=1
File B contains Comments: default=2,C2=2
<+comments>
<empty>
After the copy File B will contain Comment: default=1, C2=2
default was copied. C2 was not copied but preexisted.
If you wish to override the behaviour that items are added, enter a <flush> token in the desired section. The presence of this token in a field type's list implies that all items of the field type in the destination of the copy are to be removed at the start of the copy.
Example 3 copying UDTIs from file A to file B
File A contains UDTIs: U1=1, U2=1, U3=1, U5=1, U6=1, U7=1
File B contains UDTIs: U2=2, U4=2, U6=2, U7=2
<+udtis>
<flush>
U2
U3
After the copy File B will contain UDTIs: U2=1, U3=1
U2 and U3 were copied and everything else was removed.
Example 4 copying UDTIs from file A to file B
File A contains UDTIs: U1=1, U2=1, U3=1, U5=1, U6=1, U7=1
File B contains UDTIs: U2=2, U4=2, U6=2, U7=2
<-udtis>
<flush>
U1
U5
U6
U7
After the copy File B will contain UDTIs: U2=1, U3=1
This is the same result as example 3. The only difference is that exclusions were used as opposed to inclusions.
One last scenario, is that you want to flush all preexisting items except for explicitly named items. The <preserve> token can be used for this purpose. The semantics for the <preserve> token are as follows: remove all preexisting items except for those explicitly specified for inclusion or exclusion. The <preserve> token has a higher precedence than the <flush> token. If <preserve> is present, <flush> is ignored.
Example 5 copying UDTIs from file A to file B
File A contains UDTIs: U1=1, U2=1, U3=1, U5=1, U6=1
File B contains UDTIs: U2=2, U4=2, U6=2, U7=2
<-udtis>
<preserve>
U4
U6
After the copy File B will contain UDTIs: U1=1, U2=1, U3=1, U4=2, U5=1, U6=2
U1, U2, U3, U5 were copied. U4 and U6 were excluded but preserved. U7 was removed as it was not explicitly named.
Example 6 copying UDTIs from file A to file B
File A contains UDTIs: U1=1, U2=1, U3=1, U5=1, U6=1
File B contains UDTIs: U2=2, U4=2, U6=2, U7=2
<+udtis>
<preserve>
U1
U2
U6
U7
After the copy File B will contain UDTIs: U1=1, U2=1, U6=1, U7=2
U1, U2, U6 were copied. U7 was preserved as it was explicitly named.
When configuring the named variable in an action statement, it might be easier to produce it on the Actions>Configure Copy Metadata panel as the exclusions/inclusions panel has a menu to insert the various tokens. You can copy the text and paste it into the appropriate text field in the action.