added FAQ - you are free to add entries - the web page faq is generated from this...
[ffmpeg.git] / doc / ffmpeg.txt
index b7fffcd..7352a66 100644 (file)
@@ -1,6 +1,39 @@
-* ffmpeg can use YUV files as input : 
+*************** FFMPEG soft VCR documentation *****************
 
-  ffmpeg /tmp/out.mpg /tmp/test
+0) Introduction
+---------------
+
+  FFmpeg is a very fast video and audio encoder. It can grab from
+  files or 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 paramters, when
+  possible. You have usually to give only 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.
+
+1) Video and Audio grabbing
+---------------------------
+
+* ffmpeg can use a video4linux compatible video source and any Open
+  Sound System audio source:
+
+  ffmpeg /tmp/out.mpg 
+
+  Note that you must activate the right video source and channel
+  before launching ffmpeg. You can use any TV viewer such as xawtv by
+  Gerd Knorr which I find very good. You must also set correctly the
+  audio recording levels with a standard mixer.
+
+2) Video and Audio file format convertion
+-----------------------------------------
+
+* ffmpeg can use any supported file format and protocol as input : 
+
+examples:
+
+  ffmpeg -i /tmp/test%d.Y /tmp/out.mpg 
 
 If will use the files: 
 /tmp/test0.Y, /tmp/test0.U, /tmp/test0.V, 
@@ -8,48 +41,118 @@ If will use the files:
 
 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.
+decoders. You must specify the size of the image with the '-s' option
+if ffmpeg cannot guess it.
 
-* ffmpeg can use a video4linux compatible video source : 
+* You can set several input files and output files:
 
-  ffmpeg /tmp/out.mpg 
+  ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
 
-  Note that you must activate the right video source and channel
-  before launching ffmpeg. You can use any TV viewer such as xawtv by
-  Gerd Knorr which I find very good.
+Convert the audio file a.wav and the raw yuv video file a.yuv  to mpeg file a.mpg
 
-* There are some importants options to know:
+* you can also do audio and video convertions at the same time:
 
--s size      set frame size                [160x128]
--f format    set encoding format           [mpeg1]
--r fps       set frame rate                [25]
--b bitrate   set the bitrate in kbit/s     [100]
--t time      set recording time in seconds [10.0]
+  ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
 
-The frame size can also be: cif, qcif, sqcif and 4cif.
-The encoding format can be mpeg1, h263 or rv10.
+Convert the sample rate of a.wav to 22050 Hz and encode it to MPEG audio.
 
-Advanced options are:
+* 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
+
+  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
+  stream, in the order of the definition of output streams.
+
+NOTE: to see the supported input formats, use 'ffmpeg -formats'.
+
+2) Invocation
+-------------
 
--d device    set video4linux device name
--g gop_size  set the group of picture size. 
-             An 'intra' frame is generated every gop_size frames.
--i           use only intra images (speed up compression, but lower quality).
--c comment   set the comment string.
+* The generic syntax is :
 
-Comment strings are only used for Real Video(tm) encoding. Tags are
-used in the comment string. A typical comment string is:
+  ffmpeg [[options][-i input_file]]... {[options] output_file}...
 
-"+title=Test Video +author=FFMpeg +copyright=Free +comment=Generated by FFMpeg 1.0"
+  If no input file is given, audio/video grabbing is done.
+
+  As a general rule, options are applied to the next specified
+  file. For example, if you give the '-b 64' option, it sets the video
+  bitrate of the next file. 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 fors the outputs as the one
+  specified for the inputs.
+
+* Main options are:
+
+-h                  show help
+-formats            show available formats, codecs and protocols
+-L                  print the LICENSE
+-i filename         input file name
+-y                  overwrite output files
+-t duration         set recording time in seconds
+-f format           set encoding format                  [guessed]
+-title string       set the title
+-author string      set the author
+-copyright string   set the copyright
+-comment string     set the comment
+
+* Video Options are:
+
+-s size      set frame size                       [160x128]
+-r fps       set frame rate                       [25]
+-b bitrate   set the video bitrate in kbit/s      [200]
+-vn          disable video recording              [no]
+
+* Audio Options are:
+
+-ar freq     set the audio sampling freq          [44100]
+-ab bitrate  set the audio bitrate in kbit/s      [64]
+-ac channels set the number of audio channels     [1]
+-an          disable audio recording              [no]
+
+Advanced options are:
+
+-map file:stream    set input stream mapping
+-g gop_size         set the group of picture size        [12]
+-intra              use only intra frames                [no]
+-qscale q           use fixed video quantiser scale (VBR)
+-c comment          set the comment string
+-vd device          set video4linux device name          [/dev/video]
+-vcodec codec       force audio codec
+-me method          set motion estimation method
+-ad device          set audio device name                [/dev/dsp]
+-acodec codec       force audio codec
 
 The output file can be "-" to output to a pipe. This is only possible
 with mpeg1 and h263 formats. 
 
-* Tips:
+3) Protocols
+
+ ffmpeg handles also many protocols specified with the URL syntax.
+
+ Use 'ffmpeg -formats' to have a list of the supported protocols.
+
+ The protocol 'http:' is currently used only to communicate with
+ ffserver (see the ffserver documentation). When ffmpeg will be a
+ video player it will also be used for streaming :-)
+
+4) File formats and codecs
+--------------------------
 
-- For low bit rate application, use a low frame rate and a small gop
-  size. This is especially true for real video where the Linux player
-  does not seem to be very fast, so it can miss frames. An example is:
+ Use 'ffmpeg -formats' to have a list of the supported output
+ formats. Only some formats are handled as input, but it will improve
+ in the next versions.
+
+5) Tips
+-------
+
+- 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
+  the Linux player does not seem to be very fast, so it can miss
+  frames. An example is:
 
   ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
 
@@ -60,3 +163,19 @@ with mpeg1 and h263 formats.
   your bit rate. You must either increase the bit rate, decrease the
   frame rate or decrease the frame size.
 
+- 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
+  completly motion estimation (you have only I frames, which means it
+  is about as good as JPEG compression).
+
+- To have very low bitrates in audio, reduce the sampling frequency
+  (down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
+
+- 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).
+
+- 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.