Map Metadata to Files

The statement is used to attempt to establish a mapping between the track metadata returned by a Discogs Metadata for Release or MusicBrainz Metadata for Release statement and the current set of files. If the metadata was downloaded as a key-value list you must specify the named variable which contains the metadata. If the metadata was downloaded as a container, you must specify the name of the container.

You establish the same criteria as in the Discogs or MusicBrainz wizards. You can specify the source of the file based metadata used for mapping in one of three ways:

Tag Embedded Metadata

uses the fields within the tag information. You can elect to use any or all of Title, Artist, Track and Disc metadata. Note that one of Title or Track must be chosen. You can override the criteria at runtime by putting the following names in named variable Map Metadata to Files Override as a list separated by the default list delimiter (\~), newline characters (\n) or commas: Title, Artist, Track, Disc and Length (used for duration). If at least one of the fields is present in the list, it will be used to define the criteria. Otherwise, the criteria specified in the statement will be used.

Track-Title from Filename

extracts the Track and Title fields directly from a filename which is assumed to be formatted in one of three ways:

track number  title
track number -  title
track number .  title

File to Tag Template

requires that you specify a File to Tag template to extract fields from the filename. Extracted Title, Artist, Track and Disc fields can be accessed. Note that one of Title or Track must be chosen. The specification of the template can contain escape sequences. If the template cannot be found at runtime the statement will fail.

You can also choose to use a tracks's duration to assist in the mapping.

The Title Truncation pattern can be used to remove the tail of a Title field. If you are placing featuring information on Title fields, the artist information can hinder matching against titles in the online metadata. For example if you use Feat. as the start of your featuring specifications, you would specify Feat. in the Title Truncation field.

A percentage score of a match is evaluated based on a fuzzy comparison between the downloaded metadata title and:

• the title contained in a track's metadata
• the track's filename
• the track's filename run through all available File to Tag templates. This is used to extract the title from the filename which may contain other metadata components. When the metadata source explicitly names a File to Tag template, only that template is used.

A track variable is specified to receive the result of a mapping. The index is a 0 based index into the Track List item in the extracted metadata. If not mapped the variable will be set to -1.

A track variable is specified to receive the score. A value of 0 through 100 is returned. If not mapped the variable will be set to 0. The score is entirely based on Title.

If the metadata cannot be parsed or if a required template cannot be found, the action test state will be set to false. Otherwise, it will be set to true.

Escape sequences described in Escape Sequences can be used in any text field.

The statement is not valid during grouped execution.

A few items to think about:

• The algorithm used in the wizards always matches files. The only time you will have unmatched files is if there are less files than reported in the downloaded metadata.
• There is no guarantee that a match is correct.
• If you know for sure that the current set of files is represented by the downloaded metadata, the results should be meaningful. If you're not sure ... be careful.
• The wizards have the capability of splitting and merging tracks in certain instances. There is no capability here to do that as the downloaded metadata is a far more simplistic representation of track information.

Here's a code snippet in a simplistic example as to how to extract the metadata:

Discogs Metadata for Release "123456" to named variable 'test'
Map Metadata to Files metadata(metadata), mode(Tag Embedded Metadata), index(V0), score(V1), Use(Title, Artist, Track, Disc, Duration)
Set named variable 'Track Info' to the value of case insensitive key 'Track List' in the list in named variable 'metadata' (delimiter "⏎" separator "≔")
Test if the numeric value of the Variable 0 field >= 0 (Set result and Variable 15)
Ignore files where Variable 15 is false
if true
    Run inline action 'Extract additional per track metadata' grouped
    Restore Initial Set of Files
endif
Start Extract additional per track metadata
Set named variable 'Per Track Info' to the item at index '\v0' of the list in named variable 'Track Info' delimiter "\,"

' Extract per track metadata from the key-value list in Per Track Info
' ...
Set named variable 'Extracted Title' to the value of case insensitive key 'Title' in the list in named variable 'Per Track Info' (delimiter "\:" separator "≔")
Set the Title field to "\<Extracted Title>"

Manually Constructing the Metadata

While initially designed to work with the metadata returned by the Discogs Metadata for Release and MusicBrainz Metadata for Release statements, you can also construct your own metadata list. This is done in a variety of actions on the resources web page.

The only required field is the Track list array. Each Track list item can contain the following items: Artist, Title, Track number, Disc number and Length. If you are constructing a container the numeric fields can be Numbers or Strings. Omitted items will be treated as empty or 0.

If you want to include a test for a perfect filename match for data you have constructed you can do so if the mode is Tag Embedded Metadata. Add an item named __filename__ to the Track list items. If a track's filename is an exact match for the __filename__ item, it will always be mapped to that item. The track's score will be 100%. The double leading and trailing underscores were chosen to ensure that the item will not collide with any possible future Discogs or MusicBrainz returned metadata.

If you want to consider album metadata when mapping, add an item named __album__ to the Track list items. The double leading and trailing underscores were chosen to ensure that the item will not collide with any possible future Discogs or MusicBrainz returned metadata.