format sorting documentation

Checklist

• I’m reporting a bug unrelated to a specific site
• I’ve searched the bugtracker for similar issues including closed ones. DO NOT post duplicates
• I’ve read the guidelines for opening an issue

Description

I believe there is an error in the documentation. https://github.com/yt-dlp/yt-dlp#sorting-formats says:

« ie_pref: The format preference as given by the extractor […] The fields hasvid and ie_pref are always given highest priority in sorting, irrespective of the user-defined order. This behaviour can be changed by using --format-sort-force. Apart from these, the default order used is: lang,quality,res,fps,hdr:12,codec:vp9.2,size,br,asr,proto,ext,hasaud,source,id. The extractors may override this default order, but they cannot override the user-provided order. »

So at first, the doc says ie_pref (i.e. the extractor’s format preference) always has the highest priority, irrespective of the user-defined order. In other words, the extractor preference overrides the user preference.

So far so good, but then the doc goes on saying the extractor cannot override the user preference (last sentence in quote).

I may be mistaken, but I believe these two statements are contradictory and can’t both be true at the same time.

[pukkandan]

Some formats are from the Android API and some from the Web API. The formats from Web API may be throttled (it’s actually fixed now, though the checking code isn’t removed). So we check if the format will be throttled and then reduce source_preference if it is.

The field is similarly used in niconico and tiktok

[pukkandan]

Is there any place where I could find some information about the fields used in format sorting to avoid bothering you ? (I’d like to find out for example what other values than “-1” ie_pref can have. And what source means and what values it can have.)

Other than looking at extractor source code, no

Theoretically, I thought this should not change anything in the final sort order, as I am only passing along the default sort order (i.e. the sort order yt-dlp uses every time, even in the first run printed above).

That is because the YouTube extractor overrides the default sort order (which you overrode when passing it as user order)

[debug] Sort order given by extractor: quality, res, fps, hdr:12, source, codec:vp9.2, lang, proto