FFmpeg is a very fast video and audio converter. It can also grab from
a live audio/video source.
-
+
The command line interface is designed to be intuitive, in the sense
-that ffmpeg tries to figure out all the parameters, when
-possible. You have usually to give only the target bitrate you want.
+that FFmpeg tries to figure out all parameters that can possibly be
+derived automatically. You usually only have to specify the target
+bitrate you want.
FFmpeg can also convert from any sample rate to any other, and resize
video on the fly with a high quality polyphase filter.
System audio source:
@example
-ffmpeg /tmp/out.mpg
+ffmpeg /tmp/out.mpg
@end example
Note that you must activate the right video source and channel before
-launching ffmpeg. You can use any TV viewer such as xawtv
-(@url{http://bytesex.org/xawtv/}) by Gerd Knorr which I find very
-good. You must also set correctly the audio recording levels with a
+launching FFmpeg with any TV viewer such as xawtv
+(@url{http://bytesex.org/xawtv/}) by Gerd Knorr. You also
+have to set the audio recording levels correctly with a
standard mixer.
@section Video and Audio file format conversion
-* ffmpeg can use any supported file format and protocol as input:
+* FFmpeg can use any supported file format and protocol as input:
Examples:
-* You can input from YUV files:
+* You can use YUV files as input:
@example
-ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
+ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
@end example
-It will use the files:
+It will use the files:
@example
/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
The Y files use twice the resolution of the U and V files. They are
raw files, without header. They can be generated by all decent video
decoders. You must specify the size of the image with the @option{-s} option
-if ffmpeg cannot guess it.
+if FFmpeg cannot guess it.
-* You can input from a RAW YUV420P file:
+* You can input from a raw YUV420P file:
@example
ffmpeg -i /tmp/test.yuv /tmp/out.avi
@end example
-The RAW YUV420P is a file containing RAW YUV planar, for each frame first
-come the Y plane followed by U and V planes, which are half vertical and
+test.yuv is a file containing raw YUV planar data. Each frame is composed
+of the Y plane followed by the U and V planes at half vertical and
horizontal resolution.
-* You can output to a RAW YUV420P file:
+* You can output to a raw YUV420P file:
@example
-ffmpeg -i mydivx.avi -o hugefile.yuv
+ffmpeg -i mydivx.avi hugefile.yuv
@end example
* You can set several input files and output files:
ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
@end example
-Convert the audio file a.wav and the raw yuv video file a.yuv
-to mpeg file a.mpg
+Converts the audio file a.wav and the raw YUV video file a.yuv
+to MPEG file a.mpg.
* You can also do audio and video conversions at the same time:
ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
@end example
-Convert the sample rate of a.wav to 22050 Hz and encode it to MPEG audio.
+Converts a.wav to MPEG audio at 22050Hz sample rate.
* You can encode to several formats at the same time and define a
mapping from input stream to output streams:
ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
@end example
-Convert a.wav to a.mp2 at 64 kbits and b.mp2 at 128 kbits. '-map
-file:index' specify which input stream is used for each output
+Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. '-map
+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
ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800 -g 300 -bf 2 -acodec mp3 -ab 128 snatch.avi
@end example
-This is a typical DVD ripper example, input from a VOB file, output
-to an AVI file with MPEG-4 video and MP3 audio, note that in this
-command we use B frames so the MPEG-4 stream is DivX5 compatible, GOP
-size is 300 that means an INTRA frame every 10 seconds for 29.97 fps
-input video. Also the audio stream is MP3 encoded so you need LAME
-support which is enabled using @code{--enable-mp3lame} when
-configuring. The mapping is particularly useful for DVD transcoding
+This is a typical DVD ripping example; the input is a VOB file, the
+output an AVI file with MPEG-4 video and MP3 audio. Note that in this
+command we use B-frames so the MPEG-4 stream is DivX5 compatible, and
+GOP size is 300 which means one intra frame every 10 seconds for 29.97fps
+input video. Furthermore, the audio stream is MP3-encoded so you need
+to enable LAME support by passing @code{--enable-mp3lame} to configure.
+The mapping is particularly useful for DVD transcoding
to get the desired audio language.
-NOTE: to see the supported input formats, use @code{ffmpeg -formats}.
+NOTE: To see the supported input formats, use @code{ffmpeg -formats}.
@c man end
@chapter Invocation
The generic syntax is:
-@example
+@example
@c man begin SYNOPSIS
-ffmpeg [[options][@option{-i} @var{input_file}]]... @{[options] @var{output_file}@}...
+ffmpeg [[infile options][@option{-i} @var{infile}]]... @{[outfile options] @var{outfile}@}...
@c man end
@end example
@c man begin DESCRIPTION
As a general rule, options are applied to the next specified
file. For example, if you give the @option{-b 64} option, it sets the video
-bitrate of the next file. Format option may be needed for raw input
+bitrate of the next file. The format option may be needed for raw input
files.
-By default, ffmpeg tries to convert as losslessly as possible: it
-uses the same audio and video parameter for the outputs as the one
+By default, FFmpeg tries to convert as losslessly as possible: It
+uses the same audio and video parameters for the outputs as the one
specified for the inputs.
@c man end
@table @option
@item -L
-show license
+Show license.
@item -h
-show help
+Show help.
@item -formats
-show available formats, codecs, protocols, ...
+Show available formats, codecs, protocols, ...
-@item -f fmt
-force format
+@item -f fmt
+Force format.
-@item -i filename
-input file name
+@item -i filename
+input filename
-@item -y
-overwrite output files
+@item -y
+Overwrite output files.
-@item -t duration
-set the recording time in seconds. @code{hh:mm:ss[.xxx]} syntax is also
-supported.
+@item -t duration
+Set the recording time in seconds.
+@code{hh:mm:ss[.xxx]} syntax is also supported.
-@item -title string
-set the title
+@item -ss position
+Seek to given time position in seconds.
+@code{hh:mm:ss[.xxx]} syntax is also supported.
-@item -author string
-set the author
+@item -title string
+Set the title.
-@item -copyright string
-set the copyright
+@item -author string
+Set the author.
-@item -comment string
-set the comment
+@item -copyright string
+Set the copyright.
+
+@item -comment string
+Set the comment.
@item -target type
-specify target file type ("vcd", "svcd" or "dvd"). All the format
-options (bitrate, codecs, buffer sizes) are automatically set by this
-option. You can just type:
+Specify target file type ("vcd", "svcd", "dvd", "dv", "pal-vcd",
+"ntsc-svcd", ... ). All the format options (bitrate, codecs,
+buffer sizes) are then set automatically. You can just type:
@example
ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
@end example
+Nevertheless you can specify additional options as long as you know
+they do not conflict with the standard, as in:
+
+@example
+ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
+@end example
+
@item -hq
-activate high quality settings
+Activate high quality settings.
+
+@item -itsoffset 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.
+The offset is added to the timestamps of the input files.
+Specifying a positive offset means that the corresponding
+streams are delayed by 'offset' seconds.
@end table
@table @option
@item -b bitrate
-set the video bitrate in kbit/s (default = 200 kb/s)
-@item -r fps
-set frame rate (default = 25)
-@item -s size
-set frame size. The format is @samp{WxH} (default 160x128). The
-following abbreviations are recognized:
+Set the video bitrate in kbit/s (default = 200 kb/s).
+@item -r fps
+Set frame rate (default = 25).
+@item -s size
+Set frame size. The format is @samp{wxh} (default = 160x128).
+The following abbreviations are recognized:
@table @samp
@item sqcif
128x96
@end table
@item -aspect aspect
-set aspect ratio (4:3, 16:9 or 1.3333, 1.7777)
+Set aspect ratio (4:3, 16:9 or 1.3333, 1.7777).
@item -croptop size
-set top crop band size (in pixels)
+Set top crop band size (in pixels).
@item -cropbottom size
-set bottom crop band size (in pixels)
+Set bottom crop band size (in pixels).
@item -cropleft size
-set left crop band size (in pixels)
+Set left crop band size (in pixels).
@item -cropright size
-set right crop band size (in pixels)
+Set right crop band size (in pixels).
+@item -padtop size
+Set top pad band size (in pixels).
+@item -padbottom size
+Set bottom pad band size (in pixels).
+@item -padleft size
+Set left pad band size (in pixels).
+@item -padright size
+Set right pad band size (in pixels).
+@item -padcolor (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 kbit/s)
+Disable video recording.
+@item -bt tolerance
+Set video bitrate tolerance (in kbit/s).
@item -maxrate bitrate
-set max video bitrate tolerance (in kbit/s)
+Set max video bitrate tolerance (in kbit/s).
@item -minrate bitrate
-set min video bitrate tolerance (in kbit/s)
+Set min video bitrate tolerance (in kbit/s).
@item -bufsize size
-set ratecontrol buffere size (in kbit)
-@item -vcodec codec
-force video codec to @var{codec}. Use the @code{copy} special value to
+Set rate control buffer size (in kbit).
+@item -vcodec 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)
+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 at the exact requested bit rate is generated in the second
-pass.
+@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 -passlogfile file
-select two pass log file name to @var{file}.
+@item -passlogfile file
+Set two pass logfile name to @var{file}.
@end table
@section Advanced Video Options
@table @option
-@item -g gop_size
-set the group of picture size
-@item -intra
-use only intra frames
-@item -qscale q
-use fixed video quantiser scale (VBR)
-@item -qmin q
-min video quantiser scale (VBR)
-@item -qmax q
-max video quantiser scale (VBR)
-@item -qdiff q
-max difference between the quantiser scale (VBR)
-@item -qblur blur
+@item -g gop_size
+Set the group of pictures size.
+@item -intra
+Use only intra frames.
+@item -qscale q
+Use fixed video quantiser scale (VBR).
+@item -qmin q
+minimum video quantiser scale (VBR)
+@item -qmax q
+maximum video quantiser scale (VBR)
+@item -qdiff q
+maximum difference between the quantiser scales (VBR)
+@item -qblur blur
video quantiser scale blur (VBR)
-@item -qcomp compression
+@item -qcomp compression
video quantiser scale compression (VBR)
@item -rc_init_cplx complexity
-initial complexity for 1-pass encoding
+initial complexity for single pass encoding
@item -b_qfactor factor
-qp factor between p and b frames
+qp factor between P- and B-frames
@item -i_qfactor factor
-qp factor between p and i frames
+qp factor between P- and I-frames
@item -b_qoffset offset
-qp offset between p and b frames
+qp offset between P- and B-frames
@item -i_qoffset offset
-qp offset between p and i frames
+qp offset between P- and I-frames
@item -rc_eq equation
-set rate control equation (@pxref{FFmpeg formula
-evaluator}). Default is @code{tex^qComp}.
+Set rate control equation (@pxref{FFmpeg formula
+evaluator}) (default = @code{tex^qComp}).
@item -rc_override override
rate control override for specific intervals
@item -me method
-set motion estimation method to @var{method}. Available methods are
-(from lower to best quality):
+Set motion estimation method to @var{method}.
+Available methods are (from lowest to best quality):
@table @samp
@item zero
Try just the (0, 0) vector.
@end table
@item -dct_algo algo
-set dct algorithm to @var{algo}. Available values are:
+Set DCT algorithm to @var{algo}. Available values are:
@table @samp
@item 0
FF_DCT_AUTO (default)
@end table
@item -idct_algo algo
-set idct algorithm to @var{algo}. Available values are:
+Set IDCT algorithm to @var{algo}. Available values are:
@table @samp
@item 0
FF_IDCT_AUTO (default)
@item 1
-FF_IDCT_INT
+FF_IDCT_INT
@item 2
-FF_IDCT_SIMPLE
+FF_IDCT_SIMPLE
@item 3
-FF_IDCT_SIMPLEMMX
+FF_IDCT_SIMPLEMMX
@item 4
-FF_IDCT_LIBMPEG2MMX
+FF_IDCT_LIBMPEG2MMX
@item 5
-FF_IDCT_PS2
+FF_IDCT_PS2
@item 6
-FF_IDCT_MLIB
+FF_IDCT_MLIB
@item 7
-FF_IDCT_ARM
+FF_IDCT_ARM
@item 8
-FF_IDCT_ALTIVEC
+FF_IDCT_ALTIVEC
@item 9
-FF_IDCT_SH4
+FF_IDCT_SH4
@item 10
-FF_IDCT_SIMPLEARM
+FF_IDCT_SIMPLEARM
@end table
@item -er n
-set error resilience to @var{n}.
+Set error resilience to @var{n}.
@table @samp
-@item 1
-FF_ER_CAREFULL (default)
+@item 1
+FF_ER_CAREFUL (default)
@item 2
FF_ER_COMPLIANT
@item 3
@end table
@item -ec bit_mask
-set error concealment to @var{bit_mask}. @var{bit_mask} is a bit mask of
+Set error concealment to @var{bit_mask}. @var{bit_mask} is a bit mask of
the following values:
@table @samp
@item 1
-FF_EC_GUESS_MVS (default=enabled)
+FF_EC_GUESS_MVS (default = enabled)
@item 2
-FF_EC_DEBLOCK (default=enabled)
+FF_EC_DEBLOCK (default = enabled)
@end table
@item -bf frames
-use 'frames' B frames (supported for MPEG-1, MPEG-2 and MPEG-4)
+Use 'frames' B-frames (supported for MPEG-1, MPEG-2 and MPEG-4).
@item -mbd mode
macroblock decision
@table @samp
@item 0
-FF_MB_DECISION_SIMPLE: use mb_cmp (cannot change it yet in ffmpeg)
+FF_MB_DECISION_SIMPLE: Use mb_cmp (cannot change it yet in FFmpeg).
@item 1
-FF_MB_DECISION_BITS: chooses the one which needs the fewest bits
+FF_MB_DECISION_BITS: Choose the one which needs the fewest bits.
@item 2
-FF_MB_DECISION_RD: rate distoration
+FF_MB_DECISION_RD: rate distortion
@end table
@item -4mv
-use four motion vector by macroblock (only MPEG-4)
+Use four motion vector by macroblock (MPEG-4 only).
@item -part
-use data partitioning (only MPEG-4)
+Use data partitioning (MPEG-4 only).
@item -bug param
-workaround not auto detected encoder bugs
+Work around encoder bugs that are not auto-detected.
@item -strict strictness
-how strictly to follow the standarts
+How strictly to follow the standards.
@item -aic
-enable Advanced intra coding (h263+)
+Enable Advanced intra coding (h263+).
@item -umv
-enable Unlimited Motion Vector (h263+)
+Enable Unlimited Motion Vector (h263+)
@item -deinterlace
-deinterlace pictures
+Deinterlace pictures.
@item -interlace
-force interlacing support in encoder (only MPEG-2 and MPEG-4). Use this option
-if your input file is interlaced and if you want to keep the interlaced
-format for minimum losses. The alternative is to deinterlace the input
-stream with @option{-deinterlace}, but deinterlacing introduces more
-losses.
+Force interlacing support in encoder (MPEG-2 and MPEG-4 only).
+Use this option if your input file is interlaced and you want
+to keep the interlaced format for minimum losses.
+The alternative is to deinterlace the input stream with
+@option{-deinterlace}, but deinterlacing introduces losses.
@item -psnr
-calculate PSNR of compressed frames
+Calculate PSNR of compressed frames.
@item -vstats
-dump video coding statistics to @file{vstats_HHMMSS.log}.
+Dump video coding statistics to @file{vstats_HHMMSS.log}.
@item -vhook module
-insert video processing @var{module}. @var{module} contains the module
+Insert video processing @var{module}. @var{module} contains the module
name and its parameters separated by spaces.
@end table
@section Audio Options
@table @option
-@item -ab bitrate
-set audio bitrate (in kbit/s)
-@item -ar freq
-set the audio sampling freq (default = 44100 Hz)
-@item -ab bitrate
-set the audio bitrate in kbit/s (default = 64)
+@item -ar freq
+Set the audio sampling frequency (default = 44100 Hz).
+@item -ab bitrate
+Set the audio bitrate in kbit/s (default = 64).
@item -ac channels
-set the number of audio channels (default = 1)
+Set the number of audio channels (default = 1).
@item -an
-disable audio recording
+Disable audio recording.
@item -acodec codec
-force audio codec to @var{codec}. Use the @code{copy} special value to
-tell that the raw codec data must be copied as is.
+Force audio codec to @var{codec}. Use the @code{copy} special value to
+specify that the raw codec data must be copied as is.
@end table
@section Audio/Video grab options
@table @option
@item -vd device
-set video grab device (e.g. @file{/dev/video0})
+sEt video grab device (e.g. @file{/dev/video0}).
@item -vc channel
-set video grab channel (DV1394 only)
+Set video grab channel (DV1394 only).
@item -tvstd standard
-set television standard (NTSC, PAL (SECAM))
+Set television standard (NTSC, PAL (SECAM)).
@item -dv1394
-set DV1394 grab
+Set DV1394 grab.
@item -ad device
-set audio device (e.g. @file{/dev/dsp})
+Set audio device (e.g. @file{/dev/dsp}).
@end table
@section Advanced options
@table @option
-@item -map file:stream
-set input stream mapping
+@item -map file:stream
+Set input stream mapping.
@item -debug
-print specific debug info
-@item -benchmark
-add timings for benchmarking
-@item -hex
-dump each input packet
+Print specific debug info.
+@item -benchmark
+Add timings for benchmarking.
+@item -hex
+Dump each input packet.
@item -bitexact
-only use bit exact algorithms (for codec testing)
+Only use bit exact algorithms (for codec testing).
@item -ps size
-set packet size in bits
+Set packet size in bits.
@item -re
-read input at native frame rate. Mainly used to simulate a grab device.
+Read input at native frame rate. Mainly used to simulate a grab device.
@item -loop
-loop over the input stream. Currently it works only for image
-streams. This option is used for ffserver automatic testing.
+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
+Repeatedly loop output for formats that support looping such as animated GIF
+(0 will loop the output infinitely).
@end table
@node FFmpeg formula evaluator
@section FFmpeg formula evaluator
When evaluating a rate control string, FFmpeg uses an internal formula
-evaluator.
+evaluator.
The following binary operators are available: @code{+}, @code{-},
@code{*}, @code{/}, @code{^}.
@settitle FFmpeg video converter
@c man begin SEEALSO
-ffserver(1), ffplay(1) and the html documentation of @file{ffmpeg}.
+ffserver(1), ffplay(1) and the HTML documentation of @file{ffmpeg}.
@c man end
@c man begin AUTHOR
@section Protocols
-The filename can be @file{-} to read from the standard input or to write
-to the standard output.
+The filename can be @file{-} to read from standard input or to write
+to standard output.
-ffmpeg handles also many protocols specified with the URL syntax.
+FFmpeg also handles many protocols specified with an URL syntax.
-Use 'ffmpeg -formats' to have a list of the supported protocols.
+Use 'ffmpeg -formats' 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
+FFserver (see the FFserver documentation). When FFmpeg will be a
video player it will also be used for streaming :-)
@chapter Tips
@itemize
-@item For streaming at very low bit rate application, use a low frame rate
-and a small gop size. This is especially true for real video where
+@item For streaming at very low bitrate application, use a low frame rate
+and a small GOP size. This is especially true for RealVideo where
the Linux player does not seem to be very fast, so it can miss
frames. An example is:
@end example
@item The parameter 'q' which is displayed while encoding is the current
-quantizer. The value of 1 indicates that a very good quality could
-be achieved. The value of 31 indicates the worst quality. If q=31
+quantizer. The value 1 indicates that a very good quality could
+be achieved. The value 31 indicates the worst quality. If q=31 appears
too often, it means that the encoder cannot compress enough to meet
-your bit rate. You must either increase the bit rate, decrease the
+your bitrate. You must either increase the bitrate, decrease the
frame rate or decrease the frame size.
@item If your computer is not fast enough, you can speed up the
compression at the expense of the compression ratio. You can use
'-me zero' to speed up motion estimation, and '-intra' to disable
-completely motion estimation (you have only I frames, which means it
+motion estimation completely (you have only I-frames, which means it
is about as good as JPEG compression).
-@item To have very low bitrates in audio, reduce the sampling frequency
-(down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
+@item To have very low audio bitrates, reduce the sampling frequency
+(down to 22050 kHz for MPEG audio, 22050 or 11025 for AC3).
@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
quality).
@item When converting video files, you can use the '-sameq' option which
-uses in the encoder the same quality factor than in the decoder. It
-allows to be almost lossless in encoding.
+uses the same quality factor in the encoder as in the decoder.
+It allows almost lossless encoding.
@end itemize
FFmpeg supports the following file formats through the @code{libavformat}
library:
-@multitable @columnfractions .4 .1 .1
+@multitable @columnfractions .4 .1 .1 .4
@item Supported File Format @tab Encoding @tab Decoding @tab Comments
@item MPEG audio @tab X @tab X
-@item MPEG1 systems @tab X @tab X
+@item MPEG-1 systems @tab X @tab X
@tab muxed audio and video
-@item MPEG2 PS @tab X @tab X
+@item MPEG-2 PS @tab X @tab X
@tab also known as @code{VOB} file
-@item MPEG2 TS @tab @tab X
+@item MPEG-2 TS @tab @tab X
@tab also known as DVB Transport Stream
-@item ASF@tab X @tab X
-@item AVI@tab X @tab X
-@item WAV@tab X @tab X
+@item ASF@tab X @tab X
+@item AVI@tab X @tab X
+@item WAV@tab X @tab X
@item Macromedia Flash@tab X @tab X
-@tab Only embedded audio is decoded
+@tab Only embedded audio is decoded.
@item FLV @tab X @tab X
@tab Macromedia Flash video files
-@item Real Audio and Video @tab X @tab X
-@item Raw AC3 @tab X @tab X
-@item Raw MJPEG @tab X @tab X
-@item Raw MPEG video @tab X @tab X
-@item Raw PCM8/16 bits, mulaw/Alaw@tab X @tab X
-@item Raw CRI ADX audio @tab X @tab X
-@item SUN AU format @tab X @tab X
+@item Real Audio and Video @tab X @tab X
+@item Raw AC3 @tab X @tab X
+@item Raw MJPEG @tab X @tab X
+@item Raw MPEG video @tab X @tab X
+@item Raw PCM8/16 bits, mulaw/Alaw@tab X @tab X
+@item Raw CRI ADX audio @tab X @tab X
+@item Raw Shorten audio @tab @tab X
+@item SUN AU format @tab X @tab X
@item NUT @tab X @tab X @tab NUT Open Container Format
-@item Quicktime @tab X @tab X
-@item MPEG4 @tab X @tab X
-@tab MPEG4 is a variant of Quicktime
-@item Raw MPEG4 video @tab X @tab X
+@item QuickTime @tab X @tab X
+@item MPEG-4 @tab X @tab X
+@tab MPEG-4 is a variant of QuickTime.
+@item Raw MPEG4 video @tab X @tab X
@item DV @tab X @tab X
@item 4xm @tab @tab X
-@tab 4X Technologies format, used in some games
+@tab 4X Technologies format, used in some games.
@item Playstation STR @tab @tab X
@item Id RoQ @tab @tab X
-@tab used in Quake III, Jedi Knight 2, other computer games
+@tab Used in Quake III, Jedi Knight 2, other computer games.
@item Interplay MVE @tab @tab X
-@tab format used in various Interplay computer games
+@tab Format used in various Interplay computer games.
@item WC3 Movie @tab @tab X
-@tab multimedia format used in Origin's Wing Commander III computer game
+@tab Multimedia format used in Origin's Wing Commander III computer game.
@item Sega FILM/CPK @tab @tab X
-@tab used in many Sega Saturn console games
+@tab Used in many Sega Saturn console games.
@item Westwood Studios VQA/AUD @tab @tab X
-@tab Multimedia formats used in Westwood Studios games
+@tab Multimedia formats used in Westwood Studios games.
@item Id Cinematic (.cin) @tab @tab X
-@tab Used in Quake II
+@tab Used in Quake II.
@item FLIC format @tab @tab X
@tab .fli/.flc files
@item Sierra VMD @tab @tab X
-@tab used in Sierra CD-ROM games
+@tab Used in Sierra CD-ROM games.
+@item Sierra Online @tab @tab X
+@tab .sol files used in Sierra Online games.
+@item Matroska @tab @tab X
+@item Electronic Arts Multimedia @tab @tab X
+@tab Used in various EA games; files have extensions like WVE and UV2.
+@item Nullsoft Video (NSV) format @tab @tab X
+@item ADTS AAC audio @tab X @tab X
+@item Creative VOC @tab X @tab X @tab Created for the Sound Blaster Pro.
+@item American Laser Games MM @tab @tab X
+@tab Multimedia format used in games like Mad Dog McCree
+@item AVS @tab @tab X
+@tab Multimedia format used by the Creature Shock game.
+@item Smacker @tab @tab X
+@tab Multimedia format used by many games.
+@item GXF @tab @tab X
@end multitable
-@code{X} means that the encoding (resp. decoding) is supported.
+@code{X} means that encoding (resp. decoding) is supported.
@section Image Formats
FFmpeg can read and write images for each frame of a video sequence. The
following image formats are supported:
-@multitable @columnfractions .4 .1 .1
+@multitable @columnfractions .4 .1 .1 .4
@item Supported Image Format @tab Encoding @tab Decoding @tab Comments
-@item PGM, PPM @tab X @tab X
-@item PAM @tab X @tab X @tab PAM is a PNM extension with alpha support
+@item PGM, PPM @tab X @tab X
+@item PAM @tab X @tab X @tab PAM is a PNM extension with alpha support.
@item PGMYUV @tab X @tab X @tab PGM with U and V components in YUV 4:2:0
-@item JPEG @tab X @tab X @tab Progressive JPEG is not supported
-@item .Y.U.V @tab X @tab X @tab One raw file per component
-@item Animated GIF @tab X @tab X @tab Only uncompressed GIFs are generated
-@item PNG @tab X @tab X @tab 2 bit and 4 bit/pixel not supported yet
+@item JPEG @tab X @tab X @tab Progressive JPEG is not supported.
+@item .Y.U.V @tab X @tab X @tab one raw file per component
+@item animated GIF @tab X @tab X @tab Only uncompressed GIFs are generated.
+@item PNG @tab X @tab X @tab 2 bit and 4 bit/pixel not supported yet.
+@item SGI @tab X @tab X @tab SGI RGB image format
@end multitable
-@code{X} means that the encoding (resp. decoding) is supported.
+@code{X} means that encoding (resp. decoding) is supported.
@section Video Codecs
-@multitable @columnfractions .4 .1 .1 .7
+@multitable @columnfractions .4 .1 .1 .4
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
-@item MPEG1 video @tab X @tab X
-@item MPEG2 video @tab X @tab X
-@item MPEG4 @tab X @tab X @tab Also known as DIVX4/5
+@item MPEG-1 video @tab X @tab X
+@item MPEG-2 video @tab X @tab X
+@item MPEG-4 @tab X @tab X @tab also known as DivX4/5
@item MSMPEG4 V1 @tab X @tab X
@item MSMPEG4 V2 @tab X @tab X
-@item MSMPEG4 V3 @tab X @tab X @tab Also known as DIVX3
+@item MSMPEG4 V3 @tab X @tab X @tab also known as DivX3
@item WMV7 @tab X @tab X
-@item WMV8 @tab X @tab X @tab Not completely working
-@item H263(+) @tab X @tab X @tab Also known as Real Video 1.0
-@item MJPEG @tab X @tab X
-@item Lossless MJPEG @tab X @tab X
+@item WMV8 @tab X @tab X @tab not completely working
+@item H.261 @tab X @tab X
+@item H.263(+) @tab X @tab X @tab also known as RealVideo 1.0
+@item H.264 @tab @tab X
+@item RealVideo 1.0 @tab X @tab X
+@item RealVideo 2.0 @tab X @tab X
+@item MJPEG @tab X @tab X
+@item lossless MJPEG @tab X @tab X
+@item JPEG-LS @tab X @tab X @tab fourcc: MJLS, lossless and near-lossless is supported
@item Apple MJPEG-B @tab @tab X
@item Sunplus MJPEG @tab @tab X @tab fourcc: SP5X
-@item DV @tab X @tab X
-@item Huff YUV @tab X @tab X
-@item FFmpeg Video 1 @tab X @tab X @tab Lossless codec (fourcc: FFV1)
+@item DV @tab X @tab X
+@item HuffYUV @tab X @tab X
+@item FFmpeg Video 1 @tab X @tab X @tab experimental lossless codec (fourcc: FFV1)
+@item FFmpeg Snow @tab X @tab X @tab experimental wavelet codec (fourcc: SNOW)
@item Asus v1 @tab X @tab X @tab fourcc: ASV1
@item Asus v2 @tab X @tab X @tab fourcc: ASV2
@item Creative YUV @tab @tab X @tab fourcc: CYUV
-@item H.264 @tab @tab X
-@item Sorenson Video 1 @tab @tab X @tab fourcc: SVQ1
+@item Sorenson Video 1 @tab X @tab X @tab fourcc: SVQ1
@item Sorenson Video 3 @tab @tab X @tab fourcc: SVQ3
@item On2 VP3 @tab @tab X @tab still experimental
@item Theora @tab @tab X @tab still experimental
-@item Intel Indeo 3 @tab @tab X @tab only works on i386 right now
-@item FLV @tab X @tab X @tab Flash H263 variant
+@item Intel Indeo 3 @tab @tab X
+@item FLV @tab X @tab X @tab Sorenson H.263 used in Flash
+@item Flash Screen Video @tab @tab X @tab fourcc: FSV1
@item ATI VCR1 @tab @tab X @tab fourcc: VCR1
@item ATI VCR2 @tab @tab X @tab fourcc: VCR2
@item Cirrus Logic AccuPak @tab @tab X @tab fourcc: CLJR
-@item 4X Video @tab @tab X @tab used in certain computer games
-@item Sony Playstation MDEC @tab @tab X
-@item Id RoQ @tab @tab X @tab used in Quake III, Jedi Knight 2, other computer games
-@item Xan/WC3 @tab @tab X @tab used in Wing Commander III .MVE files
-@item Interplay Video @tab @tab X @tab used in Interplay .MVE files
+@item 4X Video @tab @tab X @tab Used in certain computer games.
+@item Sony Playstation MDEC @tab @tab X
+@item Id RoQ @tab @tab X @tab Used in Quake III, Jedi Knight 2, other computer games.
+@item Xan/WC3 @tab @tab X @tab Used in Wing Commander III .MVE files.
+@item Interplay Video @tab @tab X @tab Used in Interplay .MVE files.
+@item Apple Animation @tab @tab X @tab fourcc: 'rle '
@item Apple Graphics @tab @tab X @tab fourcc: 'smc '
@item Apple Video @tab @tab X @tab fourcc: rpza
+@item Apple QuickDraw @tab @tab X @tab fourcc: qdrw
@item Cinepak @tab @tab X
@item Microsoft RLE @tab @tab X
@item Microsoft Video-1 @tab @tab X
@item Westwood VQA @tab @tab X
-@item Id Cinematic Video @tab @tab X @tab used in Quake II
+@item Id Cinematic Video @tab @tab X @tab Used in Quake II.
@item Planar RGB @tab @tab X @tab fourcc: 8BPS
@item FLIC video @tab @tab X
@item Duck TrueMotion v1 @tab @tab X @tab fourcc: DUCK
-@item VMD Video @tab @tab X @tab used in Sierra VMD files
+@item Duck TrueMotion v2 @tab @tab X @tab fourcc: TM20
+@item VMD Video @tab @tab X @tab Used in Sierra VMD files.
+@item MSZH @tab @tab X @tab Part of LCL
+@item ZLIB @tab X @tab X @tab Part of LCL, encoder experimental
+@item TechSmith Camtasia @tab @tab X @tab fourcc: TSCC
+@item IBM Ultimotion @tab @tab X @tab fourcc: ULTI
+@item Miro VideoXL @tab @tab X @tab fourcc: VIXL
+@item QPEG @tab @tab X @tab fourccs: QPEG, Q1.0, Q1.1
+@item LOCO @tab @tab X @tab
+@item Winnov WNV1 @tab @tab X @tab
+@item Autodesk Animator Studio Codec @tab @tab X @tab fourcc: AASC
+@item Fraps FPS1 @tab @tab X @tab
+@item CamStudio @tab @tab X @tab fourcc: CSCD
+@item American Laser Games Video @tab @tab X @tab Used in games like Mad Dog McCree
+@item ZMBV @tab @tab X @tab
+@item AVS Video @tab @tab X @tab Video encoding used by the Creature Shock game.
+@item Smacker Video @tab @tab X @tab Video encoding used in Smacker.
+@item RTjpeg @tab @tab X @tab Video encoding used in NuppelVideo files.
+@item KMVC @tab @tab X @tab Codec used in Worms games.
@end multitable
-@code{X} means that the encoding (resp. decoding) is supported.
+@code{X} means that encoding (resp. decoding) is supported.
-Check at @url{http://www.mplayerhq.hu/~michael/codec-features.html} to
-get a precise comparison of FFmpeg MPEG4 codec compared to the other
-solutions.
+See @url{http://mplayerhq.hu/~michael/codec-features.html} to
+get a precise comparison of the FFmpeg MPEG-4 codec compared to
+other implementations.
@section Audio Codecs
@multitable @columnfractions .4 .1 .1 .1 .7
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
-@item MPEG audio layer 2 @tab IX @tab IX
+@item MPEG audio layer 2 @tab IX @tab IX
@item MPEG audio layer 1/3 @tab IX @tab IX
-@tab MP3 encoding is supported through the external library LAME
-@item AC3 @tab IX @tab X
-@tab liba52 is used internally for decoding
+@tab MP3 encoding is supported through the external library LAME.
+@item AC3 @tab IX @tab IX
+@tab liba52 is used internally for decoding.
@item Vorbis @tab X @tab X
-@tab supported through the external library libvorbis
+@tab Supported through the external library libvorbis.
@item WMA V1/V2 @tab @tab X
-@item Microsoft ADPCM @tab @tab X
+@item AAC @tab X @tab X
+@tab Supported through the external library libfaac/libfaad.
+@item Microsoft ADPCM @tab X @tab X
@item MS IMA ADPCM @tab X @tab X
@item QT IMA ADPCM @tab @tab X
@item 4X IMA ADPCM @tab @tab X
+@item G.726 ADPCM @tab X @tab X
@item Duck DK3 IMA ADPCM @tab @tab X
-@tab used in some Sega Saturn console games
+@tab Used in some Sega Saturn console games.
@item Duck DK4 IMA ADPCM @tab @tab X
-@tab used in some Sega Saturn console games
+@tab Used in some Sega Saturn console games.
@item Westwood Studios IMA ADPCM @tab @tab X
-@tab used in Westwood Studios games like Command and Conquer
+@tab Used in Westwood Studios games like Command and Conquer.
+@item SMJPEG IMA ADPCM @tab @tab X
+@tab Used in certain Loki game ports.
@item CD-ROM XA ADPCM @tab @tab X
@item CRI ADX ADPCM @tab X @tab X
-@tab used in Sega Dreamcast games
+@tab Used in Sega Dreamcast games.
+@item Electronic Arts ADPCM @tab @tab X
+@tab Used in various EA titles.
+@item Creative ADPCM @tab @tab X
+@tab 16 -> 4, 8 -> 4, 8 -> 3, 8 -> 2
@item RA144 @tab @tab X
@tab Real 14400 bit/s codec
@item RA288 @tab @tab X
@tab Real 28800 bit/s codec
+@item RADnet @tab X @tab IX
+@tab Real low bitrate AC3 codec, liba52 is used for decoding.
@item AMR-NB @tab X @tab X
-@tab supported through an external library
+@tab Supported through an external library.
@item AMR-WB @tab X @tab X
-@tab supported through an external library
+@tab Supported through an external library.
@item DV audio @tab @tab X
@item Id RoQ DPCM @tab @tab X
-@tab used in Quake III, Jedi Knight 2, other computer games
+@tab Used in Quake III, Jedi Knight 2, other computer games.
@item Interplay MVE DPCM @tab @tab X
-@tab used in various Interplay computer games
+@tab Used in various Interplay computer games.
@item Xan DPCM @tab @tab X
-@tab used in Origin's Wing Commander IV AVI files
+@tab Used in Origin's Wing Commander IV AVI files.
+@item Sierra Online DPCM @tab @tab X
+@tab Used in Sierra Online game audio files.
@item Apple MACE 3 @tab @tab X
@item Apple MACE 6 @tab @tab X
+@item FLAC lossless audio @tab @tab X
+@item Shorten lossless audio @tab @tab X
+@item Apple lossless audio @tab @tab X
+@tab QuickTime fourcc 'alac'
+@item FFmpeg Sonic @tab X @tab X
+@tab experimental lossy/lossless codec
+@item Qdesign QDM2 @tab @tab X
+@tab there are still some distortions
+@item Real COOK @tab @tab X
+@tab All versions except 5.1 are supported
+@item DSP Group TrueSpeech @tab @tab X
+@item True Audio (TTA) @tab @tab X
+@item Smacker Audio @tab @tab X
@end multitable
-@code{X} means that the encoding (resp. decoding) is supported.
+@code{X} means that encoding (resp. decoding) is supported.
-@code{I} means that an integer only version is available too (ensures highest
-performances on systems without hardware floating point support).
+@code{I} means that an integer-only version is available, too (ensures high
+performance on systems without hardware floating point support).
@chapter Platform Specific information
@section Linux
-ffmpeg should be compiled with at least GCC 2.95.3. GCC 3.2 is the
-preferred compiler now for ffmpeg. All future optimizations will depend on
+FFmpeg should be compiled with at least GCC 2.95.3. GCC 3.2 is the
+preferred compiler now for FFmpeg. All future optimizations will depend on
features only found in GCC 3.2.
@section BSD
+BSD make will not build FFmpeg, you need to install and use GNU Make
+(@file{gmake}).
+
@section Windows
@subsection Native Windows compilation
@url{http://www.mingw.org/}. You can find detailed installation
instructions in the download section and the FAQ.
-@item If you want to test the FFmpeg Simple Media Player, also download
+@item If you want to test the FFplay, also download
the MinGW development library of SDL 1.2.x
(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
-@url{http://www.libsdl.org}. Unpack it in a temporary place, and
+@url{http://www.libsdl.org}. Unpack it in a temporary directory, and
unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
directory. Edit the @file{sdl-config} script so that it gives the
correct SDL directory when invoked.
-@item Extract the current version of FFmpeg (the latest release version or the current CVS snapshot whichever is recommended).
-
+@item Extract the current version of FFmpeg.
+
@item Start the MSYS shell (file @file{msys.bat}).
-@item Change to the FFMPEG directory and follow
- the instructions of how to compile ffmpeg (file
+@item Change to the FFmpeg directory and follow
+ the instructions of how to compile FFmpeg (file
@file{INSTALL}). Usually, launching @file{./configure} and @file{make}
suffices. If you have problems using SDL, verify that
@file{sdl-config} can be launched from the MSYS command line.
-@item You can install FFmpeg in @file{Program Files/FFmpeg} by typing @file{make install}. Don't forget to copy @file{SDL.dll} at the place you launch
-@file{ffplay}.
+@item You can install FFmpeg in @file{Program Files/FFmpeg} by typing
+@file{make install}. Don't forget to copy @file{SDL.dll} to the place
+you launch @file{ffplay} from.
@end itemize
-Notes:
+Notes:
@itemize
@item The target @file{make wininstaller} can be used to create a
Nullsoft based Windows installer for FFmpeg and FFplay. @file{SDL.dll}
-must be copied in the ffmpeg directory in order to build the
+must be copied to the FFmpeg directory in order to build the
installer.
-@item By using @code{./configure --enable-shared} when configuring ffmpeg,
+@item By using @code{./configure --enable-shared} when configuring FFmpeg,
you can build @file{avcodec.dll} and @file{avformat.dll}. With
@code{make install} you install the FFmpeg DLLs and the associated
-headers in @file{Program Files/FFmpeg}.
+headers in @file{Program Files/FFmpeg}.
-@item Visual C++ compatibility: if you used @code{./configure --enable-shared}
-when configuring FFmpeg, then FFmpeg tries to use the Microsoft Visual
+@item Visual C++ compatibility: If you used @code{./configure --enable-shared}
+when configuring FFmpeg, FFmpeg tries to use the Microsoft Visual
C++ @code{lib} tool to build @code{avcodec.lib} and
-@code{avformat.lib}. With these libraries, you can link your Visual C++
-code directly with the FFmpeg DLLs.
+@code{avformat.lib}. With these libraries you can link your Visual C++
+code directly with the FFmpeg DLLs (see below).
@end itemize
+@subsection Visual C++ compatibility
+
+FFmpeg will not compile under Visual C++ -- and it has too many
+dependencies on the GCC compiler to make a port viable. However,
+if you want to use the FFmpeg libraries in your own applications,
+you can still compile those applications using Visual C++. An
+important restriction to this is that you have to use the
+dynamically linked versions of the FFmpeg libraries (i.e. the
+DLLs), and you have to make sure that Visual-C++-compatible
+import libraries are created during the FFmpeg build process.
+
+This description of how to use the FFmpeg libraries with Visual C++ is
+based on Visual C++ 2005 Express Edition Beta 2. If you have a different
+version, you might have to modify the procedures slightly.
+
+Here are the step-by-step instructions for building the FFmpeg libraries
+so they can be used with Visual C++:
+
+@enumerate
+
+@item Install Visual C++ (if you haven't done so already).
+
+@item Install MinGW and MSYS as described above.
+
+@item Add a call to @file{vcvars32.bat} (which sets up the environment
+variables for the Visual C++ tools) as the first line of
+@file{msys.bat}. The standard location for @file{vcvars32.bat} is
+@file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
+and the standard location for @file{msys.bat} is
+@file{C:\msys\1.0\msys.bat}. If this corresponds to your setup, add the
+following line as the first line of @file{msys.bat}:
+
+@code{call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"}
+
+@item Start the MSYS shell (file @file{msys.bat}) and type @code{link.exe}.
+If you get a help message with the command line options of @code{link.exe},
+this means your environment variables are set up correctly, the
+Microsoft linker is on the path and will be used by FFmpeg to
+create Visual-C++-compatible import libraries.
+
+@item Extract the current version of FFmpeg and change to the FFmpeg directory.
+
+@item Type the command
+@code{./configure --enable-shared --disable-static --enable-memalign-hack}
+to configure and, if that didn't produce any errors,
+type @code{make} to build FFmpeg.
+
+@item The subdirectories @file{libavformat}, @file{libavcodec}, and
+@file{libavutil} should now contain the files @file{avformat.dll},
+@file{avformat.lib}, @file{avcodec.dll}, @file{avcodec.lib},
+@file{avutil.dll}, and @file{avutil.lib}, respectively. Copy the three
+DLLs to your System32 directory (typically @file{C:\Windows\System32}).
+
+@end enumerate
+
+And here is how to use these libraries with Visual C++:
+
+@enumerate
+
+@item Create a new console application ("File / New / Project") and then
+select "Win32 Console Application". On the appropriate page of the
+Application Wizard, uncheck the "Precompiled headers" option.
+
+@item Write the source code for your application, or, for testing, just
+copy the code from an existing sample application into the source file
+that Visual C++ has already created for you. (Note that your source
+filehas to have a @code{.cpp} extension; otherwise, Visual C++ won't
+compile the FFmpeg headers correctly because in C mode, it doesn't
+recognize the @code{inline} keyword.) For example, you can copy
+@file{output_example.c} from the FFmpeg distribution (but you will
+have to make minor modifications so the code will compile under
+C++, see below).
+
+@item Open the "Project / Properties" dialog box. In the "Configuration"
+combo box, select "All Configurations" so that the changes you make will
+affect both debug and release builds. In the tree view on the left hand
+side, select "C/C++ / General", then edit the "Additional Include
+Directories" setting to contain the complete paths to the
+@file{libavformat}, @file{libavcodec}, and @file{libavutil}
+subdirectories of your FFmpeg directory. Note that the directories have
+to be separated using semicolons. Now select "Linker / General" from the
+tree view and edit the "Additional Library Directories" setting to
+contain the same three directories.
+
+@item Still in the "Project / Properties" dialog box, select "Linker / Input"
+from the tree view, then add the files @file{avformat.lib},
+@file{avcodec.lib}, and @file{avutil.lib} to the end of the "Additional
+Dependencies". Note that the names of the libraries have to be separated
+using spaces.
+
+@item Now, select "C/C++ / Code Generation" from the tree view. Select
+"Debug" in the "Configuration" combo box. Make sure that "Runtime
+Library" is set to "Multi-threaded Debug DLL". Then, select "Release" in
+the "Configuration" combo box and make sure that "Runtime Library" is
+set to "Multi-threaded DLL".
+
+@item Click "OK" to close the "Project / Properties" dialog box and build
+the application. Hopefully, it should compile and run cleanly. If you
+used @file{output_example.c} as your sample application, you will get a
+few compiler errors, but they are easy to fix. The first type of error
+occurs because Visual C++ doesn't allow an @code{int} to be converted to
+an @code{enum} without a cast. To solve the problem, insert the required
+casts (this error occurs once for a @code{CodecID} and once for a
+@code{CodecType}). The second type of error occurs because C++ requires
+the return value of @code{malloc} to be cast to the exact type of the
+pointer it is being assigned to. Visual C++ will complain that, for
+example, @code{(void *)} is being assigned to @code{(uint8_t *)} without
+an explicit cast. So insert an explicit cast in these places to silence
+the compiler. The third type of error occurs because the @code{snprintf}
+library function is called @code{_snprintf} under Visual C++. So just
+add an underscore to fix the problem. With these changes,
+@file{output_example.c} should compile under Visual C++, and the
+resulting executable should produce valid video files.
+
+@end enumerate
+
@subsection Cross compilation for Windows with Linux
You must use the MinGW cross compilation tools available at
@url{http://www.mingw.org/}.
-Then configure ffmpeg with the following options:
+Then configure FFmpeg with the following options:
@example
./configure --enable-mingw32 --cross-prefix=i386-mingw32msvc-
@end example
-(you can change the cross-prefix according to the prefix choosen for the
+(you can change the cross-prefix according to the prefix chosen for the
MinGW tools).
-Then you can easily test ffmpeg with wine
+Then you can easily test FFmpeg with Wine
(@url{http://www.winehq.com/}).
-@section MacOS X
+@section Mac OS X
@section BeOS
Old stuff:
-François Revol - revol at free dot fr - April 2002
+François Revol - revol at free dot fr - April 2002
-The configure script should guess the configuration itself,
-however I still didn't tested building on net_server version of BeOS.
+The configure script should guess the configuration itself,
+however I still didn't test building on the net_server version of BeOS.
-ffserver is broken (needs poll() implementation).
+FFserver is broken (needs poll() implementation).
-There is still issues with errno codes, which are negative in BeOs, and
-that ffmpeg negates when returning. This ends up turning errors into
+There are still issues with errno codes, which are negative in BeOS, and
+that FFmpeg negates when returning. This ends up turning errors into
valid results, then crashes.
(To be fixed)
@chapter Developers Guide
@section API
-@itemize
+@itemize @bullet
@item libavcodec is the library containing the codecs (both encoding and
- decoding). See @file{libavcodec/apiexample.c} to see how to use it.
+decoding). Look at @file{libavcodec/apiexample.c} to see how to use it.
-@item libavformat is the library containing the file formats handling (mux and
- demux code for several formats). See @file{ffplay.c} to use it in a
+@item libavformat is the library containing the file format handling (mux and
+demux code for several formats). Look at @file{ffplay.c} to use it in a
player. See @file{output_example.c} to use it to generate audio or video
streams.
You can use libavcodec or libavformat in your commercial program, but
@emph{any patch you make must be published}. The best way to proceed is
-to send your patches to the ffmpeg mailing list.
+to send your patches to the FFmpeg mailing list.
+@node Coding Rules
@section Coding Rules
-ffmpeg is programmed in ANSI C language. GCC extensions are
-tolerated. Indent size is 4. The TAB character should not be used.
+FFmpeg is programmed in the ISO C90 language with a few additional
+features from ISO C99, namely:
+@itemize @bullet
+@item
+the @samp{inline} keyword;
+@item
+@samp{//} comments;
+@item
+designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
+@item
+compound literals (@samp{x = (struct s) @{ 17, 23 @};})
+@end itemize
+
+These features are supported by all compilers we care about, so we won't
+accept patches to remove their use unless they absolutely don't impair
+clarity and performance.
+
+All code must compile with GCC 2.95 and GCC 3.3. Currently, FFmpeg also
+compiles with several other compilers, such as the Compaq ccc compiler
+or Sun Studio 9, and we would like to keep it that way unless it would
+be exceedingly involved. To ensure compatibility, please don't use any
+additional C99 features or GCC extensions. Especially watch out for:
+@itemize @bullet
+@item
+mixing statements and declarations;
+@item
+@samp{long long} (use @samp{int64_t} instead);
+@item
+@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
+@item
+GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
+@end itemize
-The presentation is the one specified by 'indent -i4 -kr'.
+Indent size is 4.
+The presentation is the one specified by 'indent -i4 -kr -nut'.
+The TAB character is forbidden outside of Makefiles as is any
+form of trailing whitespace. Commits containing either will be
+rejected by the Subversion repository.
-Main priority in ffmpeg is simplicity and small code size (=less
+Main priority in FFmpeg is simplicity and small code size (=less
bugs).
-Comments: for functions visible from other modules, use the JavaDoc
-format (see examples in @file{libav/utils.c}) so that a documentation
-can be generated automatically.
+Comments: Use the JavaDoc/Doxygen
+format (see examples below) so that code documentation
+can be generated automatically. All nontrivial functions should have a comment
+above them explaining what the function does, even if it's just one sentence.
+All structures and their member variables should be documented, too.
+@example
+/**
+ * @@file mpeg.c
+ * MPEG codec.
+ * @@author ...
+ */
+
+/**
+ * Summary sentence.
+ * more text ...
+ * ...
+ */
+typedef struct Foobar@{
+ int var1; /**< var1 description */
+ int var2; ///< var2 description
+ /** var3 description */
+ int var3;
+@} Foobar;
+
+/**
+ * Summary sentence.
+ * more text ...
+ * ...
+ * @@param my_parameter description of my_parameter
+ * @@return return value description
+ */
+int myfunc(int my_parameter)
+...
+@end example
+
+fprintf and printf are forbidden in libavformat and libavcodec,
+please use av_log() instead.
+
+@section Development Policy
+
+@enumerate
+@item
+ You must not commit code which breaks FFmpeg! (Meaning unfinished but
+ enabled code which breaks compilation or compiles but does not work or
+ breaks the regression tests)
+ You can commit unfinished stuff (for testing etc), but it must be disabled
+ (#ifdef etc) by default so it does not interfere with other developers'
+ work.
+@item
+ You don't have to over-test things. If it works for you, and you think it
+ should work for others, then commit. If your code has problems
+ (portability, triggers compiler bugs, unusual environment etc) they will be
+ reported and eventually fixed.
+@item
+ Do not commit unrelated changes together, split them into self-contained
+ pieces.
+@item
+ Do not change behavior of the program (renaming options etc) without
+ first discussing it on the ffmpeg-devel mailing list. Do not remove
+ functionality from the code. Just improve!
+
+ Note: Redundant code can be removed.
+@item
+ Do not commit changes to the build system (Makefiles, configure script)
+ which change behavior, defaults etc, without asking first. The same
+ applies to compiler warning fixes, trivial looking fixes and to code
+ maintained by other developers. We usually have a reason for doing things
+ the way we do. Send your changes as patches to the ffmpeg-devel mailing
+ list, and if the code maintainers say OK, you may commit. This does not
+ apply to files you wrote and/or maintain.
+@item
+ We refuse source indentation and other cosmetic changes if they are mixed
+ with functional changes, such commits will be rejected and removed. Every
+ developer has his own indentation style, you should not change it. Of course
+ if you (re)write something, you can use your own style, even though we would
+ prefer if the indentation throughout FFmpeg was consistent (Many projects
+ force a given indentation style - we don't.). If you really need to make
+ indentation changes (try to avoid this), separate them strictly from real
+ changes.
+
+ NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code,
+ then either do NOT change the indentation of the inner part within (don't
+ move it to the right)! or do so in a separate commit
+@item
+ Always fill out the commit log message. Describe in a few lines what you
+ changed and why. You can refer to mailing list postings if you fix a
+ particular bug. Comments such as "fixed!" or "Changed it." are unacceptable.
+@item
+ If you apply a patch by someone else, include the name and email address in
+ the log message. Since the ffmpeg-cvslog mailing list is publicly
+ archived you should add some SPAM protection to the email address. Send an
+ answer to ffmpeg-devel (or wherever you got the patch from) saying that
+ you applied the patch.
+@item
+ Do NOT commit to code actively maintained by others without permission.
+ Send a patch to ffmpeg-devel instead. If noone answers within a reasonable
+ timeframe (12h for build failures and security fixes, 3 days small changes,
+ 1 week for big patches) then commit your patch if you think it's OK.
+ Also note, the maintainer can simply ask for more time to review!
+@item
+ Subscribe to the ffmpeg-cvslog mailing list. The diffs of all commits
+ are sent there and reviewed by all the other developers. Bugs and possible
+ improvements or general questions regarding commits are discussed there. We
+ expect you to react if problems with your code are uncovered.
+@item
+ Update the documentation if you change behavior or add features. If you are
+ unsure how best to do this, send a patch to ffmpeg-devel, the documentation
+ maintainer(s) will review and commit your stuff.
+@item
+ Never write to unallocated memory, never write over the end of arrays,
+ always check values read from some untrusted source before using them
+ as array index or other risky things.
+@item
+ Remember to check if you need to bump versions for the specific libav
+ parts (libavutil, libavcodec, libavformat) you are changing. You need
+ to change the version integer and the version string.
+ Incrementing the first component means no backward compatibility to
+ previous versions (e.g. removal of a function).
+ Incrementing the second component means backward compatible change
+ (e.g. addition of a function).
+ Incrementing the third component means a noteworthy binary compatible
+ change (e.g. encoder bug fix that matters for the decoder).
+@item
+ If you add a new codec, remember to update the changelog, add it to
+ the supported codecs table in the documentation and bump the second
+ component of the @file{libavcodec} version number appropriately. If
+ it has a fourcc, add it to @file{libavformat/avienc.c}, even if it
+ is only a decoder.
+@end enumerate
+
+We think our rules are not too hard. If you have comments, contact us.
+
+Note, these rules are mostly borrowed from the MPlayer project.
@section Submitting patches
+First, (@pxref{Coding Rules}) above if you didn't yet.
+
When you submit your patch, try to send a unified diff (diff '-up'
option). I cannot read other diffs :-)
+Also please do not submit patches which contain several unrelated changes.
+Split them into individual self-contained patches; this makes reviewing
+them much easier.
+
Run the regression tests before submitting a patch so that you can
verify that there are no big problems.
Patches should be posted as base64 encoded attachments (or any other
-encoding which ensures that the patch wont be trashed during
-transmission) to the ffmpeg-devel mailinglist, see
-@url{http://lists.sourceforge.net/lists/listinfo/ffmpeg-devel}
+encoding which ensures that the patch won't be trashed during
+transmission) to the ffmpeg-devel mailing list, see
+@url{http://lists.mplayerhq.hu/mailman/listinfo/ffmpeg-devel}
It also helps quite a bit if you tell us what the patch does (for example
-'replaces lrint by lrintf') , and why (for example '*bsd isnt c99 compliant
+'replaces lrint by lrintf'), and why (for example '*BSD isn't C99 compliant
and has no lrint()')
+We reply to all submitted patches and either apply or reject with some
+explanation why, but sometimes we are quite busy so it can take a week or two.
+
@section Regression tests
-Before submitting a patch (or committing with CVS), you should at least
+Before submitting a patch (or committing to the repository), you should at least
test that you did not break anything.
-The regression test build a synthetic video stream and a synthetic
-audio stream. Then these are encoded then decoded with all codecs or
+The regression tests build a synthetic video stream and a synthetic
+audio stream. These are then encoded and decoded with all codecs or
formats. The CRC (or MD5) of each generated file is recorded in a
-result file. Then a 'diff' is launched with the reference results and
+result file. A 'diff' is launched to compare the reference results and
the result file.
-The regression test then goes on to test the ffserver code with a
+The regression tests then go on to test the FFserver code with a
limited set of streams. It is important that this step runs correctly
as well.
-Run 'make test' to test all the codecs.
+Run 'make test' to test all the codecs and formats.
-Run 'make fulltest' to test all the codecs, formats and ffserver.
+Run 'make fulltest' to test all the codecs, formats and FFserver.
-[Of course, some patches may change the regression tests results. In
-this case, the regression tests reference results shall be modified
+[Of course, some patches may change the results of the regression tests. In
+this case, the reference results of the regression tests shall be modified
accordingly].
@bye
projects / ffmpeg / blobdiff