| Message ID | 8e2c78d7-87ca-fbaf-e372-db91981b0913@gmail.com |
|---|---|
| State | New |
| Headers | show |
On Sun, May 27, 2018 at 09:46:46 +0530, Gyan Doshi wrote: > +The @code{-vn}, @code{-an}, @code{-sn} options can be used to skip automatic stream selection > +for video, audio, and subtitle streams respectively. This is incorrect, as it already was before. It doesn't disable *automatic* stream selection, it rather disables mapping any of these stream types at all, *even* if explictly mapped. (IOW: "-vn -map 0:v" never gets you any video stream in the output.) > +@file{out1.mkv} is a Matroska container file and accepts video, audio and subtitle streams, > +so ffmpeg will try to select one of each type. > +For video, it will select @code{stream 0} from @file{B.mp4}, which has the highest > +resolution among all the input video streams. > +For audio, it will select @code{stream 3} from @file{B.mp4}, since it has the greatest > +number of channels. > +For subtitles, it will select @code{stream 2} from @file{B.mp4}, which is the first subtitle > +stream from among @file{A.avi} and @file{B.mp4}. Your inserted line breaks don't make this a list yet, as they will be swallowed by the formatting. You either need to make paragraphs or a proper list. (Either way, it's much better than listing them all in one sentence.) Cheers, Moritz
On 27-05-2018 07:59 PM, Moritz Barsnick wrote: > This is incorrect, as it already was before. It doesn't disable > *automatic* stream selection, it rather disables mapping any of these > stream types at all, *even* if explictly mapped. (IOW: "-vn -map 0:v" > never gets you any video stream in the output.) Fixed locally, note that filtergraph outputs remain immune, > Your inserted line breaks don't make this a list yet, as they will be > swallowed by the formatting. You either need to make paragraphs or a > proper list. (Either way, it's much better than listing them all in one > sentence.) I didn't intend for separate lines, just composed it that way. But that does look better, so forced linebreaks added. Thanks, Gyan
On Sun, 27 May 2018 09:46:46 +0530 Gyan Doshi <gyandoshi@gmail.com> wrote: > I was talking about the vertical margins appled to the 'code' element. That's ugly too. I removed the margin for the code element. > From 60ed76348e70f1b0a25eadde8d886d47be3fca69 Mon Sep 17 00:00:00 2001 > From: Gyan Doshi <ffmpeg@gyani.pro> > Date: Thu, 24 May 2018 19:11:00 +0530 > Subject: [PATCH v2] doc/ffmpeg - rewrite Stream Selection chapter The subject nit still exists. doc/ffmpeg: rewrite Stream Selection chapter > Flesh out with details and examples to show quirks and limitations. > --- > doc/ffmpeg.texi | 187 +++++++++++++++++++++++++++++++++++++++++++++++++++++--- > 1 file changed, 177 insertions(+), 10 deletions(-) > > diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi > index 88dbdeb95a..803490ce7b 100644 > --- a/doc/ffmpeg.texi > +++ b/doc/ffmpeg.texi [...] > +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 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. Using an itemized list here will look better in my opinion. @itemize @item for video, it is the stream with the highest resolution, @item ... @end itemize [...] > +@subsubheading Example: automatic stream selection The subsubheadings did not render in the HTML for me, but they did in man. I didn't investigate why. [...] > +@subsubheading Example: unlabeled filtergraph outputs Trailing whitespace. I'm not convinced a verbose, tutorial-style set of examples belongs here. I tend to put such things in the wiki, but if you think otherwise that's fine. That's all of my comments. Everything else LGTM.
2018-05-27 6:16 GMT+02:00, Gyan Doshi <gyandoshi@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."? > +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? > +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. > +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;-( [...] > +In the case where several streams of the same type rate equally, the stream with the > lowest > +index is chosen. Please remove this. All-in-all, this is far too complicated imo. Please resend, Carl Eugen
On 30-05-2018 04:57 AM, Carl Eugen Hoyos wrote: > 2018-05-27 6:16 GMT+02:00, Gyan Doshi <gyandoshi@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
On 30-05-2018 04:39 AM, Lou Logan wrote: > The subject nit still exists. Fixed locally. > Using an itemized list here will look better in my opinion. > > @itemize > @item > for video, it is the stream with the highest resolution, > @item > ... > @end itemize Changed. >> +@subsubheading Example: automatic stream selection > > The subsubheadings did not render in the HTML for me, but they did in > man. I didn't investigate why. They do here. Which version of makeinfo do you have? More importantly, which version is on the project server? > [...] >> +@subsubheading Example: unlabeled filtergraph outputs > > Trailing whitespace. Already fixed. > I'm not convinced a verbose, tutorial-style set of examples belongs > here. I tend to put such things in the wiki, but if you think otherwise > that's fine. The wiki examples are common use-cases that people actually want to carry out. The examples here are to demonstrate how the set of rules in the description section work. These are not tutorials as such. Thanks, Gyan
On Tue, May 29, 2018, at 9:43 PM, Gyan Doshi wrote: > > They do here. Which version of makeinfo do you have? 6.5 Works when "--init-file=doc/t2h.pm" is omitted. Didn't investigate further. > More importantly, which version is on the project server? 5.2
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@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 [...]
On 31-05-2018 04:35 AM, Michael Niedermayer wrote: >> 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. The docs on the website are only for git master. > 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 ... > 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 ... Agreed. But that depends on the devs recording their intentions in writing. In this particular case, I don't see any TODO, FIXME or similar notes. The code has remained relatively the same for a few years now. If you know what the 70% is, in this case, I'll note that. I'll add a disclaimer about ffmpeg being under active development and that the docs are maintained on a best-effort basis. Regards, Gyan
On 31-05-2018 02:00 AM, Lou Logan wrote: > On Tue, May 29, 2018, at 9:43 PM, Gyan Doshi wrote: > > Works when "--init-file=doc/t2h.pm" is omitted. Didn't investigate further. make uses the init file here. makeinfo is texi2any 6.3 makeinfo --html -I doc --no-split -D config-not-all --init-file=/ffmpeg/src/doc/t2h.pm --output doc/ffmpeg.html /ffmpeg/src/doc/ffmpeg.texi Can you run this on the server to check if subsubheadings are rendered? Thanks, Gyan
On Wed, May 30, 2018, at 9:56 PM, Gyan Doshi wrote: > > Can you run this on the server to check if subsubheadings are rendered? I'm fairly confident it will since @subheading also works online for developer.html, but not locally. However, this shouldn't be blocking your patch since it is an independent issue. I may take a look later as I haven't ruled out a PEBKAC yet, but it would be helpful if others can try to see if it is duplicated: cd ffmpeg ./configure --disable-all makeinfo --html -I doc --no-split -D config-not-all --init-file=doc/t2h.pm --output ~/developer.html doc/developer.texi Then open ~/developer.html and search for "You must not commit code which breaks FFmpeg!" or any other subheading.
On 31-05-2018 11:57 PM, Lou Logan wrote: > On Wed, May 30, 2018, at 9:56 PM, Gyan Doshi wrote: >> >> Can you run this on the server to check if subsubheadings are rendered? > > I'm fairly confident it will since @subheading also works online for developer.html, but not locally. However, this shouldn't be blocking your patch since it is an independent issue. Ok. Will push in a day or so. Thanks, Gyan
On 01-06-2018 01:16 PM, Gyan Doshi wrote: >> I'm fairly confident it will since @subheading also works online for >> developer.html, but not locally. However, this shouldn't be blocking >> your patch since it is an independent issue. > > Ok. Will push in a day or so. > > Thanks, > Gyan Revised and pushed.
diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi index 88dbdeb95a..803490ce7b 100644 --- a/doc/ffmpeg.texi +++ b/doc/ffmpeg.texi @@ -216,16 +216,183 @@ 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. +@command{ffmpeg} provides the @code{-map} option for manual control of stream selection in each +output file. Users can skip @code{-map} and let ffmpeg perform automatic stream selection as +described below. + +@section Description +@subsection Automatic stream selection + +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: +@* +@*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 Manual stream selection + +When @code{-map} is used, only user-mapped streams are included in that output file, +with one possible exception for filtergraph outputs described below. + +@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. + +@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. + +@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) +@end verbatim + +@subsubheading Example: automatic stream selection +@example +ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov +@end example +There are three output files specified, and for the first two, no @code{-map} options +are set, so ffmpeg will select streams for these two files automatically. + +@file{out1.mkv} is a Matroska container file and accepts video, audio and subtitle streams, +so ffmpeg will try to select one of each type. +For video, it will select @code{stream 0} from @file{B.mp4}, which has the highest +resolution among all the input video streams. +For audio, it will select @code{stream 3} from @file{B.mp4}, since it has the greatest +number of channels. +For subtitles, it will select @code{stream 2} from @file{B.mp4}, which is the first subtitle +stream from among @file{A.avi} and @file{B.mp4}. + +@file{out2.wav} accepts only audio streams, so only @code{stream 3} from @file{B.mp4} is +selected. + +For @file{out3.mov}, since a @code{-map} option is set, no automatic stream selection will +occur. The @code{-map 1:a} will select all audio streams from the second input @file{B.mp4}. +No other streams will be included in this output file. + +For the first two outputs, all included streams will be transcoded. The encoders chosen will +be the default ones registered by each output format, which may not match the codec of the +selected input streams. For the third output, codec option for audio streams has been set +to @code{copy}, so no decoding-filtering-encoding operations will occur, or @emph{can} occur. +Packets of selected streams shall be conveyed from the input file and muxed within the output +file. + +@subsubheading Example: automatic subtitles selection +@example +ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv +@end example +Although @file{out1.mkv} is a Matroska container file which accepts subtitle streams, only a +video and audio stream shall be selected. The subtitle stream of @file{C.mkv} is image-based +and the default subtitle encoder of the Matroska muxer is text-based, so a transcode operation +for the subtitles is expected to fail and hence the stream isn't selected. However, in +@file{out2.mkv}, a subtitle encoder is specified in the command and so, the subtitle stream is +selected, in addition to the video stream. The presence of @code{-an} disables audio stream +selection for @file{out2.mkv}. + +@subsubheading Example: unlabeled filtergraph outputs +@example +ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt +@end example +A filtergraph is setup here using the @code{-filter_complex} option and consists of a single +video filter. The @code{overlay} filter requires exactly two video inputs, but none are +specified, so the first two available video streams are used, those of @file{A.avi} and +@file{C.mkv}. The output pad of the filter has no label and so is sent to the first output file +@file{out1.mp4}. Due to this, automatic selection of the video stream is skipped, which would +have selected the stream in @file{B.mp4}. The audio stream with most channels viz. @code{stream 3} +in @file{B.mp4}, is chosen automatically. No subtitle stream is chosen however, since the MP4 +format has no default subtitle encoder registered, and the user hasn't specified a subtitle encoder. + +The 2nd output file, @file{out2.srt}, only accepts text-based subtitle streams. So, even though +the first subtitle stream available belongs to @file{C.mkv}, it is image-based and hence skipped. +The selected stream, @code{stream 2} in @file{B.mp4}, is the first text-based subtitle stream. + +@subsubheading Example: labeled filtergraph outputs +@example +ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" -map '[outv]' -an out1.mp4 out2.mkv -map '[outv]' -map 1:a:0 out3.mkv +@end example + +This command will fail, as the output pad labelled @code{[outv]} has been mapped twice. +No output files shall be processed. + +@example +ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" -an out1.mp4 out2.mkv -map 1:a:0 out3.mkv +@end example + +This command will also fail as the hue filter output is labelled (@code{[outv]}) and hasn't been mapped anywhere. + +The command should be modified as follows, +@example +ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" -map '[outv1]' -an out1.mp4 out2.mkv -map '[outv2]' -map 1:a:0 out3.mkv +@end example +The video stream from @file{B.mp4} is sent to the hue filter, whose output is cloned once, +and both outputs labelled. Then a copy each is mapped to the first and third output files. +The overlay filter, requiring two video inputs, uses the first two unused video streams. +Those are the streams from @file{A.avi} and @file{C.mkv}. The overlay output isn't labelled, +so it is sent to the first output file @file{out1.mp4}, regardless of the presence of the +@code{-map} option. The aresample filter is sent the first unused audio stream, that of +@file{A.avi}. Since this filter output is also unlabelled, it too is mapped to the first output +file. The presence of @code{-an} only suppresses automatic or manual stream selection of audio +streams, not outputs sent from filtergraphs. Both these mapped streams shall be ordered before +the mapped stream in @file{out1.mp4}. + +The video, audio and subtitle streams mapped to @code{out2.mkv} are entirely determined by +automatic stream selection. + +@file{out3.mkv} consists of the video output from the hue filter and the first audio stream from +@file{B.mp4}. +@* @c man end STREAM SELECTION