24 Sep 2019

Help

  1. Criteria repositories
  2. Criteria configuration
    1. Criteria conditions
  3. Criteria testing

Criteria

When talking about a way to match media properties to some condition filter uses word criteria.

It is important to understand that filter operates files, not qualities. Result of its work is a file (or set of files) that is passed to downstream filter in DirectShow graph. So using criteria you select a file conforming conditions from criteria. "File" actually can be not really a single file but fragmented (chunked) stream with finite or infinite (in case of live streams) number of fragments. So below is used more generic term "media source".

With that said, there are two media sources that you can setup in filter configuration. They are called main source and extra source and controlled by criteria combo boxes of the same name.

Main source is a first media file or live stream provided by the filter. If it does not match criterion selected in combo box Condition for extra source, and only in this case, filter selects extra source and adds it to the resulting set.

Main intention of this approach is support for DASH format with single stream (where video and audio are represented by separate media sources).

Criteria repositories

Top level criteria internally reside in criteria repositories. Criteria combo boxes (for example General Quality Main source) contain all criteria from single repo. In different cases are used different repos. So for example criteria in Main source and Extra source are the same, but criteria from Condition for extra source 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):

There are five types of criteria: numeric, textual, boolean, composite and include. 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.

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 and numeric 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.

Textual

Canonical string for textual criteria is a string you specify when adjusting criteria. All conditions are case-insensitive. Supported conditions:

Boolean

This criteria checks if particular flag is set in quality. These criteria 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).

Optional criteria<

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 bitrate condition to be skipped if it cannot be checked. But behavior of numeric criterion is different: it marks whole chain as failed since there are no bitrate information.

Solution is to mark criteria as optional. This way criteria always match given quality. So the quality is not discarded before comparison. However after that, when comparing two qualities, wins the one that really has given property.

For numeric properties it does more than just dealing with nonexistent properties. If property exists, it makes condition to 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 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