doc/avconv: add forgotten end of chapter.
[ffmpeg.git] / doc / avconv.texi
index ab1df09..ba1c1a0 100644 (file)
@@ -65,6 +65,20 @@ specified for the inputs.
 
 @c man end DESCRIPTION
 
+@chapter Stream selection
+@c man begin STREAM SELECTION
+
+By default av tries to pick the "best" stream of each type present in input
+files and add them to each output file. For video, this means the highest
+resolution, for audio the highest channel count. For subtitle it's simply the
+first subtitle stream.
+
+You can disable some of those defaults by using @code{-vn/-an/-sn} options. For
+full manual control, use the @code{-map} option, which disables the defaults just
+described.
+
+@c man end STREAM SELECTION
+
 @chapter Options
 @c man begin OPTIONS
 
@@ -83,6 +97,34 @@ input file name
 @item -y
 Overwrite output files.
 
+@item -c[:@var{stream_type}][:@var{stream_index}] @var{codec}
+@item -codec[:@var{stream_type}][:@var{stream_index}] @var{codec}
+Select an encoder (when used before an output file) or a decoder (when used
+before an input file) for one or more streams. @var{codec} is the name of a
+decoder/encoder or a special value @code{copy} (output only) to indicate that
+the stream is not to be reencoded.
+
+@var{stream_type} may be 'v' for video, 'a' for audio, 's' for subtitle and 'd'
+for data streams.  @var{stream_index} is a global zero-based stream index if
+@var{stream_type} isn't given, otherwise it counts only streams of the given
+type. If @var{stream_index} is omitted, this option applies to all streams of
+the given type or all streams of any type if @var{stream_type} is missing as
+well (note that this only makes sense when all streams are of the same type or
+@var{codec} is @code{copy}).
+
+For example
+@example
+avconv -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
+@end example
+encodes all video streams with libx264 and copies all audio streams.
+
+For each stream, the last matching @code{c} option is applied, so
+@example
+avconv -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
+@end example
+will copy all the streams except the second video, which will be encoded with
+libx264, and the 138th audio, which will be encoded with libvorbis.
+
 @item -t @var{duration}
 Restrict the transcoded/captured video sequence
 to the duration specified in seconds.
@@ -145,12 +187,6 @@ avconv -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
 @item -dframes @var{number}
 Set the number of data frames to record.
 
-@item -scodec @var{codec}
-Force subtitle codec ('copy' to copy stream).
-
-@item -newsubtitle
-Add a new subtitle stream to the current output stream.
-
 @item -slang @var{code}
 Set the ISO 639 language code (3 letters) of the current subtitle stream.
 
@@ -271,8 +307,7 @@ It is of little use elsewise.
 @item -bufsize @var{size}
 Set video buffer verifier buffer size (in bits).
 @item -vcodec @var{codec}
-Force video codec to @var{codec}. Use the @code{copy} special value to
-tell that the raw codec data must be copied as is.
+Set the video codec. This is an alias for @code{-codec:v}.
 @item -sameq
 Use same quantizer as source (implies VBR).
 
@@ -285,8 +320,8 @@ at the exact requested bitrate.
 On pass 1, you may just deactivate audio and set output to null,
 examples for Windows and Unix:
 @example
-avconv -i foo.mov -vcodec libxvid -pass 1 -an -f rawvideo -y NUL
-avconv -i foo.mov -vcodec libxvid -pass 1 -an -f rawvideo -y /dev/null
+avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL
+avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
 @end example
 
 @item -passlogfile @var{prefix}
@@ -295,9 +330,6 @@ prefix is ``av2pass''. The complete file name will be
 @file{PREFIX-N.log}, where N is a number specific to the output
 stream.
 
-@item -newvideo
-Add a new video stream to the current output stream.
-
 @item -vlang @var{code}
 Set the ISO 639 language code (3 letters) of the current video stream.
 
@@ -533,7 +565,7 @@ Show QP histogram.
 @item -vbsf @var{bitstream_filter}
 Bitstream filters available are "dump_extra", "remove_extra", "noise", "h264_mp4toannexb", "imxdump", "mjpegadump", "mjpeg2jpeg".
 @example
-avconv -i h264.mp4 -vcodec copy -vbsf h264_mp4toannexb -an out.h264
+avconv -i h264.mp4 -c:v copy -vbsf h264_mp4toannexb -an out.h264
 @end example
 @item -force_key_frames @var{time}[,@var{time}...]
 Force key frames at the specified timestamps, more precisely at the first
@@ -563,20 +595,7 @@ and is mapped to the corresponding demuxer options.
 @item -an
 Disable audio recording.
 @item -acodec @var{codec}
-Force audio codec to @var{codec}. Use the @code{copy} special value to
-specify that the raw codec data must be copied as is.
-@item -newaudio
-Add a new audio track to the output file. If you want to specify parameters,
-do so before @code{-newaudio} (@code{-acodec}, @code{-ab}, etc..).
-
-Mapping will be done automatically, if the number of output streams is equal to
-the number of input streams, else it will pick the first one that matches. You
-can override the mapping using @code{-map} as usual.
-
-Example:
-@example
-avconv -i file.mpg -vcodec copy -acodec ac3 -ab 384k test.mpg -acodec mp2 -ab 192k -newaudio
-@end example
+Set the audio codec. This is an alias for @code{-codec:a}.
 @item -alang @var{code}
 Set the ISO 639 language code (3 letters) of the current audio stream.
 @end table
@@ -616,9 +635,7 @@ Bitstream filters available are "dump_extra", "remove_extra", "noise", "mp3comp"
 
 @table @option
 @item -scodec @var{codec}
-Force subtitle codec ('copy' to copy stream).
-@item -newsubtitle
-Add a new subtitle stream to the current output stream.
+Set the subtitle codec. This is an alias for @code{-codec:s}.
 @item -slang @var{code}
 Set the ISO 639 language code (3 letters) of the current subtitle stream.
 @item -sn
@@ -626,7 +643,7 @@ Disable subtitle recording.
 @item -sbsf @var{bitstream_filter}
 Bitstream filters available are "mov2textsub", "text2movsub".
 @example
-avconv -i file.mov -an -vn -sbsf mov2textsub -scodec copy -f rawvideo sub.txt
+avconv -i file.mov -an -vn -sbsf mov2textsub -c:s copy -f rawvideo sub.txt
 @end example
 @end table
 
@@ -640,42 +657,63 @@ Synchronize read on input.
 @section Advanced options
 
 @table @option
-@item -map @var{input_file_id}.@var{input_stream_id}[:@var{sync_file_id}.@var{sync_stream_id}]
+@item -map [-]@var{input_file_id}[:@var{input_stream_type}][:@var{input_stream_id}][,@var{sync_file_id}[:@var{sync_stream_type}][:@var{sync_stream_id}]]
 
-Designate an input stream as a source for the output file. Each input
+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 indexes start at 0. If specified,
-@var{sync_file_id}.@var{sync_stream_id} sets which input stream
+file. Both indices start at 0. If specified,
+@var{sync_file_id}:@var{sync_stream_id} 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
-file. The first @code{-map} option on the command line specifies the
+If @var{input_stream_type} is specified -- 'v' for video, 'a' for audio, 's' for
+subtitle and 'd' for data -- then @var{input_stream_id} counts only the streams
+of this type. Same for @var{sync_stream_type}.
+
+@var{input_stream_id} may be omitted, in which case all streams of the given
+type are mapped (or all streams in the file, if no type is specified).
+
+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.
 
+A @code{-} character before the stream identifier creates a "negative" mapping.
+It disables matching streams from already created mappings.
+
+For example, to map ALL streams from the first input file to output
+@example
+av -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 stream to place in an output file. For
+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:
 @example
-avconv -i INPUT out.wav -map 0.1
+avconv -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
-@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"),
+@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
-avconv -i a.mov -i b.mov -vcodec copy -acodec copy out.mov -map 0.2 -map 1.6
+avconv -i a.mov -i b.mov -c copy -map 0:2 -map 1:6 out.mov
+@end example
+
+To select all video and the third audio stream from an input file:
+@example
+avconv -i INPUT -map 0:v -map 0:a:2 OUTPUT
+@end example
+
+To map all the streams except the second audio, use negative mappings
+@example
+avconv -i INPUT -map 0 -map -0:a:1 OUTPUT
 @end example
 
-To add more streams to the output file, you can use the
-@code{-newaudio}, @code{-newvideo}, @code{-newsubtitle} options.
+Note that using this option disables the default mappings for this output file.
 
 @item -map_metadata[:@var{metadata_type}][:@var{index}] @var{infile}[:@var{metadata_type}][:@var{index}]
 Set metadata information of the next output file from @var{infile}. Note that
@@ -770,40 +808,7 @@ an output mpegts file:
 avconv -i infile -streamid 0:33 -streamid 1:36 out.ts
 @end example
 @end table
-
-@section Preset files
-
-A preset file contains a sequence of @var{option}=@var{value} pairs,
-one for each line, specifying a sequence of options which would be
-awkward to specify on the command line. Lines starting with the hash
-('#') character are ignored and are used to provide comments. Check
-the @file{ffpresets} directory in the Libav source tree for examples.
-
-Preset files are specified with the @code{vpre}, @code{apre},
-@code{spre}, and @code{fpre} options. The @code{fpre} option takes the
-filename of the preset instead of a preset name as input and can be
-used for any kind of codec. For the @code{vpre}, @code{apre}, and
-@code{spre} options, the options specified in a preset file are
-applied to the currently selected codec of the same type as the preset
-option.
-
-The argument passed to the @code{vpre}, @code{apre}, and @code{spre}
-preset options identifies the preset file to use according to the
-following rules:
-
-First avconv searches for a file named @var{arg}.ffpreset in the
-directories @file{$av_DATADIR} (if set), and @file{$HOME/.avconv}, and in
-the datadir defined at configuration time (usually @file{PREFIX/share/avconv})
-in that order. For example, if the argument is @code{libx264-max}, it will
-search for the file @file{libx264-max.ffpreset}.
-
-If no such file is found, then avconv will search for a file named
-@var{codec_name}-@var{arg}.ffpreset in the above-mentioned
-directories, where @var{codec_name} is the name of the codec to which
-the preset file options will be applied. For example, if you select
-the video codec with @code{-vcodec libx264} and use @code{-vpre max},
-then it will search for the file @file{libx264-max.ffpreset}.
-@c man end
+@c man end OPTIONS
 
 @chapter Tips
 @c man begin TIPS
@@ -953,7 +958,7 @@ You can encode to several formats at the same time and define a
 mapping from input stream to output streams:
 
 @example
-avconv -i /tmp/a.wav -ab 64k /tmp/a.mp2 -ab 128k /tmp/b.mp2 -map 0:0 -map 0:0
+avconv -i /tmp/a.wav -map 0:a -ab 64k /tmp/a.mp2 -map 0:a -ab 128k /tmp/b.mp2
 @end example
 
 Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. '-map
@@ -964,7 +969,7 @@ stream, in the order of the definition of output streams.
 You can transcode decrypted VOBs:
 
 @example
-avconv -i snatch_1.vob -f avi -vcodec mpeg4 -b 800k -g 300 -bf 2 -acodec libmp3lame -ab 128k snatch.avi
+avconv -i snatch_1.vob -f avi -c:v mpeg4 -b 800k -g 300 -bf 2 -c:a libmp3lame -ab 128k snatch.avi
 @end example
 
 This is a typical DVD ripping example; the input is a VOB file, the
@@ -1008,16 +1013,11 @@ only formats accepting a normal integer are suitable.
 You can put many streams of the same type in the output:
 
 @example
-avconv -i test1.avi -i test2.avi -vcodec copy -acodec copy -vcodec copy -acodec copy test12.avi -newvideo -newaudio
+avconv -i test1.avi -i test2.avi -map 0.3 -map 0.2 -map 0.1 -map 0.0 -c copy test12.nut
 @end example
 
-In addition to the first video and audio streams, the resulting
-output file @file{test12.avi} will contain the second video
-and the second audio stream found in the input streams list.
-
-The @code{-newvideo}, @code{-newaudio} and @code{-newsubtitle}
-options have to be specified immediately after the name of the output
-file to which you want to add them.
+The resulting output file @file{test12.avi} will contain first four streams from
+the input file in reverse order.
 
 @end itemize
 @c man end EXAMPLES