Match

Processor that matches objects and data types based on given configuration.

Classes:

CleanTagConfig(tag[, remove, split, preprocess])	Config for processing string-type tag values before matching with ItemMatcher
ItemMatcher()	Matches source items/collections to given result(s).

class musify.processors.match.CleanTagConfig(tag, remove=<factory>, split=<factory>, preprocess=<function CleanTagConfig.<lambda>>)

Bases: PrettyPrinter

Config for processing string-type tag values before matching with ItemMatcher

Attributes:

tag	The name of the tag to clean.
remove	A set of string values to remove from this tag.
split	A set of string values for which the cleaner will slice the tag on and remove anything that comes after.

Methods:

preprocess()	A function to apply before the remove and split values are applied.
as_dict()	Return a dictionary representation of the key attributes of this object.

tag: TagField

The name of the tag to clean.

remove: set[str]

A set of string values to remove from this tag.

split: set[str]

A set of string values for which the cleaner will slice the tag on and remove anything that comes after.

preprocess()

A function to apply before the remove and split values are applied.

as_dict()

Return a dictionary representation of the key attributes of this object.

Return type:

dict[str, Any]

The results of this function are used to produce the following:

• A JSON representation of the object when calling json()

• The string representation of the object when calling str() on the object

• The representation of the object when calling repr() on the object

class musify.processors.match.ItemMatcher

Bases: Processor

Matches source items/collections to given result(s).

Attributes:

karaoke_tags	A set of words to search for in tag values that identify the item as being a karaoke item.
year_range	A difference in years of this value gives a score of 0 for the match_year() algorithm.
clean_tags_remove_all	Apply these remove settings to all tags when processing tags as per clean_tags() method.
clean_tags_split_all	Apply these split settings to all tags when processing tags as per clean_tags() method.
clean_tags_config	A list of configurations in the form of CleanTagConfig to apply for each tag type.
reduce_name_score_on	A set of words to check for when applying name score reduction logic.
reduce_name_score_factor	The factor to apply to a name score when a word from reduce_name_score_on is found in the result but not in the source MusifyObject.
logger	The MusifyLogger for this object

Methods:

log(messages[, pad])	Log lists of messages in a uniform aligned format with a given pad character.
clean_tags(source)	Clean tags on the input item and assign to its clean_tags attribute.
match_not_karaoke(source, result)	Checks if a result is not a karaoke item that is either 0 when item is karaoke or 1 when not karaoke.
match_name(source, result)	Match on names and return a score between 0-1.
match_artist(source, result)	Match on artists and return a score between 0-1.
match_album(source, result)	Match on album and return a score between 0-1.
match_length(source, result)	Match on length and return a score between 0-1.
match_year(source, result)	Match on year and return a score between 0-1.
match(source, results[, min_score, ...])	Perform match algorithm for a given item and its results.
as_dict()	Return a dictionary representation of the key attributes of this object.

karaoke_tags = {'backing', 'instrumental', 'karaoke'}

A set of words to search for in tag values that identify the item as being a karaoke item.

year_range = 10

A difference in years of this value gives a score of 0 for the match_year() algorithm. See the match_year() method for more information.

clean_tags_remove_all = {'&', 'a', 'and', 'the'}

Apply these remove settings to all tags when processing tags as per clean_tags() method. See also CleanTagConfig for more info on this configuration.

clean_tags_split_all = {}

Apply these split settings to all tags when processing tags as per clean_tags() method. See also CleanTagConfig for more info on this configuration.

clean_tags_config = (CleanTagConfig(tag=<TagFields.TITLE: 65>, remove={'part'}, split={'featuring', '/', 'feat.', 'ft.'}, preprocess=<function CleanTagConfig.<lambda>>), CleanTagConfig(tag=<TagFields.ARTIST: 32>, remove=set(), split={'vs', 'featuring', 'feat.', 'ft.'}, preprocess=<function CleanTagConfig.<lambda>>), CleanTagConfig(tag=<TagFields.ALBUM: 30>, remove={'ep'}, split=set(), preprocess=<function ItemMatcher.<lambda>>))

A list of configurations in the form of CleanTagConfig to apply for each tag type. See also CleanTagConfig for more info.

reduce_name_score_on = {'acoustic', 'demo', 'live'}

A set of words to check for when applying name score reduction logic.

If a word from this list is present in the name of the result to score against but not in the source MusifyObject, apply the reduce_name_score_factor to reduce its score. This set is always combined with the karaoke_tags.

reduce_name_score_factor = 0.5

The factor to apply to a name score when a word from reduce_name_score_on is found in the result but not in the source MusifyObject.

logger: MusifyLogger

The MusifyLogger for this object

log(messages, pad=' ')

Log lists of messages in a uniform aligned format with a given pad character.

Convenience function for ensuring consistent log format for results of operations of this class and any other classes which use this class.

Return type:

None

clean_tags(source)

Clean tags on the input item and assign to its clean_tags attribute. Used for better matching/searching. Clean by removing words, and only taking phrases before a certain word e.g. ‘featuring’, ‘part’. Cleaning config for string-type tags is set in _clean_tags_config.

Parameters:

source (MusifyObject) – The base object with tags to clean.

Return type:

None

match_not_karaoke(source, result)

Checks if a result is not a karaoke item that is either 0 when item is karaoke or 1 when not karaoke.

Return type:

int

match_name(source, result)

Match on names and return a score between 0-1. Score=0 when either value is None.

Return type:

float

match_artist(source, result)

Match on artists and return a score between 0-1. Score=0 when either value is None. When many artists are present, a scale factor is applied to the score of matches on subsequent artists. i.e. match on artist 1 is scaled by 1, match on artist 2 is scaled by 1/2, match on artist 3 is scaled by 1/3 etc.

Return type:

float

match_album(source, result)

Match on album and return a score between 0-1. Score=0 when either value is None.

Return type:

float

match_length(source, result)

Match on length and return a score between 0-1. Score=0 when either value is None.

Return type:

float

match_year(source, result)

Match on year and return a score between 0-1. Score=0 when either value is None. Matches within year_range years on a 0-1 scale where 1 is the exact same year and 0 is a difference in year greater that year_range. User may modify this max range via the year_range class attribute.

Return type:

float

match(source, results, min_score=0.1, max_score=0.8, match_on=frozenset({TagFields.FILENAME, TagFields.TYPE, TagFields.SIZE, TagFields.CHANNELS, TagFields.SAMPLE_RATE, TagFields.BIT_RATE, TagFields.DATE_MODIFIED, TagFields.DATE_ADDED, TagFields.LAST_PLAYED, TagFields.PLAY_COUNT, TagFields.LENGTH, TagFields.ALBUM, TagFields.ALBUM_ARTIST, TagFields.ARTIST, TagFields.YEAR, TagFields.COMPOSER, TagFields.COMMENTS, TagFields.CONDUCTOR, TagFields.DISC_NUMBER, TagFields.DISC_TOTAL, TagFields.GENRES, TagFields.TITLE, TagFields.PUBLISHER, TagFields.RATING, TagFields.BPM, TagFields.TRACK_NUMBER, TagFields.TRACK_TOTAL, TagFields.EXT, TagFields.PATH, TagFields.FOLDER, TagFields.BIT_DEPTH, TagFields.DATE, TagFields.MONTH, TagFields.DAY, TagFields.KEY, TagFields.COMPILATION, TagFields.IMAGES, TagFields.DATE_CREATED, TagFields.DESCRIPTION, TagFields.URI, TagFields.USER_ID, TagFields.USER_NAME, TagFields.OWNER_ID, TagFields.OWNER_NAME, TagFields.FOLLOWERS, TagFields.NAME}), allow_karaoke=False)

Perform match algorithm for a given item and its results.

Parameters:

• source (TypeVar(T, bound= MusifyObject)) – Source item to compare against and find a match for.

• results (Iterable[TypeVar(T, bound= MusifyObject)]) – Results for comparisons.

• min_score (float (default: 0.1)) – Only return the result as a match if the score is above this value. Value will be limited to between 0.01 and 1.0.

• max_score (float (default: 0.8)) – Stop matching once this score has been reached. Value will be limited to between 0.01 and 1.0.

• match_on (GenericAlias[TagField] (default: frozenset({<TagFields.FILENAME: 3>, <TagFields.DATE: 900>, <TagFields.MONTH: 901>, <TagFields.DAY: 902>, <TagFields.KEY: 903>, <TagFields.COMPILATION: 904>, <TagFields.IMAGES: 905>, <TagFields.SIZE: 7>, <TagFields.TYPE: 4>, <TagFields.CHANNELS: 8>, <TagFields.BIT_RATE: 10>, <TagFields.SAMPLE_RATE: 9>, <TagFields.DATE_MODIFIED: 11>, <TagFields.LENGTH: 16>, <TagFields.DATE_ADDED: 12>, <TagFields.LAST_PLAYED: 13>, <TagFields.PLAY_COUNT: 14>, <TagFields.DATE_CREATED: 921>, <TagFields.ALBUM: 30>, <TagFields.ALBUM_ARTIST: 31>, <TagFields.ARTIST: 32>, <TagFields.YEAR: 35>, <TagFields.DESCRIPTION: 931>, <TagFields.COMPOSER: 43>, <TagFields.COMMENTS: 44>, <TagFields.CONDUCTOR: 45>, <TagFields.URI: 941>, <TagFields.USER_ID: 942>, <TagFields.USER_NAME: 943>, <TagFields.OWNER_ID: 944>, <TagFields.OWNER_NAME: 945>, <TagFields.FOLDER: 179>, <TagFields.DISC_NUMBER: 52>, <TagFields.FOLLOWERS: 946>, <TagFields.DISC_TOTAL: 54>, <TagFields.BIT_DEPTH: 183>, <TagFields.GENRES: 59>, <TagFields.TITLE: 65>, <TagFields.PUBLISHER: 73>, <TagFields.RATING: 75>, <TagFields.BPM: 85>, <TagFields.TRACK_NUMBER: 86>, <TagFields.TRACK_TOTAL: 87>, <TagFields.EXT: 100>, <TagFields.NAME: 1000>, <TagFields.PATH: 106>}))) – List of tags to match on. Currently only the following fields are supported: title, artist, album, year, length.

• allow_karaoke (bool (default: False)) – When True, items determined to be karaoke are allowed when matching added items. Skip karaoke results otherwise. Karaoke items are identified using the karaoke_tags attribute.

Returns:

Optional[TypeVar(T, bound= MusifyObject)] – T. The item that matched best if found, None if no item matched conditions.

as_dict()

Return a dictionary representation of the key attributes of this object.

Return type:

dict[str, Any]

The results of this function are used to produce the following:

• A JSON representation of the object when calling json()

• The string representation of the object when calling str() on the object

• The representation of the object when calling repr() on the object