[FFmpeg-devel] [PATCH] doc/ffmpeg - rewrite Stream Selection chapter

[Gyan Doshi]

On 30-05-2018 04:57 AM, Carl Eugen Hoyos wrote:
> 2018-05-27 6:16 GMT+02:00, Gyan Doshi <gyandoshi at gmail.com>:
> 
>> v2 attached.
> 
>> +In the absence of any map options for a particular output file, ffmpeg inspects the output
>> +format to check which type of streams can be included in it, viz. video, audio and/or
> 
> Sorry, what is "viz."?

"Namely". Commonly seen in English prose. Can change it to 'i.e.' which 
is less correct here.

>> +subtitles. For each acceptable stream type, ffmpeg will pick one stream, when available,
>> +from among all the inputs.
> 
> I don't think this is correct, not every stream type is picked.
> Or do I misunderstand?

Yes. The qualifier is at the start, "For each acceptable stream type"

  >> +It will select that stream based upon the following criteria:
>> +@*
>> +@*for video, it is the stream with the highest resolution,
>> +@*for audio, it is the stream with the most channels,
>> +@*for subtitles, it is the first subtitle stream
> 
> Please remove the actual current criteria:
> This is just the current state of the implementation, for one
> of the above, this is obviously not a good choice, for the
> others, we could find better criteria.
> Or mention that they may all change at any point.

These have been the criteria for nearly 7 years now. The narrowing of 
the subtitle selection was added by you nearly 4 years ago. This is one 
of the parts I copied from the current version, since it remains valid.

>> +The output format's default subtitle encoder may be text-based or image-based, and only a
>> +subtitle stream of the same type can be chosen.
> 
> I wish that were true but I fear it isn't;-(

Please test. The 2nd example demonstrates it. It's your logic - you 
authored & committed it.
(`dvb teletext` is an exception since it no prop flags set.)

>> +In the case where several streams of the same type rate equally, the stream with the
>> lowest
>> +index is chosen.
> 
> Please remove this.

Why? Another part, copied from the original. Remains valid

> All-in-all, this is far too complicated imo.

The _implementation_ is complicated. The docs now reflect it.

The basic principle I'm aiming to follow for docs, even if execution 
remains uneven, is

If a user consults the relevant parts of the documentation before 
execution, they should be able to predict how the program will behave. 
If they do it afterwards, they should understand what the program did. 
Even though FFmpeg is an open source project, end users of the CLI tools 
aren't expected to understand or dive into the source to grasp how the 
program behaves. It's the job of the docs to convey descriptions of 
behaviour that will affect what the end user expects the program to do. 
Do you disagree?

Regards,
Gyan