Criteria
When talking about a way to match media properties to some condition component uses word criteria.
Criteria originally were developed to improve quality selection for playback. However the final result appeared to be quite flexible both from development and usage point of view. Based on this, it made sense to use it more widely.
Thereby currently it is used when selecting audio quality, audio decoder, video quality, video downloader, subtitles to show initially, subtitles to use in Lyric Show Panel 3 source and internally in video frame context menu (qualities popup menu) and analysis cache UI.
Criteria repositories
Top level criteria internally reside in criteria repositories. Criteria combo boxes (for example Decoding Playback quality) contain all criteria from single repo. In different cases are used different repos. So for example criteria in Playback quality and non-playback quality (combo box next to Override non-playback quality) are the same, but criteria from Decoder combo box near to them are different.
When you select Configure item from criteria combo box, a dialog box pops up where you can configure repository i.e. manage criteria within it.
This dialog box has list control will all criteria belonging to it. Use context menu in this list to check available options.
Once you've added new criterion in order to use it, do not forget to select this criterion after you close repository config window. It is not selected automatically neither in this case nor when you remove from repo the criterion that is currently selected in the combo box.
Criteria configuration
To modify criterion, open criteria repository window, select criterion and use context menu item Modify. Criteria configuration window will appear after that and you can start modification.
Main UI element of this window is a tree control containing criteria tree. All modification options are available there via context menu.
Basically each criterion consists of two parts: property to which it applies and condition for its compliance. And when two qualities are compared, component checks whether they match this condition, and if both match - which one matches it better.
Available properties to match are grouped next way (you can find them in popup menu Add of tree context menu):
Origin- properties relevant not to single quality but to entire origin where this quality comes from. I.e. they are the same for all qualities within single origin but are different for different origins. Here reside metadata, origin URL (e.g. URL to video page), length (in seconds) and a flag whether this origin represents live streamContainer- properties of multimedia container format used for quality being matched. For example number of streams, size (if quality is represented by a single file), URL (to this specific media file or stream), bitrate (total bitrate of this file / stream) etc.Video, Audio, Subtitles- properties of corresponding streams within the container
There are four types of criteria: numeric, textual, boolean and composite. Difference of first three ones comes from properties they match. For example container streams count is a number so it is covered by numeric criterion. Codec name is a string so criterion is textual. Whether container is HLS is a true/false flag so it is covered by boolean criterion. And so on.
Composite criteria are used to group other criteria and combine their results.
Criteria conditions
Each criteria type has its own set of conditions. Condition can be changed for selected criterion using context menu (popup menu Condition).
Composite
Composite criteria has two conditions. They specify how results of nested criteria should be combined.
Condition AND means that quality matches composite criteria if it matches all nested criteria. Condition OR means that quality matches composite criteria if it matches at least one of nested criteria.
Numeric
Conditions for numeric criteria are described in the following list. Note that when comparing two qualities using numeric criteria it checks not only if there is a match (aka yes/no) but which one matches better to sort qualities accordingly. Canonical number there is the number you specify when adjusting criteria.
is equal to- whether property value is exactly equal to canonical numberis not equal to- whether property value is not equal to canonical numberis the closest below- value should be less or equal to canonical number. Wins the nearest oneis the closest above- value should be greater or equal to canonical number. Wins the nearest onehas the maximum value,has the minimum value- wins the one with maximum or minimum value respectively. Canonical number is not used in this case.
Textual
Canonical string for textual criteria is a string you specify when adjusting criteria. All conditions are case-insensitive. Supported conditions:
is equal to- canonical string should be equal to property valuematches regex- canonical string is treated as regular expression. Criteria matches only if full property value matches specified regex. Partial match is not allowed. If you need a partial match, wrap your regex with.*tokensmatches glob- simplified variant of previous condition. Match is performed using glob pattern. It is usual string with two special "wildcard" characters: '*' matches any number of characteds and '?' matches any single character. As with regex, this condition checks for full match. If you need partial match, wrap your pattern with '*' characters- the other three are negation of the above ones
Boolean
There are only two conditions for boolean criteria: is true and is false. Condition also implies canonical value so it is not configured there separately.
Optional conditions
When properties are matched using some condition, match is marked as failed if given quality does not contain the property being matched. In some cases this is not the desired behavior.
Suppose you want to select audio that has the maximum bitrate. If quality does not contain bitrate info, that is ok - you have other conditions in the chain like number of channels, sample rate etc. You want component to skip bitrate condition if it cannot be checked. But its behavior is different: it marks whole chain as failed since there are no bitrate information.
Solution is to mark condition as optional. This is supported by all textual, numeric and boolean conditions using context menu item Optional Property.
For numeric properties it does more than just dealing with nonexistent properties. If property exists, it makes condition be considered as passed even if property value does not actually match condition. Qualities containing such properties will have lesser priority than ones that really match appropriate condition but greater than ones which do not have such properties at all. This way, for example, if you have condition bitrate the closest below 128kbps and the only one quality with, say, 256kbps bitrate, it will not be rejected.
Criteria testing
For complex criteria it is not always obvious why one or another quality wins or gets skipped. To help with that component provides the way to examine criteria work on fly while you are editing criteria.
Currently it is only supported for criteria from Decoding Audio Playback quality and Decoding Video Quality. Their criteria configuration windows have additional button Test that opens criteria test window.
Test UI uses analysis cache to get tracks for test. They should be in the cache at the moment you open component preferences. So if you are getting error saying "There are no tracks in analysis cache", close preferences window, open some audio track and then open component preferences again.
Criteria test window has combo box and list control. Combo box contains all tracks from analysis cache at the moment you opened component preferences. List control contains all separate streams found for the track selected in combo box.
List control visualizes how criteria from criteria configuration window matches available streams. Matching is performed on the fly after every change made in configuration window.
If stream in the list is checked that means it matched the criteria. Streams are sorted according to best match. So when selecting quality to play, component will use the one that is on top of this list (if it is checked, otherwise there will be an error saying that no qualities matched criteria).
Streams that are unchecked in the list are still sorted with meaning. Numeric criteria have extra logic applied to non-matching qualities. When comparing two such qualities, it checks which one was closer.
If you want to get more details why some stream matched or did not match criteria, select it in the list and use context menu item Match. It will show detailed description how stream was matched to every single criteria until the final result was determined.
If you want to get details about why one stream was ranged better than other, select these two streams and use context menu item Compare. As with the Match, it will show detailed description how comparison was going through every single criteria until the final result was determined.
Help Criteria