[FFmpeg-devel] Fix -map documentation to match current behaviour

[Etienne Buira]

Hi all.

$subject

Technical part should be ok, a native english speaker can probably tweak
it a bit.

Regards.

-------------- next part --------------
>From dd63cdf926350aaf7f3e311887fa95644dee7774 Mon Sep 17 00:00:00 2001
From: Etienne Buira <etienne.buira.lists at free.fr>
Date: Mon, 5 Sep 2011 22:55:19 +0200
Subject: [PATCH] doc: Fix -map documentation to match current behaviour

---
 doc/ffmpeg.texi |   54 ++++++++++++++++++++++++++++++++++++++----------------
 ffmpeg.c        |    2 +-
 2 files changed, 39 insertions(+), 17 deletions(-)

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index 832e3d8..5ef4f2c 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -649,42 +649,64 @@ Synchronize read on input.
 @section Advanced options
 
 @table @option
- at item -map @var{input_file_id}. at var{input_stream_id}[:@var{sync_file_id}. at var{sync_stream_id}]
+ at item -map [-]@var{source_stream}[:@var{sync_stream}]
 
 Designate an input stream 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 indexes start at 0. If specified,
- at var{sync_file_id}. at var{sync_stream_id} sets which input stream
+stream is identified as follows
+ at var{file_idx}[:@var{stream_idx}|[(v|a|s|d)[:@var{stream_type_idx}]]],
+where file_idx is the input file index. The stream selection can be
+achieved either by:
+ at itemize
+ at item
+not specifying anything, will select all streams if source_stream, or the first
+if sync_stream, or
+ at item
+specifying the stream index, or
+ at item
+specifying the stream type (v->video, a->audio, s->subtitles, d->data),
+optionnally followed by a colon and an integer to specify the nth stream of the given type.
+ at end itemize
+
+If specified, @var{sync_stream} sets which input stream
 is used as a presentation sync reference.
 
-The @code{-map} options must be specified just after the output file.
-If any @code{-map} options are used, the number of @code{-map} options
-on the command line must match the number of streams in the output
+A leading @code{-} will turn this @code{-map} option in negative mode,
+that is, it will disable all matching streams.
+
+The @code{-map} options must be specified before the output file.
+If any @code{-map} options are used, the number of still active @code{-map} options
+on the command line defines the number of streams in the output
 file. 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.
 
 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
+these streams are identified by "0:0" and "0:1". You can use
 @code{-map} to select which stream to place in an output file. For
 example:
 @example
-ffmpeg -i INPUT out.wav -map 0.1
+ffmpeg -i INPUT -map 0:1 out.wav
 @end example
-will map the input stream in @file{INPUT} identified by "0.1" to
+will map the input stream in @file{INPUT} identified by "0:1" to
 the (single) output stream in @file{out.wav}.
 
 For example, to select the stream with index 2 from input file
- at 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"),
+ at 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}:
 @example
-ffmpeg -i a.mov -i b.mov -vcodec copy -acodec copy out.mov -map 0.2 -map 1.6
+ffmpeg -i a.mov -i b.mov -vcodec copy -acodec copy -map 0:2 -map 1:6 out.mov
 @end example
 
-To add more streams to the output file, you can use the
- at code{-newaudio}, @code{-newvideo}, @code{-newsubtitle} options.
+As further examples,
+ at table @option
+ at item @code{0:v}
+will refer to the first video stream of the first input file
+ at item @code{0:a:1}
+will refer to the second audio stream of the first input file
+ at item @code{-1:a}
+will disable all previously @code{-map}ped audio streams from second input file
+ at end table
 
 @item -map_meta_data @var{outfile}[, at var{metadata}]:@var{infile}[, at var{metadata}]
 Deprecated, use @var{-map_metadata} instead.
diff --git a/ffmpeg.c b/ffmpeg.c
index 6aa3fa0..85c7277 100644
--- a/ffmpeg.c
+++ b/ffmpeg.c
@@ -4327,7 +4327,7 @@ static const OptionDef options[] = {
     { "y", OPT_BOOL, {(void*)&file_overwrite}, "overwrite output files" },
     { "c", HAS_ARG, {(void*)opt_codec}, "codec name", "codec" },
     { "codec", HAS_ARG, {(void*)opt_codec}, "codec name", "codec" },
-    { "map", HAS_ARG | OPT_EXPERT | OPT_FUNC2, {(void*)opt_map}, "set input stream mapping", "file.stream[:syncfile.syncstream]" },
+    { "map", HAS_ARG | OPT_EXPERT | OPT_FUNC2, {(void*)opt_map}, "set input stream mapping", "file_idx[:stream_idx|[(v|a|s|d)[:stream_type_idx]]][,sync]" },
     { "map_meta_data", HAS_ARG | OPT_EXPERT, {(void*)opt_map_meta_data}, "DEPRECATED set meta data information of outfile from infile",
       "outfile[,metadata]:infile[,metadata]" },
     { "map_metadata", HAS_ARG | OPT_EXPERT, {(void*)opt_map_metadata}, "set metadata information of outfile from infile",
-- 
1.7.3.4