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

[Michael Niedermayer]

On Wed, May 30, 2018 at 10:59:22AM +0530, Gyan Doshi wrote:
> 
> 
> 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?

This will only work to some extend
Different version will and probably do behave slightly different.

I still think its important to draw a line between what is
A. intended to behave exactly as it does
B. behaves one way and is just documented to do so.

Case A is much more likely to be conserved over time
Case B may change in the implementation whenever it feels convenient to the
developers i suspect ...

Theres also the distinction between what we intend to maintain over time
in Command line interface behavior and what we do not intend to.

in a few years this document is maybe still 70% accurate. It would be
usefull if people today could have a good guess what part will be that 70%
today, so they could write code that is future proof ...

thanks

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

Good people do not need laws to tell them to act responsibly, while bad
people will find a way around the laws. -- Plato
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20180531/5fdf971d/attachment.sig>