Statistics
| Branch: | Revision:

ffmpeg / doc / ffmpeg-doc.texi @ ca1c3f52

History | View | Annotate | Download (28.6 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
@c man begin EXAMPLES
26
@section Video and Audio grabbing
27

    
28
FFmpeg can use a video4linux compatible video source and any Open Sound
29
System audio source:
30

    
31
@example
32
ffmpeg /tmp/out.mpg 
33
@end example
34

    
35
Note that you must activate the right video source and channel before
36
launching ffmpeg. You can use any TV viewer such as xawtv
37
(@url{http://bytesex.org/xawtv/}) by Gerd Knorr which I find very
38
good. You must also set correctly the audio recording levels with a
39
standard mixer.
40

    
41
@section Video and Audio file format conversion
42

    
43
* ffmpeg can use any supported file format and protocol as input: 
44

    
45
Examples:
46

    
47
* You can input from YUV files:
48

    
49
@example
50
ffmpeg -i /tmp/test%d.Y /tmp/out.mpg 
51
@end example
52

    
53
It will use the files: 
54
@example
55
/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
56
/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
57
@end example
58

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

    
64
* You can input from a RAW YUV420P file:
65

    
66
@example
67
ffmpeg -i /tmp/test.yuv /tmp/out.avi
68
@end example
69

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

    
74
* You can output to a RAW YUV420P file:
75

    
76
@example
77
ffmpeg -i mydivx.avi -o hugefile.yuv
78
@end example
79

    
80
* You can set several input files and output files:
81

    
82
@example
83
ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
84
@end example
85

    
86
Convert the audio file a.wav and the raw yuv video file a.yuv
87
to mpeg file a.mpg
88

    
89
* You can also do audio and video conversions at the same time:
90

    
91
@example
92
ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
93
@end example
94

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

    
97
* You can encode to several formats at the same time and define a
98
mapping from input stream to output streams:
99

    
100
@example
101
ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
102
@end example
103

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

    
108
* You can transcode decrypted VOBs
109

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

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

    
123
NOTE: to see the supported input formats, use @code{ffmpeg -formats}.
124
@c man end
125

    
126
@chapter Invocation
127

    
128
@section Syntax
129

    
130
The generic syntax is:
131

    
132
@example 
133
@c man begin SYNOPSIS
134
ffmpeg [[options][@option{-i} @var{input_file}]]... @{[options] @var{output_file}@}...
135
@c man end
136
@end example
137
@c man begin DESCRIPTION
138
If no input file is given, audio/video grabbing is done.
139

    
140
As a general rule, options are applied to the next specified
141
file. For example, if you give the @option{-b 64} option, it sets the video
142
bitrate of the next file. Format option may be needed for raw input
143
files.
144

    
145
By default, ffmpeg tries to convert as losslessly as possible: it
146
uses the same audio and video parameter for the outputs as the one
147
specified for the inputs.
148
@c man end
149

    
150
@c man begin OPTIONS
151
@section Main options
152

    
153
@table @option
154
@item -L
155
show license
156

    
157
@item -h
158
show help
159

    
160
@item -formats
161
show available formats, codecs, protocols, ...
162

    
163
@item -f fmt              
164
force format
165

    
166
@item -i filename         
167
input file name
168

    
169
@item -y                  
170
overwrite output files
171

    
172
@item -t duration         
173
set the recording time in seconds. @code{hh:mm:ss[.xxx]} syntax is also
174
supported.
175

    
176
@item -title string       
177
set the title
178

    
179
@item -author string      
180
set the author
181

    
182
@item -copyright string   
183
set the copyright
184

    
185
@item -comment string     
186
set the comment
187

    
188
@item -target type
189
specify target file type ("vcd", "svcd" or "dvd"). All the format
190
options (bitrate, codecs, buffer sizes) are automatically set by this
191
option. You can just type:
192

    
193
@example
194
ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
195
@end example
196

    
197
@item -hq
198
activate high quality settings
199

    
200
@end table
201

    
202
@section Video Options
203

    
204
@table @option
205
@item -b bitrate
206
set the video bitrate in kbit/s (default = 200 kb/s)
207
@item -r fps           
208
set frame rate (default = 25)
209
@item -s size             
210
set frame size. The format is @samp{WxH} (default 160x128).  The
211
following abbreviations are recognized:
212
@table @samp
213
@item sqcif
214
128x96
215
@item qcif
216
176x144
217
@item cif
218
352x288
219
@item 4cif
220
704x576
221
@end table
222

    
223
@item -aspect aspect
224
set aspect ratio (4:3, 16:9 or 1.3333, 1.7777)
225
@item -croptop size
226
set top crop band size (in pixels)
227
@item -cropbottom size
228
set bottom crop band size (in pixels)
229
@item -cropleft size
230
set left crop band size (in pixels)
231
@item -cropright size
232
set right crop band size (in pixels)
233
@item -vn
234
disable video recording
235
@item -bt tolerance       
236
set video bitrate tolerance (in kbit/s)
237
@item -maxrate bitrate
238
set max video bitrate tolerance (in kbit/s)
239
@item -minrate bitrate
240
set min video bitrate tolerance (in kbit/s)
241
@item -bufsize size
242
set ratecontrol buffere size (in kbit)
243
@item -vcodec codec       
244
force video codec to @var{codec}. Use the @code{copy} special value to
245
tell that the raw codec data must be copied as is.
246
@item -sameq
247
use same video quality as source (implies VBR)
248

    
249
@item -pass n  
250
select the pass number (1 or 2). It is useful to do two pass
251
encoding. The statistics of the video are recorded in the first pass and
252
the video at the exact requested bit rate is generated in the second
253
pass.
254

    
255
@item -passlogfile file   
256
select two pass log file name to @var{file}.
257

    
258
@end table
259

    
260
@section Advanced Video Options
261

    
262
@table @option
263
@item -g gop_size         
264
set the group of picture size
265
@item -intra              
266
use only intra frames
267
@item -qscale q           
268
use fixed video quantiser scale (VBR)
269
@item -qmin q             
270
min video quantiser scale (VBR)
271
@item -qmax q             
272
max video quantiser scale (VBR)
273
@item -qdiff q            
274
max difference between the quantiser scale (VBR)
275
@item -qblur blur         
276
video quantiser scale blur (VBR)
277
@item -qcomp compression  
278
video quantiser scale compression (VBR)
279

    
280
@item -rc_init_cplx complexity
281
initial complexity for 1-pass encoding
282
@item -b_qfactor factor
283
qp factor between p and b frames
284
@item -i_qfactor factor
285
qp factor between p and i frames
286
@item -b_qoffset offset
287
qp offset between p and b frames
288
@item -i_qoffset offset
289
qp offset between p and i frames
290
@item -rc_eq equation
291
set rate control equation (@pxref{FFmpeg formula
292
evaluator}). Default is @code{tex^qComp}.
293
@item -rc_override override
294
rate control override for specific intervals
295
@item -me method
296
set motion estimation method to @var{method}. Available methods are
297
(from lower to best quality):
298
@table @samp
299
@item zero
300
Try just the (0, 0) vector.
301
@item phods
302
@item log
303
@item x1
304
@item epzs
305
(default method)
306
@item full
307
exhaustive search (slow and marginally better than epzs)
308
@end table
309

    
310
@item -dct_algo algo
311
set dct algorithm to @var{algo}. Available values are:
312
@table @samp
313
@item 0
314
FF_DCT_AUTO (default)
315
@item 1
316
FF_DCT_FASTINT
317
@item 2
318
FF_DCT_INT
319
@item 3
320
FF_DCT_MMX
321
@item 4
322
FF_DCT_MLIB
323
@item 5
324
FF_DCT_ALTIVEC
325
@end table
326

    
327
@item -idct_algo algo
328
set idct algorithm to @var{algo}. Available values are:
329
@table @samp
330
@item 0
331
FF_IDCT_AUTO (default)
332
@item 1
333
FF_IDCT_INT          
334
@item 2
335
FF_IDCT_SIMPLE       
336
@item 3
337
FF_IDCT_SIMPLEMMX    
338
@item 4
339
FF_IDCT_LIBMPEG2MMX  
340
@item 5
341
FF_IDCT_PS2          
342
@item 6
343
FF_IDCT_MLIB         
344
@item 7
345
FF_IDCT_ARM          
346
@item 8
347
FF_IDCT_ALTIVEC      
348
@item 9
349
FF_IDCT_SH4          
350
@item 10
351
FF_IDCT_SIMPLEARM    
352
@end table
353

    
354
@item -er n
355
set error resilience to @var{n}.
356
@table @samp
357
@item 1 
358
FF_ER_CAREFULL (default)
359
@item 2
360
FF_ER_COMPLIANT
361
@item 3
362
FF_ER_AGGRESSIVE
363
@item 4
364
FF_ER_VERY_AGGRESSIVE
365
@end table
366

    
367
@item -ec bit_mask
368
set error concealment to @var{bit_mask}. @var{bit_mask} is a bit mask of
369
the following values:
370
@table @samp
371
@item 1
372
FF_EC_GUESS_MVS (default=enabled)
373
@item 2
374
FF_EC_DEBLOCK (default=enabled)
375
@end table
376

    
377
@item -bf frames
378
use 'frames' B frames (supported for MPEG-1, MPEG-2 and MPEG-4)
379
@item -mbd mode
380
macroblock decision
381
@table @samp
382
@item 0
383
FF_MB_DECISION_SIMPLE: use mb_cmp (cannot change it yet in ffmpeg)
384
@item 1
385
FF_MB_DECISION_BITS: chooses the one which needs the fewest bits
386
@item 2
387
FF_MB_DECISION_RD: rate distoration
388
@end table
389

    
390
@item -4mv
391
use four motion vector by macroblock (only MPEG-4)
392
@item -part
393
use data partitioning (only MPEG-4)
394
@item -bug param
395
workaround not auto detected encoder bugs
396
@item -strict strictness
397
how strictly to follow the standarts
398
@item -aic
399
enable Advanced intra coding (h263+)
400
@item -umv
401
enable Unlimited Motion Vector (h263+)
402

    
403
@item -deinterlace
404
deinterlace pictures
405
@item -interlace
406
force interlacing support in encoder (only MPEG-2 and MPEG-4). Use this option
407
if your input file is interlaced and if you want to keep the interlaced
408
format for minimum losses. The alternative is to deinterlace the input
409
stream with @option{-deinterlace}, but deinterlacing introduces more
410
losses.
411
@item -psnr
412
calculate PSNR of compressed frames
413
@item -vstats
414
dump video coding statistics to @file{vstats_HHMMSS.log}.
415
@item -vhook module
416
insert video processing @var{module}. @var{module} contains the module
417
name and its parameters separated by spaces.
418
@end table
419

    
420
@section Audio Options
421

    
422
@table @option
423
@item -ab bitrate         
424
set audio bitrate (in kbit/s)
425
@item -ar freq    
426
set the audio sampling freq (default = 44100 Hz)
427
@item -ab bitrate 
428
set the audio bitrate in kbit/s (default = 64)
429
@item -ac channels
430
set the number of audio channels (default = 1)
431
@item -an
432
disable audio recording
433
@item -acodec codec
434
force audio codec to @var{codec}. Use the @code{copy} special value to
435
tell that the raw codec data must be copied as is.
436
@end table
437

    
438
@section Audio/Video grab options
439

    
440
@table @option
441
@item -vd device
442
set video grab device (e.g. @file{/dev/video0})
443
@item -vc channel
444
set video grab channel (DV1394 only)
445
@item -tvstd standard
446
set television standard (NTSC, PAL (SECAM))
447
@item -dv1394
448
set DV1394 grab
449
@item -ad device
450
set audio device (e.g. @file{/dev/dsp})
451
@end table
452

    
453
@section Advanced options
454

    
455
@table @option
456
@item -map file:stream    
457
set input stream mapping
458
@item -debug
459
print specific debug info
460
@item -benchmark          
461
add timings for benchmarking
462
@item -hex                
463
dump each input packet
464
@item -bitexact
465
only use bit exact algorithms (for codec testing)
466
@item -ps size
467
set packet size in bits
468
@item -re
469
read input at native frame rate. Mainly used to simulate a grab device.
470
@item -loop
471
loop over the input stream. Currently it works only for image
472
streams. This option is used for ffserver automatic testing.
473
@end table
474

    
475
@node FFmpeg formula evaluator
476
@section FFmpeg formula evaluator
477

    
478
When evaluating a rate control string, FFmpeg uses an internal formula
479
evaluator. 
480

    
481
The following binary operators are available: @code{+}, @code{-},
482
@code{*}, @code{/}, @code{^}.
483

    
484
The following unary operators are available: @code{+}, @code{-},
485
@code{(...)}.
486

    
487
The following functions are available:
488
@table @var
489
@item sinh(x)
490
@item cosh(x)
491
@item tanh(x)
492
@item sin(x)
493
@item cos(x)
494
@item tan(x)
495
@item exp(x)
496
@item log(x)
497
@item squish(x)
498
@item gauss(x)
499
@item abs(x)
500
@item max(x, y)
501
@item min(x, y)
502
@item gt(x, y)
503
@item lt(x, y)
504
@item eq(x, y)
505
@item bits2qp(bits)
506
@item qp2bits(qp)
507
@end table
508

    
509
The following constants are available:
510
@table @var
511
@item PI
512
@item E
513
@item iTex
514
@item pTex
515
@item tex
516
@item mv
517
@item fCode
518
@item iCount
519
@item mcVar
520
@item var
521
@item isI
522
@item isP
523
@item isB
524
@item avgQP
525
@item qComp
526
@item avgIITex
527
@item avgPITex
528
@item avgPPTex
529
@item avgBPTex
530
@item avgTex
531
@end table
532

    
533
@c man end
534

    
535
@ignore
536

    
537
@setfilename ffmpeg
538
@settitle FFmpeg video converter
539

    
540
@c man begin SEEALSO
541
ffserver(1), ffplay(1) and the html documentation of @file{ffmpeg}.
542
@c man end
543

    
544
@c man begin AUTHOR
545
Fabrice Bellard
546
@c man end
547

    
548
@end ignore
549

    
550
@section Protocols
551

    
552
The filename can be @file{-} to read from the standard input or to write
553
to the standard output.
554

    
555
ffmpeg handles also many protocols specified with the URL syntax.
556

    
557
Use 'ffmpeg -formats' to have a list of the supported protocols.
558

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

    
563
@chapter Tips
564

    
565
@itemize
566
@item For streaming at very low bit rate application, use a low frame rate
567
and a small gop size. This is especially true for real video where
568
the Linux player does not seem to be very fast, so it can miss
569
frames. An example is:
570

    
571
@example
572
ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
573
@end example
574

    
575
@item  The parameter 'q' which is displayed while encoding is the current
576
quantizer. The value of 1 indicates that a very good quality could
577
be achieved. The value of 31 indicates the worst quality. If q=31
578
too often, it means that the encoder cannot compress enough to meet
579
your bit rate. You must either increase the bit rate, decrease the
580
frame rate or decrease the frame size.
581

    
582
@item If your computer is not fast enough, you can speed up the
583
compression at the expense of the compression ratio. You can use
584
'-me zero' to speed up motion estimation, and '-intra' to disable
585
completely motion estimation (you have only I frames, which means it
586
is about as good as JPEG compression).
587

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

    
591
@item To have a constant quality (but a variable bitrate), use the option
592
'-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
593
quality).
594

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

    
599
@end itemize
600

    
601
@chapter Supported File Formats and Codecs
602

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

    
605
@section File Formats
606

    
607
FFmpeg supports the following file formats through the @code{libavformat}
608
library:
609

    
610
@multitable @columnfractions .4 .1 .1
611
@item Supported File Format @tab Encoding @tab Decoding @tab Comments
612
@item MPEG audio @tab X @tab X
613
@item MPEG1 systems @tab X  @tab  X 
614
@tab muxed audio and video
615
@item MPEG2 PS @tab X  @tab  X 
616
@tab also known as @code{VOB} file
617
@item MPEG2 TS @tab    @tab  X 
618
@tab also known as DVB Transport Stream
619
@item ASF@tab X @tab X 
620
@item AVI@tab X @tab X 
621
@item WAV@tab X @tab X 
622
@item Macromedia Flash@tab X @tab X
623
@tab Only embedded audio is decoded
624
@item FLV              @tab  X @tab X
625
@tab Macromedia Flash video files
626
@item Real Audio and Video @tab X @tab X 
627
@item Raw AC3 @tab X  @tab  X 
628
@item Raw MJPEG @tab X  @tab  X 
629
@item Raw MPEG video @tab X  @tab  X 
630
@item Raw PCM8/16 bits, mulaw/Alaw@tab X  @tab  X 
631
@item Raw CRI ADX audio @tab X  @tab  X 
632
@item SUN AU format @tab X  @tab  X 
633
@item NUT @tab X @tab X @tab NUT Open Container Format
634
@item Quicktime        @tab X @tab  X 
635
@item MPEG4            @tab X @tab  X 
636
@tab MPEG4 is a variant of Quicktime
637
@item Raw MPEG4 video  @tab  X @tab  X 
638
@item DV               @tab  X @tab  X
639
@item 4xm              @tab    @tab X
640
@tab 4X Technologies format, used in some games
641
@item Playstation STR  @tab    @tab X
642
@item Id RoQ           @tab    @tab X
643
@tab used in Quake III, Jedi Knight 2, other computer games
644
@item Interplay MVE    @tab    @tab X
645
@tab format used in various Interplay computer games
646
@item WC3 Movie        @tab    @tab X
647
@tab multimedia format used in Origin's Wing Commander III computer game
648
@item Sega FILM/CPK    @tab    @tab X
649
@tab used in many Sega Saturn console games
650
@item Westwood Studios VQA/AUD  @tab    @tab X
651
@tab Multimedia formats used in Westwood Studios games
652
@item Id Cinematic (.cin) @tab    @tab X
653
@tab Used in Quake II
654
@item FLIC format      @tab    @tab X
655
@tab .fli/.flc files
656
@end multitable
657

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

    
660
@section Image Formats
661

    
662
FFmpeg can read and write images for each frame of a video sequence. The
663
following image formats are supported:
664

    
665
@multitable @columnfractions .4 .1 .1
666
@item Supported Image Format @tab Encoding @tab Decoding @tab Comments
667
@item PGM, PPM     @tab X @tab X 
668
@item PAM          @tab X @tab X @tab PAM is a PNM extension with alpha support
669
@item PGMYUV       @tab X @tab X @tab PGM with U and V components in YUV 4:2:0
670
@item JPEG         @tab X @tab X @tab Progressive JPEG is not supported
671
@item .Y.U.V       @tab X @tab X @tab One raw file per component
672
@item Animated GIF @tab X @tab X @tab Only uncompressed GIFs are generated
673
@item PNG          @tab X @tab X @tab 2 bit and 4 bit/pixel not supported yet
674
@end multitable
675

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

    
678
@section Video Codecs
679

    
680
@multitable @columnfractions .4 .1 .1 .7
681
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
682
@item MPEG1 video            @tab  X  @tab  X
683
@item MPEG2 video            @tab  X  @tab  X 
684
@item MPEG4                  @tab  X  @tab  X @tab Also known as DIVX4/5
685
@item MSMPEG4 V1             @tab  X  @tab  X
686
@item MSMPEG4 V2             @tab  X  @tab  X
687
@item MSMPEG4 V3             @tab  X  @tab  X @tab Also known as DIVX3
688
@item WMV7                   @tab  X  @tab  X
689
@item WMV8                   @tab  X  @tab  X @tab Not completely working
690
@item H263(+)                @tab  X  @tab  X @tab Also known as Real Video 1.0
691
@item MJPEG                  @tab  X  @tab  X 
692
@item Lossless MJPEG         @tab  X  @tab  X
693
@item Apple MJPEG-B          @tab     @tab  X
694
@item Sunplus MJPEG          @tab     @tab  X @tab fourcc: SP5X
695
@item DV                     @tab  X  @tab  X 
696
@item Huff YUV               @tab  X  @tab  X
697
@item FFmpeg Video 1         @tab  X  @tab  X @tab Lossless codec (fourcc: FFV1)
698
@item Asus v1                @tab  X  @tab  X @tab fourcc: ASV1
699
@item Asus v2                @tab  X  @tab  X @tab fourcc: ASV2
700
@item Creative YUV           @tab     @tab  X @tab fourcc: CYUV
701
@item H.264                  @tab     @tab  X
702
@item Sorenson Video 1       @tab     @tab  X @tab fourcc: SVQ1
703
@item Sorenson Video 3       @tab     @tab  X @tab fourcc: SVQ3
704
@item On2 VP3                @tab     @tab  X @tab still experimental
705
@item Theora                 @tab     @tab  X @tab still experimental
706
@item Intel Indeo 3          @tab     @tab  X @tab only works on i386 right now
707
@item FLV                    @tab  X  @tab  X @tab Flash H263 variant
708
@item ATI VCR1               @tab     @tab  X @tab fourcc: VCR1
709
@item ATI VCR2               @tab     @tab  X @tab fourcc: VCR2
710
@item Cirrus Logic AccuPak   @tab     @tab  X @tab fourcc: CLJR
711
@item 4X Video               @tab     @tab  X @tab used in certain computer games
712
@item Sony Playstation MDEC  @tab     @tab  X 
713
@item Id RoQ                 @tab     @tab  X @tab used in Quake III, Jedi Knight 2, other computer games
714
@item Xan/WC3                @tab     @tab  X @tab used in Wing Commander III .MVE files
715
@item Interplay Video        @tab     @tab  X @tab used in Interplay .MVE files
716
@item Apple Graphics         @tab     @tab  X @tab fourcc: 'smc '
717
@item Apple Video            @tab     @tab  X @tab fourcc: rpza
718
@item Cinepak                @tab     @tab  X
719
@item Microsoft RLE          @tab     @tab  X
720
@item Microsoft Video-1      @tab     @tab  X
721
@item Westwood VQA           @tab     @tab  X
722
@item Id Cinematic Video     @tab     @tab  X @tab used in Quake II
723
@item Planar RGB             @tab     @tab  X @tab fourcc: 8BPS
724
@item FLIC video             @tab     @tab  X
725
@item Duck TrueMotion v1     @tab     @tab  X @tab fourcc: DUCK
726
@end multitable
727

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

    
730
Check at @url{http://www.mplayerhq.hu/~michael/codec-features.html} to
731
get a precise comparison of FFmpeg MPEG4 codec compared to the other
732
solutions.
733

    
734
@section Audio Codecs
735

    
736
@multitable @columnfractions .4 .1 .1 .1 .7
737
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
738
@item MPEG audio layer 2     @tab  IX  @tab  IX 
739
@item MPEG audio layer 1/3   @tab IX   @tab  IX
740
@tab MP3 encoding is supported through the external library LAME
741
@item AC3                    @tab  IX  @tab  X
742
@tab liba52 is used internally for decoding
743
@item Vorbis                 @tab  X   @tab  X
744
@tab supported through the external library libvorbis
745
@item WMA V1/V2              @tab      @tab X
746
@item Microsoft ADPCM        @tab      @tab X
747
@item MS IMA ADPCM           @tab X    @tab X
748
@item QT IMA ADPCM           @tab      @tab X
749
@item 4X IMA ADPCM           @tab      @tab X
750
@item Duck DK3 IMA ADPCM     @tab      @tab X
751
@tab used in some Sega Saturn console games
752
@item Duck DK4 IMA ADPCM     @tab      @tab X
753
@tab used in some Sega Saturn console games
754
@item Westwood Studios IMA ADPCM @tab      @tab X
755
@tab used in Westwood Studios games like Command and Conquer
756
@item CD-ROM XA ADPCM        @tab      @tab X
757
@item CRI ADX ADPCM          @tab X    @tab X
758
@tab used in Sega Dreamcast games
759
@item RA144                  @tab      @tab X
760
@tab Real 14400 bit/s codec
761
@item RA288                  @tab      @tab X
762
@tab Real 28800 bit/s codec
763
@item AMR-NB                 @tab X    @tab X
764
@tab supported through an external library
765
@item AMR-WB                 @tab X    @tab X
766
@tab supported through an external library
767
@item DV audio               @tab      @tab X
768
@item Id RoQ DPCM            @tab      @tab X
769
@tab used in Quake III, Jedi Knight 2, other computer games
770
@item Interplay MVE DPCM     @tab      @tab X
771
@tab used in various Interplay computer games
772
@item Xan DPCM               @tab      @tab X
773
@tab used in Origin's Wing Commander IV AVI files
774
@item Apple MACE 3           @tab      @tab X
775
@item Apple MACE 6           @tab      @tab X
776
@end multitable
777

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

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

    
783
@chapter Platform Specific information
784

    
785
@section Linux
786

    
787
ffmpeg should be compiled with at least GCC 2.95.3. GCC 3.2 is the
788
preferred compiler now for ffmpeg. All future optimizations will depend on
789
features only found in GCC 3.2.
790

    
791
@section BSD
792

    
793
@section Windows
794

    
795
@subsection Native Windows compilation
796

    
797
@itemize
798
@item Install the current versions of MSYS and MinGW from
799
@url{http://www.mingw.org/}. You can find detailed installation
800
instructions in the download section and the FAQ.
801

    
802
@item If you want to test the FFmpeg Simple Media Player, also download 
803
the MinGW development library of SDL 1.2.x
804
(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
805
@url{http://www.libsdl.org}. Unpack it in a temporary place, and
806
unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
807
directory. Edit the @file{sdl-config} script so that it gives the
808
correct SDL directory when invoked.
809

    
810
@item Extract the current version of FFmpeg (the latest release version or the current CVS snapshot whichever is recommended).
811
 
812
@item Start the MSYS shell (file @file{msys.bat}).
813

    
814
@item Change to the FFMPEG directory and follow
815
 the instructions of how to compile ffmpeg (file
816
@file{INSTALL}). Usually, launching @file{./configure} and @file{make}
817
suffices. If you have problems using SDL, verify that
818
@file{sdl-config} can be launched from the MSYS command line.
819

    
820
@item You can install FFmpeg in @file{Program Files/FFmpeg} by typing @file{make install}. Don't forget to copy @file{SDL.dll} at the place you launch 
821
@file{ffplay}.
822

    
823
@end itemize
824

    
825
Notes: 
826
@itemize
827

    
828
@item The target @file{make wininstaller} can be used to create a
829
Nullsoft based Windows installer for FFmpeg and FFplay. @file{SDL.dll}
830
must be copied in the ffmpeg directory in order to build the
831
installer.
832

    
833
@item By using @code{./configure --enable-shared} when configuring ffmpeg, 
834
you can build @file{avcodec.dll} and @file{avformat.dll}. With
835
@code{make install} you install the FFmpeg DLLs and the associated
836
headers in @file{Program Files/FFmpeg}. 
837

    
838
@item Visual C++ compatibility: if you used @code{./configure --enable-shared} 
839
when configuring FFmpeg, then FFmpeg tries to use the Microsoft Visual
840
C++ @code{lib} tool to build @code{avcodec.lib} and
841
@code{avformat.lib}. With these libraries, you can link your Visual C++
842
code directly with the FFmpeg DLLs.
843

    
844
@end itemize
845

    
846
@subsection Cross compilation for Windows with Linux
847

    
848
You must use the MinGW cross compilation tools available at
849
@url{http://www.mingw.org/}.
850

    
851
Then configure ffmpeg with the following options:
852
@example
853
./configure --enable-mingw32 --cross-prefix=i386-mingw32msvc-
854
@end example
855
(you can change the cross-prefix according to the prefix choosen for the
856
MinGW tools).
857

    
858
Then you can easily test ffmpeg with wine
859
(@url{http://www.winehq.com/}).
860

    
861
@section MacOS X
862

    
863
@section BeOS
864

    
865
The configure script should guess the configuration itself.
866
Networking support is currently not finished.
867
errno issues fixed by Andrew Bachmann.
868

    
869
Old stuff:
870

    
871
Fran?ois Revol - revol at free dot fr - April 2002
872

    
873
The configure script should guess the configuration itself, 
874
however I still didn't tested building on net_server version of BeOS.
875

    
876
ffserver is broken (needs poll() implementation).
877

    
878
There is still issues with errno codes, which are negative in BeOs, and
879
that ffmpeg negates when returning. This ends up turning errors into 
880
valid results, then crashes.
881
(To be fixed)
882

    
883
@chapter Developers Guide
884

    
885
@section API
886
@itemize
887
@item libavcodec is the library containing the codecs (both encoding and
888
  decoding). See @file{libavcodec/apiexample.c} to see how to use it.
889

    
890
@item libavformat is the library containing the file formats handling (mux and
891
  demux code for several formats). See @file{ffplay.c} to use it in a
892
player. See @file{output_example.c} to use it to generate audio or video
893
streams.
894

    
895
@end itemize
896

    
897
@section Integrating libavcodec or libavformat in your program
898

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

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

    
908
@section Coding Rules
909

    
910
ffmpeg is programmed in ANSI C language. GCC extensions are
911
tolerated. Indent size is 4. The TAB character should not be used.
912

    
913
The presentation is the one specified by 'indent -i4 -kr'.
914

    
915
Main priority in ffmpeg is simplicity and small code size (=less
916
bugs).
917

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

    
922
@section Submitting patches
923

    
924
When you submit your patch, try to send a unified diff (diff '-up'
925
option). I cannot read other diffs :-)
926

    
927
Run the regression tests before submitting a patch so that you can
928
verify that there are no big problems.
929

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

    
935
It also helps quite a bit if you tell us what the patch does (for example
936
'replaces lrint by lrintf') , and why (for example '*bsd isnt c99 compliant
937
and has no lrint()')
938

    
939
@section Regression tests
940

    
941
Before submitting a patch (or committing with CVS), you should at least
942
test that you did not break anything.
943

    
944
The regression test build a synthetic video stream and a synthetic
945
audio stream. Then these are encoded then decoded with all codecs or
946
formats. The CRC (or MD5) of each generated file is recorded in a
947
result file. Then a 'diff' is launched with the reference results and
948
the result file.
949

    
950
The regression test then goes on to test the ffserver code with a 
951
limited set of streams. It is important that this step runs correctly
952
as well.
953

    
954
Run 'make test' to test all the codecs.
955

    
956
Run 'make fulltest' to test all the codecs, formats and ffserver.
957

    
958
[Of course, some patches may change the regression tests results. In
959
this case, the regression tests reference results shall be modified
960
accordingly].
961

    
962
@bye