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 the video frame context menu (qualities popup menu), analysis cache UI, and in Lyric Show Panel 3 source.
Criteria repositories
Criteria internally reside in criteria repositories. Everywhere a criterion needs to be selected, a combo box is provided that lists top-level criteria from the repository. Criteria combo boxes may refer to the same or different repositories.
Last item in every criteria combo box is a Configure item to configure its repository. When you select it, a criteria repository window pops up where you can manage criteria within this repository. This window lists repository name in the title.
Criteria repository window contains a list control with all criteria belonging to the repository. Use context menu of this list to explore available options.
Note that criteria addition or removal in the repository does not affect currently selected criteria in the combo boxes that use this repository.
Criteria configuration
To modify criterion, open criteria repository window, select criterion and use context menu item Modify. Criteria configuration window will be shown where you can modify this criterion.
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. 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 the 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 the 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 for the 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.
This separation is justified by possibility to provide unambiguous set of conditions for the properties (more about them in the next section). For example, condition has the maximum value is applicable for numbers but is not applicable for text.
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
Criteria composite, textual, numeric, enumerable have their own set of conditions. Condition can be changed for selected criterion using context menu.
Composite
Composite criteria specify how the results of nested criteria should be combined. There are two conditions:
AND: quality matches composite criteria if it matches all nested criteriaOR: 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 (i.e. yes/no) but also which one matches it better, so qualities can be sorted accordingly.
Canonical number here is a number you specify when adjusting criteria. So it is like a parameter for 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 the 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 best. 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 the highest value then they are considered as equal to each other. Therefore in our example comparison will proceed 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 enumeration (fixed set of predefined values). Examples: video.resolution, subtitles.origin.
Available set of conditions for enumerable properties is decided individually. For example, subtitles.origin has no conditions (statements like subtitles.origin has the maximum value would have no sense), but video.resolution provides the same set of conditions as numeric criteria (except that equality threshold is not applicable in this case).
Textual
All conditions are case-insensitive.
Canonical string here is a string you specify when adjusting criteria. So it is like a parameter for criteria.
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. If you need a partial match, wrap your regex with.*tokens
Boolean
These criteria check if particular flag is set, so they do not have specific conditions.
For example, you add container.hls property and this alone means that condition will be met only if container represents HLS stream.
Negated criteria
This modifier inverts result of criteria matching.
For property-based criteria it inverts result only if quality has such property. I.e. it does not work for unknown properties. For example, for container.hls it will apply only if this property is true or false, but will have no effect if container.hls is unknown.
When comparing two qualities, it inverts result only if one quality better matches criteria than the other one. It works this way because comparison implies ordering, so internally there is no such comparison result as 'not equal', one quality may match criteria better/worse than the other one or be the same, and nothing else.
Criteria applicability
When need to select quality, conforming criteria, a two-stage process is carried out:
- "match" stage: filtering out qualities not matching criteria
- "compare" stage: comparison of the remaining qualities to arrange them in the order of criteria conformance
The first quality in the resulting list is then considered as the best match for the criteria.
By default every criterion participates in both stages (option Match+Compare in the context menu). If you want it to be used only during the single stage, you can select either Match or Compare option there.
Match stage alone can be useful if you need to filter out qualities basing on some conditions but do not want these conditions to affect actual comparison. For example, it can be used to filter out qualities using complex condition (AND/OR chain) but do not let its nested criteria to affect the final order of the qualities.
Compare stage alone 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 just skip Match stage.
For numeric properties setting Compare stage alone does more than just dealing with nonexistent properties. If property exists, it marks condition as passed even if property value does not actually match condition. Qualities containing such properties will have lesser priority than the ones with really matching condition but greater priority than ones which do not have such properties at all. This way, for example, if you have the only one quality with, say, 256kbps bitrate, then condition bitrate the closest below 128kbps will not reject it.
Criteria testing
For complex criteria it is not always obvious why one or another quality wins or gets skipped. Thus criteria configuration window provides a way to examine criteria workflow on the fly while you are editing them.
For this purpose criteria configuration window have additional button Test which opens criteria test window (for repositories that support testing).
It uses analysis cache to get videos for the test. So it requires this cache to be non-empty, and otherwise reports an error "There are no tracks in analysis cache".
Criteria test window has combo box and a list control. Combo box contains all tracks from the analysis cache at the moment you opened settings. List control contains all separate streams found for the video selected in the combo box.
List control visualizes how criteria from the criteria configuration window match available streams. Matching is performed on the fly after every change is made in the configuration window.
If stream in the list is checked that means it passed "match" stage (read Criteria applicability about stages).
Streams are sorted according to the best match, visualizing by this the "compare" stage. So when selecting quality to play, will be used the one that is on the 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. So if you select only "compare" stage for relevant criteria, these streams will become checked without changing their position.
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 of 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 the 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