merge
[libav.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.