# Preferences - Lyrics

This panel configures the extraction of lyrics from happi.dev. Before you can get lyrics you must have registered and received an API key. The process is defined in Get Lyrics Introduction. The API key must be entered on this panel.

The Introduction to Get Lyrics topic provides information on happi.dev.

> We have purchased credits as a shared pool on happi.dev. You can access this shared pool by entering free for the happi.dev API Key field. These credits are a shared resource and at some point they will disappear..

You must specify which lyrics provier you are going to use.

The panel attempts to display the number of remaining free and paid credits (API calls). This information can be extracted in actions via an escape sequence (\\?lc) which returns the sum of the two values. Note that the value displayed represents the information returned when either of the APIs was last accessed in Yate. If you use the same key on a different Mac, the value may be incorrect and will only update whan an API request is issued. The value displayed represents the sum of free and purchased API credits. The amounts are not updated when you change the provider. The Refresh button can be used if you want to update the counts immediately.

Matching is performed primarily using the Artist and Title fields. It is possible that an incorrect match is made. The happi.dev API returns multiple matches. Album metadata in the case of ties. You can elect to Retain match qualifiers. With this option enabled, when a match occurs and a lyric is saved, normalized UDTIs are created or modified:

Get Lyrics Album
  The album associated with the returned lyrics.
Get Lyrics Artist
  The artist associated with the returned lyrics.
Get Lyrics Title
  The title associated with the returned lyrics.
Get Lyrics Probability
  The probability that the match is correct. The probability is represented as a percentage in the range of 0 - 100. Note that the value may have a fraction. This value is not used with the happi.dev API.

An attempt to acquire a lyric results in the creation or modification of a UDTI named Get Lyrics Status. The formatting of the Get Lyrics Status UDTI is described in Get Lyrics Status Format.

If you do not wish to see a message displayed when there is no match, you can enable the Do not display 'not found' messsages option.

The various options and means of disallowing a track from being processed when searching for lyrics are specified in the following flow control description:

- If a track has an empty Artist or Title field, it is not processed.
- If a track already has content in the Lyrics field, the track is only processed if the Lyrics exists option is not checked.
- If a UDTI or custom field named Instrumental exists and has a non zero value, the track is only processed if the Ignore Instrumental is true is not checked.
- If a track has the Skip When Shuffling field set, the track is only processed if the Skip When Shuffling set option is not checked.
- If the Genre field contains any item in the Genre contains any of list (case insensitive) the track is not processed. Note that the multi-value delimiter is always recognized. If the Genre list in Advanced List Settings is set to Always, the non standard delimiters will be available as well.
- If the Get Lyrics Status UDTI does not exist, the track is processed.
- If an attempt was made on the track previously and it was previously missing required metadata (Artist or Title), the track is processed.
- If the Retry setting is Never, the track is not processed.
- If the Retry setting is Always, the track is processed.
- The track is processed if the Retry setting, when converted to a number of days and added to the value in the Get Lyrics Status UDTI, represents a date greater or equal to the current date. Note that a month is loosely interpreted as 31 days.
- The track is not processed.

If the track was processed and lyrics were returned you still have a number of options. If the Always save results to Get Lyrics Text option is set, the returned lyrics will be saved to a normalized UDTI named Get Lyrics Text. In this case the Lyrics field will not be modified and the process is complete.

If lyrics were returned, they may still be declined. There are three tests which can optionally be performed which can decline a returned match. When a match is declined you can choose to save it to a normalized UDTI named Get Lyrics Text. The three tests are:

The API returns the Artist metadata that it associates with the match. You can do a fuzzy compare of the track's Artist field and the returned matched artist metadata. Note that the Weight Export Set is applied. You specify the threshold percentage to be deemed successful. When the set percentage is 0%, the artist metadata is not compared. 75% seems to be a good value.

The API returns the Title metadata that it associates wit the match, You can do a fuzzy compare of the track's Title field and the returned matched title metadata. Note that the Weight Export Set is applied. You specify the threshold percentage to be deemed successful. When the set percentage is 0%, the title metadata is not compared. 75% seems to be a good value.

If either of the above three tests are run and fail, the results will only be retained if you have the Save to Get Lyrics Text if ignored option set. If none of the tests were run or if the run tests met their thresholds, the lyrics will be saved to the Lyrics field.

Warning: The above tests should be experimented with. We've found that there are often variances which can cause a match to be declined. For instance the database might have the lyrics for a duet as opposed to the original artist. The title might be tagged as (live) while your track is not. Both of the preceding situations can cause an artist or title test to fail and it is difficult to determine an appropriate percentage for the fuzzy matching. Typically we leave the three tests set to 0% and make sure that Retain match qualifiers is set. This way you can always vet the results yourself at a later time. Featuring information on a title field will typically mess things up.