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

[Lou Logan]

On Thu, 24 May 2018 19:18:50 +0530
Gyan Doshi <gyandoshi at gmail.com> wrote:

> From a7ff32bdac54a1f257482526a507ab7823cafb41 Mon Sep 17 00:00:00 2001
> From: Gyan Doshi <ffmpeg at gyani.pro>
> Date: Thu, 24 May 2018 19:11:00 +0530
> Subject: [PATCH] doc/ffmpeg - rewrite Stream Selection chapter

Nit:
Use : instead of - in the subject.

> Flesh out with details and examples to show quirks and limitations.
> ---
>  doc/ffmpeg.texi | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 160 insertions(+), 10 deletions(-)
> 
> diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
> index 88dbdeb95a..804bcc73ce 100644
> --- a/doc/ffmpeg.texi
> +++ b/doc/ffmpeg.texi
> @@ -216,16 +216,166 @@ filters is obviously also impossible, since filters work on uncompressed data.
>  @chapter Stream selection
>  @c man begin STREAM SELECTION
>  
> -By default, @command{ffmpeg} includes only one stream of each type (video, audio, subtitle)
> -present in the input files and adds them to each output file.  It picks the
> -"best" of each 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. In the case where several streams of
> -the same type rate equally, the stream with the lowest index is chosen.
> -
> -You can disable some of those defaults by using the @code{-vn/-an/-sn/-dn} options. For
> -full manual control, use the @code{-map} option, which disables the defaults just
> -described.

Due to the length of the new chapter it could be helpful to summarize
the most important aspects in the first paragraph then follow with the
more detailed documentation. Or at least adding subsections may make
reduce wall of text fatigue: I added some suggestions below.

> +The @code{-map} option should be used for manual control of stream selection for each
> +output file. When used, only user-mapped streams are included in that output file,
> +with one possible exception described below.

Please name what is involved in the exception instead of just
mentioning that there is one so the connection can be more easily made
in the following paragraphs.

> +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
> +subtitles. For each acceptable stream type, ffmpeg will pick one stream, when available,
> +from among all the inputs. It will select that stream based upon the following criteria:

Using a list here for the stream selection criteria may make it easier
to read and break up the wall of text, but I didn't try. Maybe it would
be ugly.

> +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 found but there's a caveat.
> +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. Data or attachment streams are not
> +automatically selected and can only be included using @code{-map}. In the case where several
> +streams of the same type rate equally, the stream with the lowest index is chosen.
> +
> +The @code{-vn}, @code{-an}, @code{-sn} options can be used to skip automatic stream selection
> +for video, audio, and subtitle streams respectively.

@subsection Complex filtergraphs

> +If there are any complex filtergraph output streams with unlabeled pads, they will be added
> +to the first output file. This will lead to a fatal error if the stream type is not supported
> +by the output format. In the absence of the map option, the inclusion of these streams leads
> +to the automatic stream selection of their types being skipped. If map options are present,
> +these filtergraph streams are included in addition to the mapped streams.
> +
> +Complex filtergraph output streams with labeled pads must be mapped once and exactly once.

@subsection Stream handling

> +Stream handling is independent of stream selection, with an exception for subtitles described
> +below. Stream handling is set via the @code{-codec} option addressed to streams within a
> +specific @emph{output} file. In particular, codec options are applied by ffmpeg after the
> +stream selection process and thus do not influence the latter. An exception exists for subtitles.
> +If a subtitle encoder is specified for an output file, the first subtitle stream found, of type
> +text or image, will be included. ffmpeg does not validate if the specified encoder can convert
> +the selected stream or if the converted stream is acceptable within the output format. This
> +applies generally as well: when the user sets an encoder manually, the stream selection process
> +cannot check if the encoded stream can be muxed into the output file. If it cannot, ffmpeg will
> +abort and @emph{all} output files will fail to be processed.
> +
> + at section Examples
> +
> +The following examples illustrate the behavior, quirks and limitations of ffmpeg's automatic
> +stream selection methods.
> +
> +They assume the following three input files.
> +
> + at verbatim
> +
> +input file 'A.avi'
> +      stream 0: video 640x360
> +      stream 1: audio 2 channels
> +
> +input file 'B.mp4'
> +      stream 0: video 1920x1080
> +      stream 1: audio 2 channels
> +      stream 2: subtitles (text)
> +      stream 3: audio 5.1 channels
> +      stream 4: subtitles (text)
> +
> +input file 'C.mkv'
> +      stream 0: video 1280x720
> +      stream 1: audio 2 channels
> +      stream 2: subtitles (image)
> + at end verbatim
> +
> +@*

Examples are often * itemized by convention, but the resulting text
justification such verbose examples makes them hard to read in HTML
format. I would ditch the itemization.

The examples that exhibit the behavior of the automatic stream
selection are informative, but perhaps too bewildering, technical, or
intimidating for users. I don't really have a good recommendation, but
adding titles for each example can help users understand what they are
getting into, or maybe simplify or prune this section a little. Or
maybe something like this is a better fit for the wiki. As it is I
don't envision general users reading this section as is.