From patchwork Sun May 27 04:16:46 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gyan X-Patchwork-Id: 9099 Delivered-To: ffmpegpatchwork@gmail.com Received: by 2002:a02:11c:0:0:0:0:0 with SMTP id c28-v6csp573365jad; Sat, 26 May 2018 21:17:03 -0700 (PDT) X-Google-Smtp-Source: AB8JxZpgYsXQnHquTOFhGjcqrRipDmfCi76uTVTuNZ2xBhqL4iM5OL2xK8aDSRnmHXb9QMzziUDB X-Received: by 2002:adf:eb52:: with SMTP id u18-v6mr6078962wrn.252.1527394623221; Sat, 26 May 2018 21:17:03 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1527394623; cv=none; d=google.com; s=arc-20160816; b=uy8MetWDC72uJOJZ7IWPrkphrp7ma0cb8d2wzBft3emluqNPc4k1Q8IPZCpqPOFmSQ P5drjKGTGbJVnSHIIUT59Jd1RDRqrmekekrV7VtgFWCF2qxGPMqhDFwt+pt7vr8xd6Dx VvThtGvK2BBZTTkR9ZMrJQbk/9fSRPj3SEnT5sTqd7Bj2OXAYQjaXOLvoW4sPlvdsk+j Y9SpU/eLbhKEY/4DrmauUt5mgc8ElMbJLfF9wnyomIpCloZh86hU/QSRytrgRLQprOPE hjZWrPoowrTvZtS/nh/R12zH2dlnycLPjVsR6iz6V21fDiPRLpHaxtNcfTDfA/5oe/nw 4bQA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:reply-to:list-subscribe:list-help:list-post :list-archive:list-unsubscribe:list-id:precedence:subject :content-language:in-reply-to:mime-version:user-agent:date :message-id:from:references:to:dkim-signature:delivered-to :arc-authentication-results; bh=ytllbXZGMqiutR+LXKoIhZeO6YYsxQUCJSMa79kCKfk=; b=HBtZqDvJSah6JOucs8MiVrN12WI7N/6T/nT3Xi6hoSZ5LOeeQiDIAsuVwEo4lDJQ7I z7WZvWgBusg6Ws9PlOPHk310zcNX9wK+/u4Y3/q3Orx4vAsJ6pFcUQpFjNTfAoX32wDl lcDUwLVL6ndLu+lvIHtyG0f9uqW+YTMDq6LQWh+49pL3XfSpdlGgvqqNsOeNiZNE2r4E Mn6tt8V+rQh4+u5kwDoDGVgBgcgNyskqDg2LgQk2JksMP333C4iYalFMGnwuLdixoU5Q oWQTWTJoy+6vKavR+Pf26n8qCLpCnLdAn1HzXZCezTbMx2jKUW34Fc6pnimjrvbclzf9 jzaQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20161025 header.b=lODhWxWX; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id c27-v6si9674313wrb.420.2018.05.26.21.17.02; Sat, 26 May 2018 21:17:03 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20161025 header.b=lODhWxWX; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 462DC68A3A7; Sun, 27 May 2018 07:16:17 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-pg0-f67.google.com (mail-pg0-f67.google.com [74.125.83.67]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id BBC8D68A23A for ; Sun, 27 May 2018 07:16:10 +0300 (EEST) Received: by mail-pg0-f67.google.com with SMTP id w12-v6so2688601pgc.6 for ; Sat, 26 May 2018 21:16:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=subject:to:references:from:message-id:date:user-agent:mime-version :in-reply-to:content-language; bh=8ZRkOhpt68LGwWqpmboCrBmj1967oBfQJPCPLkpGVOk=; b=lODhWxWXjsOqCZPQTK4e8Ut72pjUDxlzHD3njEGrsejPmLTfeNwTSHzykXHVqs8wM7 DCXv4dVbUp/zXXB7gyQbd0eTZ1jFLCGv/KjjT9M9gwWVLhXlX3YnSYsfN5vXPkgbyNtV t80HZ7HYcZJD2lhX3zTyAp6iXXMgRHtJ4j5EW0claPSkjvlbNtt5itu9/6qELSoceooV QGdioV+6HP/41UkrfnvbajN0XyfGrIcAyn2sEW58m2VuIB5WTfmeo1oqrMbkyHPooX0b nFthTvQrvw+PWP04J/CuoTuwrJ+RQ8ryEhwM2GDqHNLocLvzl503YQkFeMZxQDE1xvKz KzkQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language; bh=8ZRkOhpt68LGwWqpmboCrBmj1967oBfQJPCPLkpGVOk=; b=A+Im9YuKoKK7HciI9SL6AzlVVNZ+NEUR0Jy//4pHjVf4Knw3nIJZPal5b7INiUgR60 0rWxkx2+4FH1yASsOp3Sy8zygf3SFHDUjOvfyYgqKy9WSgIdE0S/QZ5gSDMRyu+UH3yn +SYjqXjz1XJCrUj2KG9ynrqcpCrYLGc5B/kNijUYshYj9FBGONbAfvLaXnIVItSwNvhq vZWofxZF+3LHFIMfNDa9tA3btjSRhGanrQ8xt/+bHAA14G4U4U9V64dwEi6Q7MXpE/81 K0F0RbBScOk60YvYYE2nuxL9ZyoSd/PuiFynisVVkpD/dFlKi8uO/608lwP3nSVQmGBE LhPg== X-Gm-Message-State: ALKqPwfsIv6oMtpk7s84QBwdRhC7chPg9YVX1R9Goiit00S9e73HLPIn rI/5cPkZxCm3nsoljJZUPSzuPVDk X-Received: by 2002:a65:51c4:: with SMTP id i4-v6mr6611613pgq.190.1527394611632; Sat, 26 May 2018 21:16:51 -0700 (PDT) Received: from [192.168.1.225] ([27.106.98.9]) by smtp.gmail.com with ESMTPSA id r76-v6sm52158575pfl.1.2018.05.26.21.16.49 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 26 May 2018 21:16:50 -0700 (PDT) To: ffmpeg-devel@ffmpeg.org References: <2bd17759-8900-504f-b9b3-a6ad729d30ac@gmail.com> <20180525142011.45b81241@jagoff.localdomain> <1527368863.2532837.1386699640.0B5492A7@webmail.messagingengine.com> From: Gyan Doshi Message-ID: <8e2c78d7-87ca-fbaf-e372-db91981b0913@gmail.com> Date: Sun, 27 May 2018 09:46:46 +0530 User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.8.0 MIME-Version: 1.0 In-Reply-To: <1527368863.2532837.1386699640.0B5492A7@webmail.messagingengine.com> Content-Language: en-US Subject: Re: [FFmpeg-devel] [PATCH] doc/ffmpeg - rewrite Stream Selection chapter X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" On 27-05-2018 02:37 AM, Lou Logan wrote: > On Sat, May 26, 2018, at 12:33 AM, Gyan Doshi wrote: >> >> Part of the ugliness is due to how the code fragments are rendered: with >> vertical margins, creating uneven line spacing. Do you mind if I reduce >> or eliminate those margins? > > Which file sets those margins? The ugly justified text in the HTML doc that I was referring to before appears to be due to "body {text-align: justify;}" in style.min.css. I don't see any value to that at the moment, but maybe I'll take a closer look some other time and we can save this discussion for later since it should be dealt with separately from this patch. v2 attached. I was talking about the vertical margins appled to the 'code' element. Regards, Gyan From 60ed76348e70f1b0a25eadde8d886d47be3fca69 Mon Sep 17 00:00:00 2001 From: Gyan Doshi Date: Thu, 24 May 2018 19:11:00 +0530 Subject: [PATCH v2] 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 @@ -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