The Artwork Information statement provides the ability to perform various operations on artwork items in a position independent manner. This statement provides access to various functionality on a single artwork item at a specified index. Note that the indexes are zero based. Index zero represents the default artwork item in any file.
All text fields may contain any of the sequences described in Escape Sequences.
By default, the index field is only evaluated once. This means that a single index is used for all files. For some functions, when not saving results to a named variable, there may be a Per file option. When Per file is set, the index will be evaluated for every file.
When a named variable is used as the destination of a function, it will fail if the image being processed is not the same for every file.
If you pass \sa for the index, it will match a single selected artwork item. More information can be found in the Accessing Selected Artwork topic. Any index which evaluates to be invalid at runtime will cause the function to fail for the associated file.
Those functions which use a supplied index, only evaluate the Index field once, unless the Per file control is checked.
The following functions are avaiilable:
Additional information:
Set the artwork item's description field to the specified data. The data field is evaluated for each file. The action test state will be true if any description was set.
Set the artwork item's picture type to the specified data. The data must either be one of the well defined picture types or an integer value representing the index of the picture type. If the data is not valid the picture type will be set to Other. A value picker is supplied as a convenience. The action test state will be true if any picture type was set.
Used to set the image metadata in an artwork item. For every selected file, the Container control specifies a track variable which contains the name of an object container describing the metadata. If a track variable is empty, the associated file is ignored and not modified.
If the container named in the track variable does not exist, is invalid or does not represent an object container, the associated file will nor be modified. Only two case insensitive keys, both optional, are processed in the container:
A list of EXIF/GPS tags can be found on the exiftool.org website. macOS may or may not interpret all of the documented keys.
Please Read: No attempt is made to validate the metadata keys or the encoding of the key's values. The OS may discard whatever keys it does not like and may override some changes. In fact macOS will almost always insert back some EXIF metadata when an attempt is made to remove it all (if EXIF metadata previously existed). This modification of the image metadata can happen whenever an action statement causes the data describing the image to be re-encoded.
When written, the image metadata is part of the image and therefore is part of the image's data. It important to note that whenever an image's data changes, you are in effect creating a new image in Yate. If all tracks in an album have the same image and this function is used only on a single track ... You will notice that the single track will contain a different image item after the function completes.
To avoid re-encoding the image data, this function will ignore specified changes if they would result in no changes being made to the current image metadata.
There are three convenience settings to enable the removal of items without creating a container:
Setting a track variable to - implies that all metadata is to be removed:
Set Variable 0 to "-"
Set Image Metadata of artwork item[0] to container in Variable 0 result to Variable 1 '
is equivalent to:
Create empty object container 'changes'
Set the container item at 'changes.EXIF' to null
Set the container item at 'changes.GPS' to null
Set Variable 0 to "changes"
Set Image Metadata of artwork item[0] to container in Variable 0 result to Variable 1
Setting a track variable to # implies that all EXIF metadata is to be removed:
Set Variable 0 to "#"
Set Image Metadata of artwork item[0] to container in Variable 0 result to Variable 1 '
is equivalent to:
Create empty object container 'changes'
Set the container item at 'changes.EXIF' to null
Set Variable 0 to "changes"
Set Image Metadata of artwork item[0] to container in Variable 0 result to Variable 1
Setting a track variable to @ implies that all GPS metadata is to be removed:
Set Variable 0 to "@"
Set Image Metadata of artwork item[0] to container in Variable 0 result to Variable 1 '
is equivalent to:
Create empty object container 'changes'
Set the container item at 'changes.GPS' to null
Set Variable 0 to "changes"
Set Image Metadata of artwork item[0] to container in Variable 0 result to Variable 1
Additional information about image metadata can be found in Image Metadata.
The artwork item at the specified index is moved to index 0 and as such becomes the default artwork. The test state is set to true on success. false implies that all runtime indexes are invalid.
Set the destination variable to the artwork item's description field.
Set the destination variable to the index of the artwork item's picture type.
Set the destination variable to the textual representation of the artwork item's picture type.
For each unique artwork image an attempt is made to extract the image's metadata. If there is no metadata or an error occurs, the associated track variable is set to empty. When metadata is extracted, the track variable is set to the unique name of a created container object. The container will have at least one of an EXIF or GPS key. Note that DPS support may not be available on older versions of the OS. The keys will reference an object whose keys describe the metadata. The following JSON representation describes the format:
{
"EXIF" : { exif metadata },
"GPS" : { gps metadata }
}
Additional information about image metadata can be found in Image Metadata.
Set the destination variable to the artwork item's mime type. Note that the * indicator used to denote a progressive JPEG in the UI is not returned here. Use the Get is Progressive JPEG function to determine if an image is progressive.
Set the destination variable to the artwork item's dimensions.
Set the destination variable to the artwork item's pixel count.
Set the destination variable to the size of the artwork data in bytes.
Set the destination variable to 1 if the image is a progressive JPEG, otherwise 0.
Set the destination variable to the resolution (PPI) of the image.
This function is used to compare a specified artwork item against one or more artwork items in the selected files. The source artwork item is specified by an artwork item's index in a file with a specified loaded file UID (LUID). The LUID is a file property. The index associated with the LUID must resolve to an absolute index. ie. while you can use escape sequences you cannot use \sa. If you want to compare the selected artwork item, you can use the Resolve Selected UI Index function, saving to a named variable, to locate a usable LUID and index for the item.
For each destination location (named or track variable), the following can be returned:
- empty
- The test was not performed due to an error. (eg. bad index)
- 0
- The images are not the same.
- 1
- The images are exactly the same. (data and metadata).
- -1
- The image data is the same but there are metadata differences. eg. different descriptions.
The action test state is set to tru if any images were matched.
Note: Yate caches images to ensure that only one copy of a given image is retained. When using this function, no image data is compared ... only the image pointers. There is one case where this can fail. The Duplicate Artwork statement is used to make a copy of an artwork item so that the original can be retained and the copy can be modified. If you duplicate an artwork item and do not modify it, this function will treat the original and duplicate as being different.
This function is used to copy an artwork item to all active files. The source artwork item is specified by an artwork item's index in a file with a specified loaded file UID (LUID). The LUID is a file property. The index associated with the LUID must resolve to an absolute index. ie. while you can use escape sequences you cannot use \sa. If you want to copy the selected artwork item, you can use the Resolve Selected UI Index function, saving to a named variable, to locate a usable LUID and index for the item.
Artwork items are not copied to files which already have the same artwork, regardless of metadata.
For each destination location (named or track variable), the following can be returned:
- empty
- The copy was not performed due to an error. (eg. bad index)
- 0
- A copy was not performed.
- 1
- A copy was performed.
The action test state is set to true if any images were copied.
The function is used to find the first artwork item in every active file which matches a picture type and/or description. The description test is performed case insensitive and can require an entire match or that the supplied text is contained in the description. The picture type data must either be one of the well defined picture types or an integer value representing the index of the picture type. If the picture type data is invalid, no attempt will be made to match the picture type.
A matched index or -1 is returned in the specified named or track variable.
It makes no sense to save the results to a named variable unless you know that there is only a single active file. Only a single file is processed when a named variable is used.
The action test state is set to true if any matches were made, otherwise false.
This function is used to compare artwork items across all active files at the effective supplied index. If the resultant track variable is set to empty, it implies that the runtime index associated with a file was invalid. Any other value is used to imply uniqueness. All tracks with a result of 1, have the same artwork. All tracks with a result of 2, have the same artwork. etc.
The action test state will be true unless not artwork was found.
When you want to use the \sa sequence as an index (Accessing Selected Artwork), you may at times wish to resolve the selected artwork index on a per file basis. This function will set the result track variable to the resolved index or -1 if it is not valid or applicable.
When the result is being written to a named variable, a single instance will be located. The specified named variable will be set to an index in one file and named variable Selected Artwork LUID will be set to the same file's Loaded File UID property. If for some reason, an instance cannot be found, both named variables will be set to -1.
The action test state will be true if any files could be resolved, otherwise false.