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

[Stefano Sabatini]

On date Monday 2011-09-05 23:02:38 +0200, Etienne Buira encoded:
> Hi all.
> 
> $subject
> 
> Technical part should be ok, a native english speaker can probably tweak
> it a bit.
> 
> Regards.
> 

> 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.
         ^

typo: optionally

> + 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

All these may go in a separate patch ("." -> ":").
  
> -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
-- 
FFmpeg = Free & Frightening Magical Power Elastic Guru