* Add the gop_size to the video parameters. Also the audio framesize.
[ffmpeg.git] / doc / ffmpeg.txt
1 *************** FFMPEG soft VCR documentation *****************
2
3 0) Introduction
4 ---------------
5
6   FFmpeg is a very fast video and audio encoder. It can grab from
7   files or from a live audio/video source. 
8   
9   The command line interface is designed to be intuitive, in the sense
10   that ffmpeg tries to figure out all the paramters, when
11   possible. You have usually to give only the target bitrate you want.
12
13   FFmpeg can also convert from any sample rate to any other, and
14   resize video on the fly with a high quality polyphase filter.
15
16 1) Video and Audio grabbing
17 ---------------------------
18
19 * ffmpeg can use a video4linux compatible video source and any Open
20   Sound System audio source:
21
22   ffmpeg /tmp/out.mpg 
23
24   Note that you must activate the right video source and channel
25   before launching ffmpeg. You can use any TV viewer such as xawtv by
26   Gerd Knorr which I find very good. You must also set correctly the
27   audio recording levels with a standard mixer.
28
29 2) Video and Audio file format convertion
30 -----------------------------------------
31
32 * ffmpeg can use any supported file format and protocol as input : 
33
34 examples:
35
36   ffmpeg -i /tmp/test%d.Y /tmp/out.mpg 
37
38 If will use the files: 
39 /tmp/test0.Y, /tmp/test0.U, /tmp/test0.V, 
40 /tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
41
42 The Y files use twice the resolution of the U and V files. They are
43 raw files, without header. They can be generated by all decent video
44 decoders. You must specify the size of the image with the '-s' option
45 if ffmpeg cannot guess it.
46
47 * You can set several input files and output files:
48
49   ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
50
51 Convert the audio file a.wav and the raw yuv video file a.yuv  to mpeg file a.mpg
52
53 * you can also do audio and video convertions at the same time:
54
55   ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
56
57 Convert the sample rate of a.wav to 22050 Hz and encode it to MPEG audio.
58
59 * you can encode to several formats at the same time and define a
60   mapping from input stream to output streams:
61
62   ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
63
64   convert a.wav to a.mp2 at 64 kbits and b.mp2 at 128 kbits. '-map
65   file:index' specify which input stream is used for each output
66   stream, in the order of the definition of output streams.
67
68 NOTE: to see the supported input formats, use 'ffmpeg -formats'.
69
70 2) Invocation
71 -------------
72
73 * The generic syntax is :
74
75   ffmpeg [[options][-i input_file]]... {[options] output_file}...
76
77   If no input file is given, audio/video grabbing is done.
78
79   As a general rule, options are applied to the next specified
80   file. For example, if you give the '-b 64' option, it sets the video
81   bitrate of the next file. Format option may be needed for raw input
82   files.
83
84   By default, ffmpeg tries to convert as losslessly as possible: it
85   uses the same audio and video parameter fors the outputs as the one
86   specified for the inputs.
87
88 * Main options are:
89
90 -h                  show help
91 -formats            show available formats, codecs and protocols
92 -L                  print the LICENSE
93 -i filename         input file name
94 -y                  overwrite output files
95 -t duration         set recording time in seconds
96 -f format           set encoding format                  [guessed]
97 -title string       set the title
98 -author string      set the author
99 -copyright string   set the copyright
100 -comment string     set the comment
101
102 * Video Options are:
103
104 -s size      set frame size                       [160x128]
105 -r fps       set frame rate                       [25]
106 -b bitrate   set the video bitrate in kbit/s      [200]
107 -vn          disable video recording              [no]
108
109 * Audio Options are:
110
111 -ar freq     set the audio sampling freq          [44100]
112 -ab bitrate  set the audio bitrate in kbit/s      [64]
113 -ac channels set the number of audio channels     [1]
114 -an          disable audio recording              [no]
115
116 Advanced options are:
117
118 -map file:stream    set input stream mapping
119 -g gop_size         set the group of picture size        [12]
120 -intra              use only intra frames                [no]
121 -qscale q           use fixed video quantiser scale (VBR)
122 -c comment          set the comment string
123 -vd device          set video4linux device name          [/dev/video]
124 -vcodec codec       force audio codec
125 -me method          set motion estimation method
126 -ad device          set audio device name                [/dev/dsp]
127 -acodec codec       force audio codec
128
129 The output file can be "-" to output to a pipe. This is only possible
130 with mpeg1 and h263 formats. 
131
132 3) Protocols
133
134  ffmpeg handles also many protocols specified with the URL syntax.
135
136  Use 'ffmpeg -formats' to have a list of the supported protocols.
137
138  The protocol 'http:' is currently used only to communicate with
139  ffserver (see the ffserver documentation). When ffmpeg will be a
140  video player it will also be used for streaming :-)
141
142 4) File formats and codecs
143 --------------------------
144
145  Use 'ffmpeg -formats' to have a list of the supported output
146  formats. Only some formats are handled as input, but it will improve
147  in the next versions.
148
149 5) Tips
150 -------
151
152 - For streaming at very low bit rate application, use a low frame rate
153   and a small gop size. This is especially true for real video where
154   the Linux player does not seem to be very fast, so it can miss
155   frames. An example is:
156
157   ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
158
159 - The parameter 'q' which is displayed while encoding is the current
160   quantizer. The value of 1 indicates that a very good quality could
161   be achieved. The value of 31 indicates the worst quality. If q=31
162   too often, it means that the encoder cannot compress enough to meet
163   your bit rate. You must either increase the bit rate, decrease the
164   frame rate or decrease the frame size.
165
166 - If your computer is not fast enough, you can speed up the
167   compression at the expense of the compression ratio. You can use
168   '-me zero' to speed up motion estimation, and '-intra' to disable
169   completly motion estimation (you have only I frames, which means it
170   is about as good as JPEG compression).
171
172 - To have very low bitrates in audio, reduce the sampling frequency
173   (down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
174
175 - To have a constant quality (but a variable bitrate), use the option
176   '-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
177   quality).
178
179 - When converting video files, you can use the '-sameq' option which
180   uses in the encoder the same quality factor than in the decoder. It
181   allows to be almost lossless in encoding.