Criteria
When talking about a way to match media properties to some condition component uses word criterion.
Criteria are 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 with all criteria belonging to it. Use context menu of this list to explore available options.
Once you've added new criterion in order to use it, do not forget to select this criterion after you close repository configuration window. It is not selected automatically neither in this case nor when you remove from repository the criterion that is currently selected in this 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, a check is performed 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 six types of criteria: numeric, enumerable, textual, boolean, composite and include. Difference of first four ones comes from properties they match. For example container streams count is a number so it is covered by numeric criterion. Subtitles origin is enumeration so criterion is enumerable. 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.
Criterion can have other criteria embedded in it via an include. This way can be avoided duplication of the same blocks within different criteria, or for example one criteria can be used as a fallback for another.
Criteria conditions
Composite, textual, numeric and enumerable criteria have their own set of conditions. Condition can be changed for selected criterion using context menu.
Composite
Composite criteria have 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 the closest below- value should be less or equal to canonical number. Wins the one nearest to itis the closest above- value should be greater or equal to canonical number. Wins the one nearest to ithas the maximum value,has the minimum value- wins the one with maximum or minimum value respectively. Canonical number is not used in this case.
Numeric criteria also have so-called Equality Threshold option. It gives possibility to use some tolerance when checking if two numeric properties are equal to each other.
Let's suppose there are two audio files of bitrate 127kbps and 128kbps. When checking which is better and bitrate check is involved (e.g. condition is has the maximum value), strict comparison of bitrate values would result in a second file being considered as the better one. But specifically for bitrate such difference is irrelevant. So here comes equality threshold (in percent) which is 5% for bitrate values. Now if difference of two values is lesser than given percentage of highest value then they are considered as equal to each other. Therefore in our example comparison proceeds to the next criterion.
The following properties use non-zero equality threshold by default: origin.duration (2%), container.size (10%), video.framerate (7%), <any>.bitrate (5%).
Enumerable
Some properties represent enumerations (fixed set of predefined values). Examples are video.resolution, subtitles.origin.
Most of enumerable properties cannot be numerically compared to each other (e.g. statement audio.decoder has the maximum value is meaningless) so they do not have conditions.
However some enumerable properties can be numerically compared (actually only video.resolution at this time). So they provide the same set of conditions as numeric criteria (except that equality threshold is not applicable 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 valuecontains- property value must contain canonical stringmatches 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.*tokens
Boolean
These criteria check if particular flag is set (e.g. container.hls is set to true if container represents HLS stream) so they do not have specific conditions.
Negated criteria
This modifier inverts result of criteria matching. For property-based criteria it inverts result only if quality has such property. When comparing two qualities, it inverts result only if one quality better matches criteria than another (because comparison implies ordering, so internally there is no such comparison result as 'not equal', one quality may match criteria better than other, worse or the same).
Criteria applicability
When component needs to select quality, conforming criteria, it performs process consisting of two stages. First it filters out qualities not matching criteria. Then it compares remaining qualities with each other to arrange them in order of conformance to criteria. First quality in resulting list will be the one that meets criteria the best.
By default every criterion participates in both stages (option Match+Compare in context menu). If you want it to be used only during one stage, you can select either Match or Compare option.
Match appliance can be useful if you need to filter out qualities basing on some conditions but do not want these conditions to affect comparison. For example, it can be used if you want to filter out qualities using complex condition (AND/OR chain) but do not want its nested single criteria to affect final order of the qualities.
Compare appliance is useful if you do not want quality to be completely removed from the list if it does not match given criteria. For example, if condition is "maximum bitrate" and quality does not have bitrate information at all, it will be discarded. Instead of that, if you want this criterion to be skipped and remaining criteria in a chain to be used instead, you can set Compare compliance to it.
Criteria testing
For complex criteria it is not always obvious why one or another quality wins or gets skipped. To help with this a way is provided to examine criteria work on fly while you are editing them.
Criteria configuration windows for repositories that support testing have additional button Test which opens criteria test window.
Test UI uses analysis cache to get videos for test. It would report an error "There are no tracks in analysis cache" if no videos were opened before opening preferences page.
Criteria test window has combo box and list control. Combo box contains all tracks from analysis cache at the moment you opened preferences page. List control contains all separate streams found for the video 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 is made in configuration window.
If stream in the list is checked that means it matched the criteria. Streams are sorted according to the best match. So when selecting quality to play, will be used 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 to match.
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