The Spotify Search Configuration action allows you to configure the criteria used to match the metadata in tracks to the metadata returned by a Spotify search. It also allows you to configure which metadata is stored to the tracks.
If you are looking for help on the available actions click here. If you are looking for help on getting started, click here.
No search based on text matching is perfect. The search performed by these actions is no exception. When a track has an ISRC value, an attempt is made to limit the search results by including the ISRC in the search. If this search fails or if there is no known ISRC value, a more general search based solely on the Title and Artist metadata is performed. When determining the best (if any) search result, the Title, Artist, Album, Disc, Year and ISRC fields are used. Additionally a track's duration is analyzed.
When search results are acquired, each result is matched by scoring it against the metadata in the track. Based on the criteria, results can be rejected. The matched result with the largest score is kept as the match. It is up to you to specify the criteria and to decide how exact a match must be.
This action can be run at any time. If a different action in the suite requires the search configuration and this action has never run, it will automatically be run.
The search criteria is divided into sets. The default set is always used when a search configuration is required. These criteria sets can be linked to others. If a search match cannot be made with the default set and the set has a link, the match attempt will be performed again with the linked set. The linked set can also link to another set, etc. When the Spotify action bundle is first installed, default criteria sets are automatically installed.
The window banner displays the name of the criteria set. The default set is always displayed when this action is started. You load and delete criteria sets via the menu displayed by the Function button.
The load submenu is used to access a different criteria set. The currently displayed set is not present on the menu. Note that the current displayed criteria are not saved when you do a load. If you want to save the displayed criteria to the current set, use the Save button.
The Delete submenu is used to choose a criteria set that you want deleted. Note that you cannot delete the default set.
You can create a new criteria set by selecting the Save As menu item. If you specify a name of a set which alread exists, it will be overwritten.
When a set other than the default is displayed, you can save the displayed criteria to the default set. Remember, that searches always start with the default set.
Reset Defaults will restore the three criteria sets initially supplied.
When scoring a search result each criteria is optionally processed and a value is added to the score. Any criteria item can also optionally eliminate a result from contention.
Every item in the table can display help specific to the row. Select a row and hit the spacebar to display the help.
The following is a discussion of the available criteria items.
- Title threshold (50-100) / multiplier
- When matching a Title, a minimum percentage of a fuzzy comparison is required in order to consider a potential match. The percentage is given in whole numbers with a range of 50 to 100. When 50, a Title will only meet the threshold if the fuzzy match percentage is 50% or greater. As long as the minimum threshold is met, the actual score will be modifed by the addition of:
fuzzy match percentage (0-1) * the multiplier
Title is the only criteria item which cannot be disabled.
If a Title test fails, various manipulations are performed on the title in an attempt to achieve results.
- Artist threshold (0-100) / multiplier
- When matching an Artist, a minimum percentage of a fuzzy comparison is required in order to consider a potential match. The percentage is given in whole numbers with a range of 0 to 100. When 0, all values will be accepted. As long as the minimum threshold is met, the actual score will be modifed by the addition of:
fuzzy match percentage (0-1) * the multiplier
Note that the setting must be enabled by checking the Enabled column. When disabled, no testing of the Artist field will occur.
The Artist test is the most difficult test to perform against search results. This is because artists are returned as a decomposed list and not as a text string. Further, Spotify tends to return an extensive artist list not always represented in a track's metadata. In the case of a test failure various manipulations are performed on the artist metadata in an attempt to achieve results.
- Album threshold (0-100) / multiplier
- The Album matching is performed and scored exactly the same as the Artist threshold with the exception that no text manipulations are performed on failure.
- Duration within seconds (1 - n) / multiplier
- When testing a duration, the supplied value is a number of seconds. The absolute value of the difference between the track's duration and the value read from Spotify must be less than or equal to the supplied value, or the test fails.
The Enabled column is a tri-state value. When ▢, the setting is not considered. When ☑, the setting is considered and is used to modify the score if the test succeeds. When ⊟ the potential match will only be considered if the test succeeds.
If the duration test succeeds the test result is considered to be 1, resulting in the multiplier being added to the score.
- Disc multiplier
- The disc test attempts to match a track's Disc field to a disc number in a result. If the track's Disc field is empty or 0, 1 is assumed. The Enabled column is a tri-state value. When ▢, the setting is not considered. When ☑, the setting is considered and is used to modify the score if the test succeeds. When ⊟ the potential match will only be considered if the test succeeds.
If the disc succeeds the test result is considered to be 1, resulting in the multiplier being added to the score.
- Track multiplier
- The track test attempts to match a track's Track field to a track number in a result. Functionally the test is identical to the Disc test.
- Year multiplier
- The year test attempts to match a track's Year field to a release date in a result. The test succeeds if the year component of each date in the test is then same. Functionally the test is identical to the Disc test.
- ISRC multiplier
- The ISRC test attempts to match a track's ISRC field to an ISRC in a result. Functionally the test is identical to the Disc test.
- On failure try settings →
- If the event that no match can be found for the specified criteria, you can link to another set of criteria. Criteria sets can be created via the panel's Function button's menu.
There is no limit to how many links can occur but a criteria set can only be invoked once. If a criteria set is specified which has already been processed, all testing is terminated.
The ability to link criteria sets on a match failure allows you to implement different criteria scenarios which can be successively applied.
The Metadata is displayed for all criteria sets but there is only a single copy across all sets. When extracting search results various items can be created.
The following data items can be created:
- SPOTIFY_TRACK_URL
- A URL to the matched track on the Spotify web site. This is the only metadata item used directly by the actions in the bundle. This item cannot be disabled.
SPOTIFY_ALBUM_URL
- A URL to the matched album on the Spotify web site.
SPOTIFY SCORE
- A User Defined Text Info (UDTI) item which is a string describing the results of a successful match. The string can contain the following codes:
- *
- The match was made from search results where an ISRC was matched.
- (#)
- The match was made in a linked criteria set (ie. not the default set). The # is 2 for the link specified in the default (starting) criteria and 1 is added for each successive link.
- T#
- # is the results of a Title test (0-100).
- A#
- # is the results of an Artist test (0-100).
- R#
- # is the results of an Album test (0-100).
- =
- The duration test succeeded.
- #
- The Track test succeeded.
- D
- The Disc test succeeded.
- Y
- The Year test succeeded.
- I
- The ISRC test succeeded.
