doc/filters: add sepia example for colorchannelmixer
[ffmpeg.git] / doc / ffmpeg.texi
index 5132227..50b2c8b 100644 (file)
@@ -16,26 +16,26 @@ ffmpeg [@var{global_options}] @{[@var{input_file_options}] -i @file{input_file}@
 @chapter Description
 @c man begin DESCRIPTION
 
-ffmpeg is a very fast video and audio converter that can also grab from
+@command{ffmpeg} is a very fast video and audio converter that can also grab from
 a live audio/video source. It can also convert between arbitrary sample
 rates and resize video on the fly with a high quality polyphase filter.
 
-ffmpeg reads from an arbitrary number of input "files" (which can be regular
+@command{ffmpeg} reads from an arbitrary number of input "files" (which can be regular
 files, pipes, network streams, grabbing devices, etc.), specified by the
 @code{-i} option, and writes to an arbitrary number of output "files", which are
 specified by a plain output filename. Anything found on the command line which
 cannot be interpreted as an option is considered to be an output filename.
 
-Each input or output file can in principle contain any number of streams of
-different types (video/audio/subtitle/attachment/data). Allowed number and/or
-types of streams can be limited by the container format. Selecting, which
-streams from which inputs go into output, is done either automatically or with
-the @code{-map} option (see the Stream selection chapter).
+Each input or output file can, in principle, contain any number of streams of
+different types (video/audio/subtitle/attachment/data). The allowed number and/or
+types of streams may be limited by the container format. Selecting which
+streams from which inputs will go into which output is either done automatically
+or with the @code{-map} option (see the Stream selection chapter).
 
 To refer to input files in options, you must use their indices (0-based). E.g.
-the first input file is @code{0}, the second is @code{1} etc. Similarly, streams
+the first input file is @code{0}, the second is @code{1}, etc. Similarly, streams
 within a file are referred to by their indices. E.g. @code{2:3} refers to the
-fourth stream in the third input file. See also the Stream specifiers chapter.
+fourth stream in the third input file. Also see the Stream specifiers chapter.
 
 As a general rule, options are applied to the next specified
 file. Therefore, order is important, and you can have the same
@@ -50,7 +50,7 @@ options apply ONLY to the next input or output file and are reset between files.
 
 @itemize
 @item
-To set the video bitrate of the output file to 64kbit/s:
+To set the video bitrate of the output file to 64 kbit/s:
 @example
 ffmpeg -i input.avi -b:v 64k -bufsize 64k output.avi
 @end example
@@ -96,14 +96,14 @@ tracking lowest timestamp on any active input stream.
 Encoded packets are then passed to the decoder (unless streamcopy is selected
 for the stream, see further for a description). The decoder produces
 uncompressed frames (raw video/PCM audio/...) which can be processed further by
-filtering (see next section). After filtering the frames are passed to the
-encoder, which encodes them and outputs encoded packets again. Finally those are
+filtering (see next section). After filtering, the frames are passed to the
+encoder, which encodes them and outputs encoded packets. Finally those are
 passed to the muxer, which writes the encoded packets to the output file.
 
 @section Filtering
 Before encoding, @command{ffmpeg} can process raw audio and video frames using
 filters from the libavfilter library. Several chained filters form a filter
-graph.  @command{ffmpeg} distinguishes between two types of filtergraphs -
+graph. @command{ffmpeg} distinguishes between two types of filtergraphs:
 simple and complex.
 
 @subsection Simple filtergraphs
@@ -139,7 +139,7 @@ only sets timestamps and otherwise passes the frames unchanged.
 
 @subsection Complex filtergraphs
 Complex filtergraphs are those which cannot be described as simply a linear
-processing chain applied to one stream. This is the case e.g. when the graph has
+processing chain applied to one stream. This is the case, for example, when the graph has
 more than one input and/or output, or when output stream type is different from
 input. They can be represented with the following diagram:
 
@@ -164,7 +164,7 @@ input. They can be represented with the following diagram:
 @end example
 
 Complex filtergraphs are configured with the @option{-filter_complex} option.
-Note that this option is global, since a complex filtergraph by its nature
+Note that this option is global, since a complex filtergraph, by its nature,
 cannot be unambiguously associated with a single stream or file.
 
 The @option{-lavfi} option is equivalent to @option{-filter_complex}.
@@ -178,7 +178,7 @@ Stream copy is a mode selected by supplying the @code{copy} parameter to the
 @option{-codec} option. It makes @command{ffmpeg} omit the decoding and encoding
 step for the specified stream, so it does only demuxing and muxing. It is useful
 for changing the container format or modifying container-level metadata. The
-diagram above will in this case simplify to this:
+diagram above will, in this case, simplify to this:
 
 @example
  _______              ______________            ________
@@ -190,7 +190,7 @@ diagram above will in this case simplify to this:
 @end example
 
 Since there is no decoding or encoding, it is very fast and there is no quality
-loss. However it might not work in some cases because of many factors. Applying
+loss. However, it might not work in some cases because of many factors. Applying
 filters is obviously also impossible, since filters work on uncompressed data.
 
 @c man end DETAILED DESCRIPTION
@@ -198,14 +198,14 @@ filters is obviously also impossible, since filters work on uncompressed data.
 @chapter Stream selection
 @c man begin STREAM SELECTION
 
-By default ffmpeg includes only one stream of each type (video, audio, subtitle)
+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 the stream with the most channels, for
-subtitle it's the first subtitle stream. In the case where several streams of
-the same type rate equally, the lowest numbered stream is chosen.
+"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 @code{-vn/-an/-sn} options. For
+You can disable some of those defaults by using the @code{-vn/-an/-sn} options. For
 full manual control, use the @code{-map} option, which disables the defaults just
 described.
 
@@ -232,7 +232,8 @@ input file name
 Overwrite output files without asking.
 
 @item -n (@emph{global})
-Do not overwrite output files but exit if file exists.
+Do not overwrite output files, and exit immediately if a specified
+output file already exists.
 
 @item -c[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
 @itemx -codec[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
@@ -345,19 +346,19 @@ Use fixed quality scale (VBR). The meaning of @var{q} is
 codec-dependent.
 
 @anchor{filter_option}
-@item -filter[:@var{stream_specifier}] @var{filter_graph} (@emph{output,per-stream})
-Create the filter graph specified by @var{filter_graph} and use it to
+@item -filter[:@var{stream_specifier}] @var{filtergraph} (@emph{output,per-stream})
+Create the filtergraph specified by @var{filtergraph} and use it to
 filter the stream.
 
-@var{filter_graph} is a description of the filter graph to apply to
+@var{filtergraph} is a description of the filtergraph to apply to
 the stream, and must have a single input and a single output of the
-same type of the stream. In the filter graph, the input is associated
+same type of the stream. In the filtergraph, the input is associated
 to the label @code{in}, and the output to the label @code{out}. See
 the ffmpeg-filters manual for more information about the filtergraph
 syntax.
 
 See the @ref{filter_complex_option,,-filter_complex option} if you
-want to create filter graphs with multiple inputs and/or outputs.
+want to create filtergraphs with multiple inputs and/or outputs.
 
 @item -filter_script[:@var{stream_specifier}] @var{filename} (@emph{output,per-stream})
 This option is similar to @option{-filter}, the only difference is that its
@@ -467,6 +468,10 @@ form @var{num}:@var{den}, where @var{num} and @var{den} are the
 numerator and denominator of the aspect ratio. For example "4:3",
 "16:9", "1.3333", and "1.7777" are valid argument values.
 
+If used together with @option{-vcodec copy}, it will affect the aspect ratio
+stored at container level, but not the aspect ratio stored in encoded
+frames, if it exists.
+
 @item -vn (@emph{output})
 Disable video recording.
 
@@ -495,8 +500,8 @@ stream
 @item -vlang @var{code}
 Set the ISO 639 language code (3 letters) of the current video stream.
 
-@item -vf @var{filter_graph} (@emph{output})
-Create the filter graph specified by @var{filter_graph} and use it to
+@item -vf @var{filtergraph} (@emph{output})
+Create the filtergraph specified by @var{filtergraph} and use it to
 filter the stream.
 
 This is an alias for @code{-filter:v}, see the @ref{filter_option,,-filter option}.
@@ -512,7 +517,7 @@ If the selected pixel format can not be selected, ffmpeg will print a
 warning and select the best pixel format supported by the encoder.
 If @var{pix_fmt} is prefixed by a @code{+}, ffmpeg will exit with an error
 if the requested pixel format can not be selected, and automatic conversions
-inside filter graphs are disabled.
+inside filtergraphs are disabled.
 If @var{pix_fmt} is a single @code{+}, ffmpeg selects the same pixel format
 as the input (or graph output) and automatic conversions are disabled.
 
@@ -527,10 +532,6 @@ list separated with slashes. Two first values are the beginning and
 end frame numbers, last one is quantizer to use if positive, or quality
 factor if negative.
 
-@item -deinterlace
-Deinterlace pictures.
-This option is deprecated since the deinterlacing is very low quality.
-Use the yadif filter with @code{-filter:v yadif}.
 @item -ilme
 Force interlacing support in encoder (MPEG-2 and MPEG-4 only).
 Use this option if your input file is interlaced and you want
@@ -636,8 +637,8 @@ Set the audio codec. This is an alias for @code{-codec:a}.
 Set the audio sample format. Use @code{-sample_fmts} to get a list
 of supported sample formats.
 
-@item -af @var{filter_graph} (@emph{output})
-Create the filter graph specified by @var{filter_graph} and use it to
+@item -af @var{filtergraph} (@emph{output})
+Create the filtergraph specified by @var{filtergraph} and use it to
 filter the stream.
 
 This is an alias for @code{-filter:a}, see the @ref{filter_option,,-filter option}.
@@ -895,7 +896,7 @@ Newly added values will have to be specified as strings always.
 Each frame is passed with its timestamp from the demuxer to the muxer.
 @item 1, cfr
 Frames will be duplicated and dropped to achieve exactly the requested
-constant framerate.
+constant frame rate.
 @item 2, vfr
 Frames are passed through with their timestamp or dropped so as to
 prevent 2 frames from having the same timestamp.
@@ -1004,10 +1005,10 @@ ffmpeg -i input.mpg -timecode 01:02:03.04 -r 30000/1001 -s ntsc output.mpg
 
 @anchor{filter_complex_option}
 @item -filter_complex @var{filtergraph} (@emph{global})
-Define a complex filter graph, i.e. one with arbitrary number of inputs and/or
+Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or
 outputs. For simple graphs -- those with one input and one output of the same
 type -- see the @option{-filter} options. @var{filtergraph} is a description of
-the filter graph, as described in the ``Filtergraph syntax'' section of the
+the filtergraph, as described in the ``Filtergraph syntax'' section of the
 ffmpeg-filters manual.
 
 Input link labels must refer to input streams using the
@@ -1051,7 +1052,7 @@ ffmpeg -filter_complex 'color=c=red' -t 5 out.mkv
 @end example
 
 @item -lavfi @var{filtergraph} (@emph{global})
-Define a complex filter graph, i.e. one with arbitrary number of inputs and/or
+Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or
 outputs. Equivalent to @option{-filter_complex}.
 
 @item -filter_complex_script @var{filename} (@emph{global})
@@ -1059,6 +1060,14 @@ This option is similar to @option{-filter_complex}, the only difference is that
 its argument is the name of the file from which a complex filtergraph
 description is to be read.
 
+@item -override_ffserver (@emph{global})
+Overrides the input specifications from ffserver. Using this option you can
+map any input stream to ffserver and control many aspects of the encoding from
+ffmpeg. Without this option ffmpeg will transmit to ffserver what is requested by
+ffserver.
+The option is intended for cases where features are needed that cannot be
+specified to ffserver but can be to ffmpeg.
+
 @end table
 
 As a special exception, you can use a bitmap subtitle stream as input: it
@@ -1361,9 +1370,42 @@ ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext
 @end itemize
 @c man end EXAMPLES
 
+@include config.texi
+@ifset config-all
+@ifset config-avutil
+@include utils.texi
+@end ifset
+@ifset config-avcodec
+@include codecs.texi
+@include bitstream_filters.texi
+@end ifset
+@ifset config-avformat
+@include formats.texi
+@include protocols.texi
+@end ifset
+@ifset config-avdevice
+@include devices.texi
+@end ifset
+@ifset config-swresample
+@include resampler.texi
+@end ifset
+@ifset config-swscale
+@include scaler.texi
+@end ifset
+@ifset config-avfilter
+@include filters.texi
+@end ifset
+@end ifset
+
 @chapter See Also
 
 @ifhtml
+@ifset config-all
+@url{ffmpeg.html,ffmpeg}
+@end ifset
+@ifset config-not-all
+@url{ffmpeg-all.html,ffmpeg-all},
+@end ifset
 @url{ffplay.html,ffplay}, @url{ffprobe.html,ffprobe}, @url{ffserver.html,ffserver},
 @url{ffmpeg-utils.html,ffmpeg-utils},
 @url{ffmpeg-scaler.html,ffmpeg-scaler},
@@ -1377,6 +1419,12 @@ ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext
 @end ifhtml
 
 @ifnothtml
+@ifset config-all
+ffmpeg(1),
+@end ifset
+@ifset config-not-all
+ffmpeg-all(1),
+@end ifset
 ffplay(1), ffprobe(1), ffserver(1),
 ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1),
 ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1),