Note that you must activate the right video source and channel before
launching FFmpeg with any TV viewer such as xawtv
-(@url{http://bytesex.org/xawtv/}) by Gerd Knorr. You also
+(@url{http://linux.bytesex.org/xawtv/}) by Gerd Knorr. You also
have to set the audio recording levels correctly with a
standard mixer.
ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
@end example
-Converts a.wav to MPEG audio at 22050Hz sample rate.
+Converts a.wav to MPEG audio at 22050 Hz sample rate.
* You can encode to several formats at the same time and define a
mapping from input stream to output streams:
file:index' specifies which input stream is used for each output
stream, in the order of the definition of output streams.
-* You can transcode decrypted VOBs
+* You can transcode decrypted VOBs:
@example
ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800k -g 300 -bf 2 -acodec libmp3lame -ab 128k snatch.avi
to get the desired audio language.
NOTE: To see the supported input formats, use @code{ffmpeg -formats}.
+
+* You can extract images from a video, or create a video from many images:
+
+For extracting images from a video:
+@example
+ffmpeg -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg
+@end example
+
+This will extract one video frame per second from the video and will
+output them in files named @file{foo-001.jpeg}, @file{foo-002.jpeg},
+etc. Images will be rescaled to fit the new WxH values.
+
+If you want to extract just a limited number of frames, you can use the
+above command in combination with the -vframes or -t option, or in
+combination with -ss to start extracting from a certain point in time.
+
+For creating a video from many images:
+@example
+ffmpeg -f image2 -i foo-%03d.jpeg -r 12 -s WxH foo.avi
+@end example
+
+The syntax @code{foo-%03d.jpeg} specifies to use a decimal number
+composed of three digits padded with zeroes to express the sequence
+number. It is the same syntax supported by the C printf function, but
+only formats accepting a normal integer are suitable.
+
+* You can put many streams of the same type in the output:
+
+@example
+ffmpeg -i test1.avi -i test2.avi -vcodec copy -acodec copy -vcodec copy -acodec copy test12.avi -newvideo -newaudio
+@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.
@c man end
@chapter Invocation
ffmpeg -i input.avi -b 64k output.avi
@end example
-* To force the frame rate of the input and output file to 24 fps:
-@example
-ffmpeg -r 24 -i input.avi output.avi
-@end example
-
* To force the frame rate of the output file to 24 fps:
@example
ffmpeg -i input.avi -r 24 output.avi
@end example
-* To force the frame rate of input file to 1 fps and the output file to 24 fps:
+* To force the frame rate of the input file (valid for raw formats only)
+to 1 fps and the frame rate of the output file to 24 fps:
@example
-ffmpeg -r 1 -i input.avi -r 24 output.avi
+ffmpeg -r 1 -i input.m2v -r 24 output.avi
@end example
The format option may be needed for raw input files.
@section Main options
@table @option
-@item -L
-Show license.
-
-@item -h
-Show help.
-
-@item -version
-Show version.
-
-@item -formats
-Show available formats, codecs, protocols, ...
+@include fftools-common-opts.texi
-@item -f fmt
+@item -f @var{fmt}
Force format.
-@item -i filename
-input filename
+@item -i @var{filename}
+input file name
@item -y
Overwrite output files.
-@item -t duration
+@item -t @var{duration}
Restrict the transcoded/captured video sequence
to the duration specified in seconds.
@code{hh:mm:ss[.xxx]} syntax is also supported.
-@item -fs limit_size
+@item -fs @var{limit_size}
Set the file size limit.
-@item -ss position
+@item -ss @var{position}
Seek to given time position in seconds.
@code{hh:mm:ss[.xxx]} syntax is also supported.
-@item -itsoffset offset
+@item -itsoffset @var{offset}
Set the input time offset in seconds.
@code{[-]hh:mm:ss[.xxx]} syntax is also supported.
This option affects all the input files that follow it.
Specifying a positive offset means that the corresponding
streams are delayed by 'offset' seconds.
-@item -title string
-Set the title.
-
-@item -timestamp time
+@item -timestamp @var{time}
Set the timestamp.
-@item -author string
-Set the author.
-
-@item -copyright string
-Set the copyright.
-
-@item -comment string
-Set the comment.
+@item -metadata @var{key}=@var{value}
+Set a metadata key/value pair.
-@item -album string
-Set the album.
-
-@item -track number
-Set the track.
-
-@item -year number
-Set the year.
+For example, for setting the title in the output file:
+@example
+ffmpeg -i in.avi -metadata title="my title" out.flv
+@end example
-@item -v verbose
-Control amount of logging.
+@item -v @var{number}
+Set the logging verbosity level.
-@item -target type
+@item -target @var{type}
Specify target file type ("vcd", "svcd", "dvd", "dv", "dv50", "pal-vcd",
"ntsc-svcd", ... ). All the format options (bitrate, codecs,
buffer sizes) are then set automatically. You can just type:
ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
@end example
-@item -dframes number
+@item -dframes @var{number}
Set the number of data frames to record.
-@item -scodec codec
+@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 code
+@item -slang @var{code}
Set the ISO 639 language code (3 letters) of the current subtitle stream.
@end table
@section Video Options
@table @option
-@item -b bitrate
+@item -b @var{bitrate}
Set the video bitrate in bit/s (default = 200 kb/s).
-@item -vframes number
+@item -vframes @var{number}
Set the number of video frames to record.
-@item -r fps
+@item -r @var{fps}
Set frame rate (Hz value, fraction or abbreviation), (default = 25).
-@item -s size
+@item -s @var{size}
Set frame size. The format is @samp{wxh} (ffserver default = 160x128, ffmpeg default = same as source).
The following abbreviations are recognized:
@table @samp
352x288
@item 4cif
704x576
+@item 16cif
+1408x1152
@item qqvga
160x120
@item qvga
1920x1080
@end table
-@item -aspect aspect
+@item -aspect @var{aspect}
Set aspect ratio (4:3, 16:9 or 1.3333, 1.7777).
-@item -croptop size
+@item -croptop @var{size}
Set top crop band size (in pixels).
-@item -cropbottom size
+@item -cropbottom @var{size}
Set bottom crop band size (in pixels).
-@item -cropleft size
+@item -cropleft @var{size}
Set left crop band size (in pixels).
-@item -cropright size
+@item -cropright @var{size}
Set right crop band size (in pixels).
-@item -padtop size
+@item -padtop @var{size}
Set top pad band size (in pixels).
-@item -padbottom size
+@item -padbottom @var{size}
Set bottom pad band size (in pixels).
-@item -padleft size
+@item -padleft @var{size}
Set left pad band size (in pixels).
-@item -padright size
+@item -padright @var{size}
Set right pad band size (in pixels).
-@item -padcolor (hex color)
+@item -padcolor @var{hex_color}
Set color of padded bands. The value for padcolor is expressed
as a six digit hexadecimal number where the first two digits
represent red, the middle two digits green and last two digits
blue (default = 000000 (black)).
@item -vn
Disable video recording.
-@item -bt tolerance
-Set video bitrate tolerance (in bit/s).
-@item -maxrate bitrate
+@item -bt @var{tolerance}
+Set video bitrate tolerance (in bits, default 4000k).
+Has a minimum value of: (target_bitrate/target_framerate).
+In 1-pass mode, bitrate tolerance specifies how far ratecontrol is
+willing to deviate from the target average bitrate value. This is
+not related to min/max bitrate. Lowering tolerance too much has
+an adverse effect on quality.
+@item -maxrate @var{bitrate}
Set max video bitrate (in bit/s).
-@item -minrate bitrate
+Requires -bufsize to be set.
+@item -minrate @var{bitrate}
Set min video bitrate (in bit/s).
-@item -bufsize size
+Most useful in setting up a CBR encode:
+@example
+ffmpeg -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v
+@end example
+It is of little use elsewise.
+@item -bufsize @var{size}
Set video buffer verifier buffer size (in bits).
-@item -vcodec codec
+@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.
@item -sameq
Use same video quality as source (implies VBR).
-@item -pass n
-Select the pass number (1 or 2). It is useful to do two pass
-encoding. The statistics of the video are recorded in the first
-pass and the video is generated at the exact requested bitrate
-in the second pass.
+@item -pass @var{n}
+Select the pass number (1 or 2). It is used to do two-pass
+video encoding. The statistics of the video are recorded in the first
+pass into a log file (see also the option -passlogfile),
+and in the second pass that log file is used to generate the video
+at the exact requested bitrate.
+On pass 1, you may just deactivate audio and set output to null,
+examples for Windows and Unix:
+@example
+ffmpeg -i foo.mov -vcodec libxvid -pass 1 -an -f rawvideo -y NUL
+ffmpeg -i foo.mov -vcodec libxvid -pass 1 -an -f rawvideo -y /dev/null
+@end example
-@item -passlogfile file
-Set two pass logfile name to @var{file}.
+@item -passlogfile @var{prefix}
+Set two-pass log file name prefix to @var{prefix}, the default file name
+prefix is ``ffmpeg2pass''. 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.
+
@end table
@section Advanced Video Options
@table @option
-@item -pix_fmt format
+@item -pix_fmt @var{format}
Set pixel format. Use 'list' as parameter to show all the supported
pixel formats.
-@item -sws_flags flags
-Set SwScaler flags (only available when compiled with SwScaler support).
-@item -g gop_size
+@item -sws_flags @var{flags}
+Set SwScaler flags (only available when compiled with swscale support).
+@item -g @var{gop_size}
Set the group of pictures size.
@item -intra
Use only intra frames.
-@item -vdt n
+@item -vdt @var{n}
Discard threshold.
-@item -qscale q
+@item -qscale @var{q}
Use fixed video quantizer scale (VBR).
-@item -qmin q
+@item -qmin @var{q}
minimum video quantizer scale (VBR)
-@item -qmax q
+@item -qmax @var{q}
maximum video quantizer scale (VBR)
-@item -qdiff q
+@item -qdiff @var{q}
maximum difference between the quantizer scales (VBR)
-@item -qblur blur
-video quantizer scale blur (VBR)
-@item -qcomp compression
-video quantizer scale compression (VBR)
+@item -qblur @var{blur}
+video quantizer scale blur (VBR) (range 0.0 - 1.0)
+@item -qcomp @var{compression}
+video quantizer scale compression (VBR) (default 0.5).
+Constant of ratecontrol equation. Recommended range for default rc_eq: 0.0-1.0
-@item -lmin lambda
+@item -lmin @var{lambda}
minimum video lagrange factor (VBR)
-@item -lmax lambda
+@item -lmax @var{lambda}
max video lagrange factor (VBR)
-@item -mblmin lambda
+@item -mblmin @var{lambda}
minimum macroblock quantizer scale (VBR)
-@item -mblmax lambda
+@item -mblmax @var{lambda}
maximum macroblock quantizer scale (VBR)
These four options (lmin, lmax, mblmin, mblmax) use 'lambda' units,
ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext
@end example
-@item -rc_init_cplx complexity
+@item -rc_init_cplx @var{complexity}
initial complexity for single pass encoding
-@item -b_qfactor factor
+@item -b_qfactor @var{factor}
qp factor between P- and B-frames
-@item -i_qfactor factor
+@item -i_qfactor @var{factor}
qp factor between P- and I-frames
-@item -b_qoffset offset
+@item -b_qoffset @var{offset}
qp offset between P- and B-frames
-@item -i_qoffset offset
+@item -i_qoffset @var{offset}
qp offset between P- and I-frames
-@item -rc_eq equation
+@item -rc_eq @var{equation}
Set rate control equation (@pxref{FFmpeg formula
evaluator}) (default = @code{tex^qComp}).
-@item -rc_override override
+@item -rc_override @var{override}
rate control override for specific intervals
-@item -me_method method
+@item -me_method @var{method}
Set motion estimation method to @var{method}.
Available methods are (from lowest to best quality):
@table @samp
exhaustive search (slow and marginally better than epzs)
@end table
-@item -dct_algo algo
+@item -dct_algo @var{algo}
Set DCT algorithm to @var{algo}. Available values are:
@table @samp
@item 0
FF_DCT_ALTIVEC
@end table
-@item -idct_algo algo
+@item -idct_algo @var{algo}
Set IDCT algorithm to @var{algo}. Available values are:
@table @samp
@item 0
FF_IDCT_SIMPLEARM
@end table
-@item -er n
+@item -er @var{n}
Set error resilience to @var{n}.
@table @samp
@item 1
FF_ER_VERY_AGGRESSIVE
@end table
-@item -ec bit_mask
+@item -ec @var{bit_mask}
Set error concealment to @var{bit_mask}. @var{bit_mask} is a bit mask of
the following values:
@table @samp
FF_EC_DEBLOCK (default = enabled)
@end table
-@item -bf frames
+@item -bf @var{frames}
Use 'frames' B-frames (supported for MPEG-1, MPEG-2 and MPEG-4).
-@item -mbd mode
+@item -mbd @var{mode}
macroblock decision
@table @samp
@item 0
Use four motion vector by macroblock (MPEG-4 only).
@item -part
Use data partitioning (MPEG-4 only).
-@item -bug param
+@item -bug @var{param}
Work around encoder bugs that are not auto-detected.
-@item -strict strictness
+@item -strict @var{strictness}
How strictly to follow the standards.
@item -aic
Enable Advanced intra coding (h263+).
Calculate PSNR of compressed frames.
@item -vstats
Dump video coding statistics to @file{vstats_HHMMSS.log}.
-@item -vstats_file file
+@item -vstats_file @var{file}
Dump video coding statistics to @var{file}.
-@item -vhook module
-Insert video processing @var{module}. @var{module} contains the module
-name and its parameters separated by spaces.
-@item -top n
+@item -top @var{n}
top=1/bottom=0/auto=-1 field first
-@item -dc precision
+@item -dc @var{precision}
Intra_dc_precision.
-@item -vtag fourcc/tag
+@item -vtag @var{fourcc/tag}
Force video tag/fourcc.
@item -qphist
Show QP histogram.
-@item -vbsf bitstream filter
-Bitstream filters available are "dump_extra", "remove_extra", "noise".
+@item -vbsf @var{bitstream_filter}
+Bitstream filters available are "dump_extra", "remove_extra", "noise", "h264_mp4toannexb", "imxdump", "mjpegadump".
+@example
+ffmpeg -i h264.mp4 -vcodec copy -vbsf h264_mp4toannexb -an out.h264
+@end example
@end table
@section Audio Options
@table @option
-@item -aframes number
+@item -aframes @var{number}
Set the number of audio frames to record.
-@item -ar freq
+@item -ar @var{freq}
Set the audio sampling frequency (default = 44100 Hz).
-@item -ab bitrate
+@item -ab @var{bitrate}
Set the audio bitrate in bit/s (default = 64k).
-@item -ac channels
+@item -aq @var{q}
+Set the audio quality (codec-specific, VBR).
+@item -ac @var{channels}
Set the number of audio channels (default = 1).
@item -an
Disable audio recording.
-@item -acodec codec
+@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
@example
ffmpeg -i file.mpg -vcodec copy -acodec ac3 -ab 384k test.mpg -acodec mp2 -ab 192k -newaudio
@end example
-@item -alang code
+@item -alang @var{code}
Set the ISO 639 language code (3 letters) of the current audio stream.
@end table
@section Advanced Audio options:
@table @option
-@item -atag fourcc/tag
+@item -atag @var{fourcc/tag}
Force audio tag/fourcc.
-@item -absf bitstream filter
+@item -absf @var{bitstream_filter}
Bitstream filters available are "dump_extra", "remove_extra", "noise", "mp3comp", "mp3decomp".
@end table
@section Subtitle options:
@table @option
-@item -scodec codec
+@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 code
+@item -slang @var{code}
Set the ISO 639 language code (3 letters) of the current subtitle stream.
+@item -sn
+Disable subtitle recording.
+@item -sbsf @var{bitstream_filter}
+Bitstream filters available are "mov2textsub", "text2movsub".
+@example
+ffmpeg -i file.mov -an -vn -sbsf mov2textsub -scodec copy -f rawvideo sub.txt
+@end example
@end table
@section Audio/Video grab options
@table @option
-@item -vc channel
+@item -vc @var{channel}
Set video grab channel (DV1394 only).
-@item -tvstd standard
+@item -tvstd @var{standard}
Set television standard (NTSC, PAL (SECAM)).
@item -isync
Synchronize read on input.
@section Advanced options
@table @option
-@item -map input stream id[:input stream id]
+@item -map @var{input_stream_id}[:@var{sync_stream_id}]
Set stream mapping from input streams to output streams.
Just enumerate the input streams in the order you want them in the output.
-[input stream id] sets the (input) stream to sync against.
-@item -map_meta_data outfile:infile
-Set meta data information of outfile from infile.
+@var{sync_stream_id} if specified sets the input stream to sync
+against.
+@item -map_meta_data @var{outfile}:@var{infile}
+Set meta data information of @var{outfile} from @var{infile}.
@item -debug
Print specific debug info.
@item -benchmark
When dumping packets, also dump the payload.
@item -bitexact
Only use bit exact algorithms (for codec testing).
-@item -ps size
-Set packet size in bits.
+@item -ps @var{size}
+Set RTP payload size in bytes.
@item -re
Read input at native frame rate. Mainly used to simulate a grab device.
@item -loop_input
Loop over the input stream. Currently it works only for image
streams. This option is used for automatic FFserver testing.
-@item -loop_output number_of_times
+@item -loop_output @var{number_of_times}
Repeatedly loop output for formats that support looping such as animated GIF
(0 will loop the output infinitely).
-@item -threads count
+@item -threads @var{count}
Thread count.
-@item -vsync parameter
+@item -vsync @var{parameter}
Video sync method. Video will be stretched/squeezed to match the timestamps,
it is done by duplicating and dropping frames. With -map you can select from
which stream the timestamps should be taken. You can leave either video or
audio unchanged and sync the remaining stream(s) to the unchanged one.
-@item -async samples_per_second
+@item -async @var{samples_per_second}
Audio sync method. "Stretches/squeezes" the audio stream to match the timestamps,
the parameter is the maximum samples per second by which the audio is changed.
-async 1 is a special case where only the start of the audio stream is corrected
Finish encoding when the shortest input stream ends.
@item -dts_delta_threshold
Timestamp discontinuity delta threshold.
-@item -muxdelay seconds
+@item -muxdelay @var{seconds}
Set the maximum demux-decode delay.
-@item -muxpreload seconds
+@item -muxpreload @var{seconds}
Set the initial demux-decode delay.
@end table
-@node FFmpeg formula evaluator
+@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 FFmpeg 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 ffmpeg searches for a file named @var{arg}.ffpreset in the
+directories @file{$HOME/.ffmpeg}, and in the datadir defined at
+configuration time (usually @file{PREFIX/share/ffmpeg}) 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 ffmpeg 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}.
+
+@anchor{FFmpeg formula evaluator}
@section FFmpeg formula evaluator
When evaluating a rate control string, FFmpeg uses an internal formula
The following unary operators are available: @code{+}, @code{-},
@code{(...)}.
+The following statements are available: @code{ld}, @code{st},
+@code{while}.
+
The following functions are available:
@table @var
@item sinh(x)
@item sin(x)
@item cos(x)
@item tan(x)
+@item atan(x)
+@item asin(x)
+@item acos(x)
@item exp(x)
@item log(x)
+@item abs(x)
@item squish(x)
@item gauss(x)
-@item abs(x)
+@item mod(x, y)
@item max(x, y)
@item min(x, y)
+@item eq(x, y)
+@item gte(x, y)
@item gt(x, y)
+@item lte(x, y)
@item lt(x, y)
-@item eq(x, y)
@item bits2qp(bits)
@item qp2bits(qp)
@end table
@section Protocols
-The filename can be @file{-} to read from standard input or to write
+The file name can be @file{-} to read from standard input or to write
to standard output.
FFmpeg also handles many protocols specified with an URL syntax.
-Use 'ffmpeg -formats' to see a list of the supported protocols.
+Use 'ffmpeg -protocols' to see a list of the supported protocols.
The protocol @code{http:} is currently used only to communicate with
FFserver (see the FFserver documentation). When FFmpeg will be a
is about as good as JPEG compression).
@item To have very low audio bitrates, reduce the sampling frequency
-(down to 22050 kHz for MPEG audio, 22050 or 11025 for AC3).
+(down to 22050 Hz for MPEG audio, 22050 or 11025 for AC-3).
@item To have a constant quality (but a variable bitrate), use the option
'-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst