Statistics
| Branch: | Revision:

ffmpeg / doc / ffmpeg-doc.texi @ 34d7008d

History | View | Annotate | Download (16.1 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 Raw AC3 @tab X  @tab  X 
343
@item Raw MJPEG @tab X  @tab  X 
344
@item Raw MPEG video @tab X  @tab  X 
345
@item Raw PCM8/16 bits, mulaw/Alaw@tab X  @tab  X 
346
@item SUN AU format @tab X  @tab  X 
347
@item Quicktime        @tab   @tab  X 
348
@item MPEG4            @tab  @tab  X 
349
@tab MPEG4 is a variant of Quicktime
350
@item Raw MPEG4 video  @tab  X @tab  X 
351
@item DV               @tab  @tab X
352
@tab Only the video track is decoded.
353
@end multitable
354

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

    
357
@section Image Formats
358

    
359
FFmpeg can read and write images for each frame of a video sequence. The
360
following image formats are supported:
361

    
362
@multitable @columnfractions .4 .1 .1
363
@item Supported Image Format @tab Encoding @tab Decoding @tab Comments
364
@item PGM, PPM     @tab X @tab X 
365
@item PGMYUV       @tab X @tab X @tab PGM with U and V components in 420
366
@item JPEG         @tab X @tab X @tab Progressive JPEG is not supported
367
@item .Y.U.V       @tab X @tab X @tab One raw file per component
368
@item Animated GIF @tab X @tab   @tab Only uncompressed GIFs are generated
369
@end multitable
370

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

    
373
@section Video Codecs
374

    
375
@multitable @columnfractions .4 .1 .1 .7
376
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
377
@item MPEG1 video            @tab  X  @tab  X
378
@item MPEG2 video            @tab     @tab  X 
379
@item MPEG4                  @tab  X  @tab  X @tab Also known as DIVX4/5
380
@item MSMPEG4 V1             @tab  X  @tab  X
381
@item MSMPEG4 V2             @tab  X  @tab  X
382
@item MSMPEG4 V3             @tab  X  @tab  X @tab Also known as DIVX3
383
@item WMV7                   @tab  X  @tab  X
384
@item H263(+)                @tab  X  @tab  X @tab Also known as Real Video 1.0
385
@item MJPEG                  @tab  X  @tab  X 
386
@item DV                     @tab     @tab  X 
387
@item Huff YUV               @tab  X  @tab  X
388
@end multitable
389

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

    
392
Check at @url{http://www.mplayerhq.hu/~michael/codec-features.html} to
393
get a precise comparison of FFmpeg MPEG4 codec compared to the other
394
solutions.
395

    
396
@section Audio Codecs
397

    
398
@multitable @columnfractions .4 .1 .1 .1 .7
399
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
400
@item MPEG audio layer 2     @tab  IX  @tab  IX 
401
@item MPEG audio layer 1/3   @tab IX   @tab  IX
402
@tab MP3 encoding is supported thru the external library LAME
403
@item AC3                    @tab  IX  @tab  X
404
@tab liba52 is used internally for decoding.
405
@item Vorbis                 @tab  X   @tab  X
406
@tab supported thru the external library libvorbis.
407
@item WMA V1/V2              @tab      @tab X
408

    
409
@end multitable
410

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

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

    
416
@chapter Platform Specific information
417

    
418
@section Linux
419

    
420
ffmpeg should be compiled with at least GCC 2.95.3. GCC 3.2 is the
421
prefered compiler now for ffmpeg. All futur optimizations will depend on
422
features only found in GCC 3.2.
423

    
424
@section BSD
425

    
426
@section Windows
427

    
428
@section MacOS X
429

    
430
@section BeOS
431

    
432
The configure script should guess the configuration itself.
433
Networking support is currently not finished.
434
errno issues fixed by Andrew Bachmann.
435

    
436
Old stuff:
437

    
438
Fran?ois Revol - revol at free dot fr - April 2002
439

    
440
The configure script should guess the configuration itself, 
441
however I still didn't tested building on net_server version of BeOS.
442

    
443
ffserver is broken (needs poll() implementation).
444

    
445
There is still issues with errno codes, which are negative in BeOs, and
446
that ffmpeg negates when returning. This ends up turning errors into 
447
valid results, then crashes.
448
(To be fixed)
449

    
450
@chapter Developers Guide
451

    
452
@section API
453
@itemize
454
@item libavcodec is the library containing the codecs (both encoding and
455
  decoding). See @file{libavcodec/apiexample.c} to see how to use it.
456

    
457
@item libavformat is the library containing the file formats handling (mux and
458
  demux code for several formats). (no example yet, the API is likely to
459
  evolve).
460
@end itemize
461

    
462
@section Integrating libavcodec or libavformat in your program
463

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

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

    
473
@section Coding Rules
474

    
475
ffmpeg is programmed in ANSI C language. GCC extensions are
476
tolerated. Indent size is 4. The TAB character should not be used.
477

    
478
The presentation is the one specified by 'indent -i4 -kr'.
479

    
480
Main priority in ffmpeg is simplicity and small code size (=less
481
bugs).
482

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

    
487
@section Submitting patches
488

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

    
492
Run the regression tests before submitting a patch so that you can
493
verify that there is no big problems.
494

    
495
Except if your patch is really big and adds an important feature, by
496
submitting it to me, you accept implicitely to put it under my
497
copyright. I prefer to do this to avoid potential problems if
498
licensing of ffmpeg changes.
499

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

    
505
@section Regression tests
506

    
507
Before submitting a patch (or commiting with CVS), you should at least
508
test that you did not break anything.
509

    
510
The regression test build a synthetic video stream and a synthetic
511
audio stream. Then there are encoded then decoded with all codecs or
512
formats. The CRC (or MD5) of each generated file is recorded in a
513
result file. Then a 'diff' is launched with the reference results and
514
the result file.
515

    
516
Run 'make test' to test all the codecs.
517

    
518
Run 'make libavtest' to test all the codecs.
519

    
520
[Of course, some patches may change the regression tests results. In
521
this case, the regression tests reference results shall be modified
522
accordingly].
523

    
524
@bye