Statistics
| Branch: | Revision:

ffmpeg / doc / ffmpeg-doc.texi @ 47d944d2

History | View | Annotate | Download (15.5 KB)

1
\input texinfo @c -*- texinfo -*-
2

    
3
@settitle FFmpeg Documentation
4
@titlepage
5
@sp 7
6
@center @titlefont{FFmpeg Documentation}
7
@sp 3
8
@end titlepage
9

    
10

    
11
@chapter Introduction
12

    
13
FFmpeg is a very fast video and audio converter. It can also grab from
14
a live audio/video source.
15
  
16
The command line interface is designed to be intuitive, in the sense
17
that ffmpeg tries to figure out all the parameters, when
18
possible. You have usually to give only the target bitrate you want.
19

    
20
FFmpeg can also convert from any sample rate to any other, and resize
21
video on the fly with a high quality polyphase filter.
22

    
23
@chapter Quick Start
24

    
25
@section Video and Audio grabbing
26

    
27
 FFmpeg can use a video4linux compatible video source and any Open Sound
28
  System audio source:
29
@example
30
  ffmpeg /tmp/out.mpg 
31
@end example
32

    
33
  Note that you must activate the right video source and channel
34
  before launching ffmpeg. You can use any TV viewer such as xawtv by
35
  Gerd Knorr which I find very good. You must also set correctly the
36
  audio recording levels with a standard mixer.
37

    
38
@section Video and Audio file format convertion
39

    
40
* ffmpeg can use any supported file format and protocol as input: 
41

    
42
Examples:
43

    
44
* You can input from YUV files:
45

    
46
@example
47
  ffmpeg -i /tmp/test%d.Y /tmp/out.mpg 
48
@end example
49

    
50
  It will use the files: 
51
@example
52
       /tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
53
       /tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
54
@end example
55

    
56
  The Y files use twice the resolution of the U and V files. They are
57
  raw files, without header. They can be generated by all decent video
58
  decoders. You must specify the size of the image with the '-s' option
59
  if ffmpeg cannot guess it.
60

    
61
* You can input from a RAW YUV420P file:
62

    
63
@example
64
  ffmpeg -i /tmp/test.yuv /tmp/out.avi
65
@end example
66

    
67
  The RAW YUV420P is a file containing RAW YUV planar, for each frame first
68
  come the Y plane followed by U and V planes, which are half vertical and
69
  horizontal resolution.
70

    
71
* You can output to a RAW YUV420P file:
72

    
73
@example
74
  ffmpeg -i mydivx.avi -o hugefile.yuv
75
@end example
76

    
77
* You can set several input files and output files:
78

    
79
@example
80
  ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
81
@end example
82

    
83
  Convert the audio file a.wav and the raw yuv video file a.yuv
84
  to mpeg file a.mpg
85

    
86
* You can also do audio and video convertions at the same time:
87

    
88
@example
89
  ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
90
@end example
91

    
92
  Convert the sample rate of a.wav to 22050 Hz and encode it to MPEG audio.
93

    
94
* You can encode to several formats at the same time and define a
95
  mapping from input stream to output streams:
96

    
97
@example
98
  ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
99
@end example
100

    
101
  Convert a.wav to a.mp2 at 64 kbits and b.mp2 at 128 kbits. '-map
102
  file:index' specify which input stream is used for each output
103
  stream, in the order of the definition of output streams.
104

    
105
* You can transcode decrypted VOBs
106

    
107
@example
108
  ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800 -g 300 -bf 2 -acodec mp3 -ab 128 snatch.avi
109
@end example
110

    
111
  This is a typicall DVD ripper example, input from a VOB file, output
112
  to an AVI file with MPEG-4 video and MP3 audio, note that in this
113
  command we use B frames so the MPEG-4 stream is DivX5 compatible, GOP
114
  size is 300 that means an INTRA frame every 10 seconds for 29.97 fps
115
  input video.  Also the audio stream is MP3 encoded so you need LAME
116
  support which is enabled using @code{--enable-mp3lame} when
117
  configuring.  The mapping is particullary usefull for DVD transcoding
118
  to get the desired audio language.
119

    
120
  NOTE: to see the supported input formats, use @code{ffmpeg -formats}.
121

    
122
@chapter Invocation
123

    
124
@section Syntax
125

    
126
 The generic syntax is:
127

    
128
@example 
129
  ffmpeg [[options][-i input_file]]... {[options] output_file}...
130
@end example
131
  If no input file is given, audio/video grabbing is done.
132

    
133
  As a general rule, options are applied to the next specified
134
  file. For example, if you give the '-b 64' option, it sets the video
135
  bitrate of the next file. Format option may be needed for raw input
136
  files.
137

    
138
  By default, ffmpeg tries to convert as losslessly as possible: it
139
  uses the same audio and video parameter fors the outputs as the one
140
  specified for the inputs.
141

    
142
@section Main options
143

    
144
@table @samp
145
@item -L
146
show license
147
@item -h
148
                  show help
149
@item -formats            
150
show available formats, codecs, protocols, ...
151
@item -f fmt              
152
force format
153
@item -i filename         
154
input file name
155

    
156
@item -y                  
157
overwrite output files
158

    
159
@item -t duration         
160
set the recording time in seconds. @code{hh:mm:ss[.xxx]} syntax is also
161
supported.
162

    
163
@item -title string       
164
set the title
165

    
166
@item -author string      
167
set the author
168

    
169
@item -copyright string   
170
set the copyright
171

    
172
@item -comment string     
173
set the comment
174

    
175
@item -b bitrate          
176
set video bitrate (in kbit/s)
177
@end table
178

    
179
@section Video Options
180

    
181
@table @samp
182
@item -s size             
183
set frame size                       [160x128]
184
@item -r fps           
185
set frame rate                       [25]
186
@item -b bitrate
187
set the video bitrate in kbit/s      [200]
188
@item -vn
189
disable video recording              [no]
190
@item -bt tolerance       
191
set video bitrate tolerance (in kbit/s)
192
@item -sameq              
193
use same video quality as source (implies VBR)
194

    
195
@item -pass n  
196
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.
197

    
198
@item -passlogfile file   
199
select two pass log file name
200

    
201
@end table
202

    
203
@section Audio Options
204

    
205
@table @samp
206
@item -ab bitrate         
207
set audio bitrate (in kbit/s)
208
@item -ar freq    
209
 set the audio sampling freq          [44100]
210
@item -ab bitrate 
211
 set the audio bitrate in kbit/s      [64]
212
@item -ac channels
213
 set the number of audio channels     [1]
214
@item -an     
215
 disable audio recording              [no]
216
@end table
217

    
218
@section Advanced options
219

    
220
@table @samp
221
@item -map file:stream    
222
set input stream mapping
223
@item -g gop_size         
224
set the group of picture size
225
@item -intra              
226
use only intra frames
227
@item -qscale q           
228
use fixed video quantiser scale (VBR)
229
@item -qmin q             
230
min video quantiser scale (VBR)
231
@item -qmax q             
232
max video quantiser scale (VBR)
233
@item -qdiff q            
234
max difference between the quantiser scale (VBR)
235
@item -qblur blur         
236
video quantiser scale blur (VBR)
237
@item -qcomp compression  
238
video quantiser scale compression (VBR)
239
@item -vd device          
240
set video device
241
@item -vcodec codec       
242
force video codec
243
@item -me method          
244
set motion estimation method
245
@item -bf frames          
246
use 'frames' B frames (only MPEG-4)
247
@item -hq                 
248
activate high quality settings
249
@item -4mv                
250
use four motion vector by macroblock (only MPEG-4)
251
@item -ad device          
252
set audio device
253
@item -acodec codec       
254
force audio codec
255
@item -deinterlace        
256
deinterlace pictures
257
@item -benchmark          
258
add timings for benchmarking
259
@item -hex                
260
dump each input packet
261
@item -psnr               
262
calculate PSNR of compressed frames
263
@item -vstats             
264
dump video coding statistics to file
265
@end table
266

    
267
@section Protocols
268

    
269
The filename can be @file{-} to read from the standard input or to write
270
to the standard output.
271

    
272
ffmpeg handles also many protocols specified with the URL syntax.
273

    
274
 Use 'ffmpeg -formats' to have a list of the supported protocols.
275

    
276
 The protocol @code{http:} is currently used only to communicate with
277
 ffserver (see the ffserver documentation). When ffmpeg will be a
278
 video player it will also be used for streaming :-)
279

    
280
@chapter Tips
281

    
282
@itemize
283
@item For streaming at very low bit rate application, use a low frame rate
284
  and a small gop size. This is especially true for real video where
285
  the Linux player does not seem to be very fast, so it can miss
286
  frames. An example is:
287

    
288
@example
289
  ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
290
@end example
291

    
292
@item  The parameter 'q' which is displayed while encoding is the current
293
  quantizer. The value of 1 indicates that a very good quality could
294
  be achieved. The value of 31 indicates the worst quality. If q=31
295
  too often, it means that the encoder cannot compress enough to meet
296
  your bit rate. You must either increase the bit rate, decrease the
297
  frame rate or decrease the frame size.
298

    
299
@item If your computer is not fast enough, you can speed up the
300
  compression at the expense of the compression ratio. You can use
301
  '-me zero' to speed up motion estimation, and '-intra' to disable
302
  completly motion estimation (you have only I frames, which means it
303
  is about as good as JPEG compression).
304

    
305
@item To have very low bitrates in audio, reduce the sampling frequency
306
  (down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
307

    
308
@item To have a constant quality (but a variable bitrate), use the option
309
  '-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
310
  quality).
311

    
312
@item When converting video files, you can use the '-sameq' option which
313
  uses in the encoder the same quality factor than in the decoder. It
314
  allows to be almost lossless in encoding.
315

    
316
@end itemize
317

    
318
@chapter Supported File Formats and Codecs
319

    
320
You can use the @code{-formats} option to have an exhaustive list.
321

    
322
@section File Formats
323

    
324
FFmpeg supports the following file formats thru the @code{libavformat}
325
library.
326

    
327
@multitable @columnfractions .4 .1 .1
328
@item Supported File Format @tab Encoding @tab Decoding @tab Comments
329
@item MPEG audio @tab X @tab X
330
@item MPEG1 systems @tab X  @tab  X 
331
@tab muxed audio and video
332
@item MPEG2 PS @tab X  @tab  X 
333
@tab also known as @code{VOB} file
334
@item MPEG2 TS @tab    @tab  X 
335
@tab also known as DVB Transport Stream
336
@item ASF@tab X @tab X 
337
@item AVI@tab X @tab X 
338
@item WAV@tab X @tab X 
339
@item Macromedia Flash@tab X @tab X
340
@tab Only embedded audio is decoded
341
@item Real Audio and Video @tab X @tab X 
342
@item PGM, YUV, PPM, JPEG images @tab X @tab X 
343
@item Animated GIF @tab X @tab
344
@tab Only uncompressed GIFs are generated
345
@item Raw AC3 @tab X  @tab  X 
346
@item Raw MJPEG @tab X  @tab  X 
347
@item Raw MPEG video @tab X  @tab  X 
348
@item Raw PCM8/16 bits, mulaw/Alaw@tab X  @tab  X 
349
@item SUN AU format @tab X  @tab  X 
350
@item Quicktime        @tab   @tab  X 
351
@item MPEG4            @tab  @tab  X 
352
@tab MPEG4 is a variant of Quicktime
353
@item Raw MPEG4 video  @tab  @tab  X 
354
@tab Only small files are supported.
355
@item DV               @tab  @tab X
356
@tab Only the video track is decoded.
357
@end multitable
358

    
359
@code{X} means that the encoding (resp. decoding) is supported.
360

    
361
@section Video Codecs
362

    
363
@multitable @columnfractions .4 .1 .1 .7
364
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
365
@item MPEG1 video            @tab  X  @tab  X 
366
@item MPEG2 video            @tab     @tab  X 
367
@item MPEG4                  @tab  X  @tab  X @tab Also known as DIVX4/5
368
@item MSMPEG4 V1             @tab  X  @tab  X
369
@item MSMPEG4 V2             @tab  X  @tab  X
370
@item MSMPEG4 V3             @tab  X  @tab  X @tab Also known as DIVX3
371
@item WMV7                   @tab  X  @tab  X
372
@item H263(+)                @tab  X  @tab  X @tab Also known as Real Video 1.0
373
@item MJPEG                  @tab  X  @tab  X 
374
@item DV                     @tab     @tab  X 
375
@end multitable
376

    
377
@code{X} means that the encoding (resp. decoding) is supported.
378

    
379
Check at @url{http://www.mplayerhq.hu/~michael/codec-features.html} to
380
get a precise comparison of FFmpeg MPEG4 codec compared to the other
381
solutions.
382

    
383
@section Audio Codecs
384

    
385
@multitable @columnfractions .4 .1 .1 .1 .7
386
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
387
@item MPEG audio layer 2     @tab  IX  @tab  IX 
388
@item MPEG audio layer 1/3   @tab IX   @tab  IX
389
@tab MP3 encoding is supported thru the external library LAME
390
@item AC3                    @tab  IX  @tab  X
391
@tab liba52 is used internally for decoding.
392
@item Vorbis                 @tab  X   @tab
393
@tab encoding is supported thru the external library libvorbis.
394
@end multitable
395

    
396
@code{X} means that the encoding (resp. decoding) is supported.
397

    
398
@code{I} means that an integer only version is available too (ensures highest
399
performances on systems without hardware floating point support).
400

    
401
@chapter Platform Specific information
402

    
403
@section Linux
404

    
405
ffmpeg should be compiled with at least GCC 2.95.3. GCC 3.2 is the
406
prefered compiler now for ffmpeg. All futur optimizations will depend on
407
features only found in GCC 3.2.
408

    
409
@section BSD
410

    
411
@section Windows
412

    
413
@section MacOS X
414

    
415
@section BeOS
416

    
417
The configure script should guess the configuration itself.
418
Networking support is currently not finished.
419
errno issues fixed by Andrew Bachmann.
420

    
421
Old stuff:
422

    
423
Fran?ois Revol - revol at free dot fr - April 2002
424

    
425
The configure script should guess the configuration itself, 
426
however I still didn't tested building on net_server version of BeOS.
427

    
428
ffserver is broken (needs poll() implementation).
429

    
430
There is still issues with errno codes, which are negative in BeOs, and
431
that ffmpeg negates when returning. This ends up turning errors into 
432
valid results, then crashes.
433
(To be fixed)
434

    
435
@chapter Developpers Guide
436

    
437
@section API
438
@itemize
439
@item libavcodec is the library containing the codecs (both encoding and
440
  decoding). See @file{libavcodec/apiexample.c} to see how to use it.
441

    
442
@item libavformat is the library containing the file formats handling (mux and
443
  demux code for several formats). (no example yet, the API is likely to
444
  evolve).
445
@end itemize
446

    
447
@section Integrating libavcodec or libavformat in your program
448

    
449
You can integrate all the source code of the libraries to link them
450
statically to avoid any version problem. All you need is to provide a
451
'config.mak' and a 'config.h' in the parent directory. See the defines
452
generated by ./configure to understand what is needed.
453

    
454
You can use libavcodec or libavformat in your commercial program, but
455
@emph{any patch you make must be published}. The best way to proceed is
456
to send your patches to the ffmpeg mailing list.
457

    
458
@section Coding Rules
459

    
460
ffmpeg is programmed in ANSI C language. GCC extensions are
461
tolerated. Indent size is 4. The TAB character should not be used.
462

    
463
The presentation is the one specified by 'indent -i4 -kr'.
464

    
465
Main priority in ffmpeg is simplicity and small code size (=less
466
bugs).
467

    
468
Comments: for functions visible from other modules, use the JavaDoc
469
format (see examples in @file{libav/utils.c}) so that a documentation
470
can be generated automatically.
471

    
472
@section Submitting patches
473

    
474
When you submit your patch, try to send a unified diff (diff '-u'
475
option). I cannot read other diffs :-)
476

    
477
Run the regression tests before submitting a patch so that you can
478
verify that there is no big problems.
479

    
480
Except if your patch is really big and adds an important feature, by
481
submitting it to me, you accept implicitely to put it under my
482
copyright. I prefer to do this to avoid potential problems if
483
licensing of ffmpeg changes.
484

    
485
Patches should be posted as base64 encoded attachments (or any other
486
encoding which ensures that the patch wont be trashed during 
487
transmission) to the ffmpeg-devel mailinglist, see 
488
@url{http://lists.sourceforge.net/lists/listinfo/ffmpeg-devel}
489

    
490
@section Regression tests
491

    
492
Before submitting a patch (or commiting with CVS), you should at least
493
test that you did not break anything.
494

    
495
The regression test build a synthetic video stream and a synthetic
496
audio stream. Then there are encoded then decoded with all codecs or
497
formats. The CRC (or MD5) of each generated file is recorded in a
498
result file. Then a 'diff' is launched with the reference results and
499
the result file.
500

    
501
Run 'make test' to test all the codecs.
502

    
503
Run 'make libavtest' to test all the codecs.
504

    
505
[Of course, some patches may change the regression tests results. In
506
this case, the regression tests reference results shall be modified
507
accordingly].
508

    
509
@bye