From patchwork Wed Aug 3 13:58:30 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anton Khirnov X-Patchwork-Id: 37107 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a21:1649:b0:8b:613a:194d with SMTP id no9csp458375pzb; Wed, 3 Aug 2022 07:00:42 -0700 (PDT) X-Google-Smtp-Source: AGRyM1u4AzypibrrQTuLjYJlqWdQZy2owhD1ZVFRLh/ztQorMMIse8fAMevfewYtUBOVNg5aHbTC X-Received: by 2002:a05:6402:4024:b0:43d:2067:f068 with SMTP id d36-20020a056402402400b0043d2067f068mr25165075eda.258.1659535241872; Wed, 03 Aug 2022 07:00:41 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1659535241; cv=none; d=google.com; s=arc-20160816; b=Rd10lnpCLYBktGaSscaF1wU2KArgBEEw1iCvFSONNZZtwiXIg3pJREJWNMz7836Oa5 Uhby6G8h/DFR28jNlU+VOeEYoZqjgAG7ovRR2vXHb+m3edIUqi5Bl1hm/taOM0rdz0Ry ErZvYBmYpHDm/+pfZzusP0L0rd/v1TrewFW+xV938IoK1wdNom3iqgqnvvSWv5rqWMJS NMVSh4mFc2r5C4HQ3HZxTnDRkZTJdJIkouF5DI4CkwH9fbuKm/L9iREA9DDnEYCGuJQk isW7Sd4Z92ExKMv1Jw8H31BaZwv7ZUkCfbeMjU0bjc6CtCII1snMt8t3kzYAdN2UUFH6 tRTg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:references:in-reply-to:message-id :date:to:from:delivered-to; bh=s3MRG9iTls8XKZNvASMJG5ZCrgch5dF24GnkRNLP8vI=; b=vTK9+9FtP2ofirZ2wXlnNM10EjZ3YRD5DbVfwwXHQ4Mj4+o7B0iMd6YYQwmBJQx2mQ NmUjIn8dtXu+ccAA3LT7tE6K9ZFPCL5D/7FvnIgIvDHpqsa3s5D1CmkTpErApyz70qTd e+0pTVdNhnUk+UTwEkEg0UubUcAyqHKK7G+spMsvTNiC5Kw+H1w45ZsXjjJll6p1zHDm Vp+5T2nRL49MgZVBXP1IUwyijaua549a96deblGw90ZLkZYVGPfyRRO+z8dbUuamkFEK Mr5zxkwwYYoZKaTOT3s4BgPVVmDCCCnaZovaRErL1wYWwz2EpRxqFwwLe3B3kjVr7s4A IpbQ== ARC-Authentication-Results: i=1; mx.google.com; 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 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id hb30-20020a170907161e00b0072f4876f0basi17876293ejc.128.2022.08.03.07.00.41; Wed, 03 Aug 2022 07:00:41 -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; 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 Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 8630868B8C0; Wed, 3 Aug 2022 16:59:12 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail0.khirnov.net (red.khirnov.net [176.97.15.12]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 9B55768B871 for ; Wed, 3 Aug 2022 16:59:06 +0300 (EEST) Received: from localhost (localhost [IPv6:::1]) by mail0.khirnov.net (Postfix) with ESMTP id 7A0D0240592 for ; Wed, 3 Aug 2022 15:59:05 +0200 (CEST) Received: from mail0.khirnov.net ([IPv6:::1]) by localhost (mail0.khirnov.net [IPv6:::1]) (amavisd-new, port 10024) with ESMTP id kBoLTJ-ERdft for ; Wed, 3 Aug 2022 15:59:04 +0200 (CEST) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:2a00:c500:561:201::7]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "libav.khirnov.net", Issuer "smtp.khirnov.net SMTP CA" (verified OK)) by mail0.khirnov.net (Postfix) with ESMTPS id 175B024062A for ; Wed, 3 Aug 2022 15:58:55 +0200 (CEST) Received: by libav.khirnov.net (Postfix, from userid 1000) id 167693A0490; Wed, 3 Aug 2022 15:58:52 +0200 (CEST) From: Anton Khirnov To: ffmpeg-devel@ffmpeg.org Date: Wed, 3 Aug 2022 15:58:30 +0200 Message-Id: <20220803135844.16662-11-anton@khirnov.net> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20220803135844.16662-1-anton@khirnov.net> References: <20220803135844.16662-1-anton@khirnov.net> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 11/25] doc/ffmpeg: update -map documentation X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 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" X-TUID: t6/FLz6yXgMn Make it match reality (current text was not updated for stream specifiers), extend and clarify the text. --- doc/ffmpeg.texi | 58 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 19 deletions(-) diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi index 20747ebb8e..42440d93b4 100644 --- a/doc/ffmpeg.texi +++ b/doc/ffmpeg.texi @@ -1413,14 +1413,16 @@ Set the size of the canvas used to render subtitles. @table @option @item -map [-]@var{input_file_id}[:@var{stream_specifier}][?] | @var{[linklabel]} (@emph{output}) -Designate one or more input streams as a source for the output file. Each input -stream is identified by the input file index @var{input_file_id} and -the input stream index @var{input_stream_id} within the input -file. Both indices start at 0. +Create one or more streams in the output file. This option has two forms for +specifying the data source(s): the first selects one or more streams from some +input file (specified with @code{-i}), the second takes an output from some +complex filtergraph (specified with @code{-filter_complex} or +@code{-filter_complex_script}). -The first @code{-map} option on the command line specifies the -source for output stream 0, the second @code{-map} option specifies -the source for output stream 1, etc. +In the first form, an output stream is created for every stream from the input +file with the index @var{input_file_id}. If @var{stream_specifier} is given, +only those streams that match the specifier are used (see the +@ref{Stream specifiers} section for the @var{stream_specifier} syntax). A @code{-} character before the stream identifier creates a "negative" mapping. It disables matching streams from already created mappings. @@ -1434,39 +1436,56 @@ An alternative @var{[linklabel]} form will map outputs from complex filter graphs (see the @option{-filter_complex} option) to the output file. @var{linklabel} must correspond to a defined output link label in the graph. -For example, to map ALL streams from the first input file to output +This option may be specified multiple times, each adding more streams to the +output file. Any given input stream may also be mapped any number of times as a +source for different output streams, e.g. in order to use different encoding +options and/or filters. The streams are created in the output in the same order +in which the @code{-map} options are given on the commandline. + +Using this option disables the default mappings for this output file. + +Examples: + +@table @emph + +@item map everything +To map ALL streams from the first input file to output @example ffmpeg -i INPUT -map 0 output @end example -For example, if you have two audio streams in the first input file, -these streams are identified by "0:0" and "0:1". You can use -@code{-map} to select which streams to place in an output file. For -example: +@item select specific stream +If you have two audio streams in the first input file, these streams are +identified by @var{0:0} and @var{0:1}. You can use @code{-map} to select which +streams to place in an output file. For example: @example ffmpeg -i INPUT -map 0:1 out.wav @end example -will map the input stream in @file{INPUT} identified by "0:1" to -the (single) output stream in @file{out.wav}. +will map the second input stream in @file{INPUT} to the (single) output stream +in @file{out.wav}. -For example, to select the stream with index 2 from input file -@file{a.mov} (specified by the identifier "0:2"), and stream with -index 6 from input @file{b.mov} (specified by the identifier "1:6"), -and copy them to the output file @file{out.mov}: +@item create multiple streams +To select the stream with index 2 from input file @file{a.mov} (specified by the +identifier @var{0:2}), and stream with index 6 from input @file{b.mov} +(specified by the identifier @var{1:6}), and copy them to the output file +@file{out.mov}: @example ffmpeg -i a.mov -i b.mov -c copy -map 0:2 -map 1:6 out.mov @end example +@item create multiple streams 2 To select all video and the third audio stream from an input file: @example ffmpeg -i INPUT -map 0:v -map 0:a:2 OUTPUT @end example +@item negative map To map all the streams except the second audio, use negative mappings @example ffmpeg -i INPUT -map 0 -map -0:a:1 OUTPUT @end example +@item optional map To map the video and audio streams from the first input, and using the trailing @code{?}, ignore the audio mapping if no audio streams exist in the first input: @@ -1474,12 +1493,13 @@ the first input: ffmpeg -i INPUT -map 0:v -map 0:a? OUTPUT @end example +@item map by language To pick the English audio stream: @example ffmpeg -i INPUT -map 0:m:language:eng OUTPUT @end example -Note that using this option disables the default mappings for this output file. +@end table @item -ignore_unknown Ignore input streams with unknown type instead of failing if copying