get rid of the last svn mentions
[libav.git] / doc / faq.texi
CommitLineData
7ff56c72
FB
1\input texinfo @c -*- texinfo -*-
2
f8a45fa1 3@settitle Libav FAQ
7ff56c72 4@titlepage
f8a45fa1 5@center @titlefont{Libav FAQ}
7ff56c72
FB
6@end titlepage
7
a8f0814a
JG
8@top
9
10@contents
7ff56c72 11
d485fed4
DB
12@chapter General Questions
13
f8a45fa1 14@section When will the next Libav version be released? / Why are Libav releases so few and far between?
d485fed4 15
f8a45fa1 16Like most open source projects Libav suffers from a certain lack of
d485fed4
DB
17manpower. For this reason the developers have to prioritize the work
18they do and putting out releases is not at the top of the list, fixing
19bugs and reviewing patches takes precedence. Please don't complain or
20request more timely and/or frequent releases unless you are willing to
21help out creating them.
22
f8a45fa1
JG
23@section I have a problem with an old version of Libav; where should I report it?
24Nowhere. We do not support old Libav versions in any way, we simply lack
2c880fe1 25the time, motivation and manpower to do so. If you have a problem with an
faa6f1c3 26old version of Libav, upgrade to the latest git snapshot. If you
2c880fe1 27still experience the problem, then you can report it according to the
21de9204 28guidelines in @url{http://libav.org/bugreports.html}.
d485fed4 29
f8a45fa1 30@section Why doesn't Libav support feature [xyz]?
d485fed4 31
f8a45fa1 32Because no one has taken on that task yet. Libav development is
d485fed4
DB
33driven by the tasks that are important to the individual developers.
34If there is a feature that is important to you, the best way to get
4f1ab3ce 35it implemented is to undertake the task yourself or sponsor a developer.
d485fed4 36
f8a45fa1 37@section Libav does not support codec XXX. Can you include a Windows DLL loader to support it?
d485fed4 38
4f1ab3ce 39No. Windows DLLs are not portable, bloated and often slow.
f8a45fa1 40Moreover Libav strives to support all codecs natively.
4f1ab3ce 41A DLL loader is not conducive to that goal.
d485fed4 42
21de9204 43@section My bug report/mail to libav-devel/user has not received any replies.
d485fed4
DB
44
45Likely reasons
46@itemize
47@item We are busy and haven't had time yet to read your report or
48investigate the issue.
21de9204 49@item You didn't follow @url{http://libav.org/bugreports.html}.
faa6f1c3 50@item You didn't use git master.
d485fed4
DB
51@item You reported a segmentation fault without gdb output.
52@item You describe a problem but not how to reproduce it.
53@item It's unclear if you use ffmpeg as command line tool or use
54libav* from another application.
55@item You speak about a video having problems on playback but
56not what you use to play it.
57@item We have no faint clue what you are talking about besides
f8a45fa1 58that it is related to Libav.
d485fed4
DB
59@end itemize
60
f8a45fa1 61@section Is there a forum for Libav? I do not like mailing lists.
d485fed4 62
242a2b7e
VP
63You may view our mailing lists with a more forum-alike look here:
64@url{http://dir.gmane.org/gmane.comp.video.ffmpeg.user},
d9fe7eb3 65but, if you post, please remember that our mailing list rules still apply there.
7ff56c72 66
cacf7199 67@section I cannot read this file although this format seems to be supported by ffmpeg.
7ff56c72 68
4f1ab3ce 69Even if ffmpeg can read the container format, it may not support all its
7ff56c72
FB
70codecs. Please consult the supported codec list in the ffmpeg
71documentation.
72
d485fed4
DB
73@section Which codecs are supported by Windows?
74
75Windows does not support standard formats like MPEG very well, unless you
831ec935 76install some additional codecs.
d485fed4
DB
77
78The following list of video codecs should work on most Windows systems:
79@table @option
80@item msmpeg4v2
81.avi/.asf
82@item msmpeg4
83.asf only
84@item wmv1
85.asf only
86@item wmv2
87.asf only
88@item mpeg4
831ec935 89Only if you have some MPEG-4 codec like ffdshow or Xvid installed.
d485fed4
DB
90@item mpeg1
91.mpg only
92@end table
93Note, ASF files often have .wmv or .wma extensions in Windows. It should also
94be mentioned that Microsoft claims a patent on the ASF format, and may sue
95or threaten users who create ASF files with non-Microsoft software. It is
96strongly advised to avoid ASF where possible.
97
98The following list of audio codecs should work on most Windows systems:
99@table @option
100@item adpcm_ima_wav
101@item adpcm_ms
102@item pcm
831ec935 103always
d485fed4 104@item mp3
831ec935 105If some MP3 codec like LAME is installed.
d485fed4
DB
106@end table
107
108
a28d9122
DB
109@chapter Compilation
110
111@section @code{error: can't find a register in class 'GENERAL_REGS' while reloading 'asm'}
112
113This is a bug in gcc. Do not report it to us. Instead, please report it to
114the gcc developers. Note that we will not add workarounds for gcc bugs.
115
5b43368d
DB
116Also note that (some of) the gcc developers believe this is not a bug or
117not a bug they should fix:
118@url{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=11203}.
119Then again, some of them do not know the difference between an undecidable
120problem and an NP-hard problem...
a28d9122 121
d485fed4
DB
122@chapter Usage
123
831ec935 124@section ffmpeg does not work; what is wrong?
d485fed4 125
4f1ab3ce 126Try a @code{make distclean} in the ffmpeg source directory before the build. If this does not help see
21de9204 127(@url{http://libav.org/bugreports.html}).
d485fed4 128
831ec935 129@section How do I encode single pictures into movies?
7ff56c72 130
1fee8b3a
VP
131First, rename your pictures to follow a numerical sequence.
132For example, img1.jpg, img2.jpg, img3.jpg,...
133Then you may run:
7ff56c72
FB
134
135@example
a9d21e78 136 ffmpeg -f image2 -i img%d.jpg /tmp/a.mpg
7ff56c72
FB
137@end example
138
1fee8b3a 139Notice that @samp{%d} is replaced by the image number.
7ff56c72 140
1fee8b3a 141@file{img%03d.jpg} means the sequence @file{img001.jpg}, @file{img002.jpg}, etc...
7ff56c72 142
49f64022
JVS
143If you have large number of pictures to rename, you can use the
144following command to ease the burden. The command, using the bourne
145shell syntax, symbolically links all files in the current directory
146that match @code{*jpg} to the @file{/tmp} directory in the sequence of
147@file{img001.jpg}, @file{img002.jpg} and so on.
148
149@example
e063f588 150 x=1; for i in *jpg; do counter=$(printf %03d $x); ln -s "$i" /tmp/img"$counter".jpg; x=$(($x+1)); done
49f64022
JVS
151@end example
152
153If you want to sequence them by oldest modified first, substitute
154@code{$(ls -r -t *jpg)} in place of @code{*jpg}.
155
156Then run:
157
158@example
159 ffmpeg -f image2 -i /tmp/img%03d.jpg /tmp/a.mpg
160@end example
161
1fee8b3a 162The same logic is used for any image format that ffmpeg reads.
7ff56c72 163
5965e1a9 164@section How do I encode movie to single pictures?
a9d21e78 165
3c88ea24 166Use:
ad21ad45 167
ad21ad45 168@example
3c88ea24 169 ffmpeg -i movie.mpg movie%d.jpg
ad21ad45
VP
170@end example
171
3c88ea24
BC
172The @file{movie.mpg} used as input will be converted to
173@file{movie1.jpg}, @file{movie2.jpg}, etc...
ad21ad45
VP
174
175Instead of relying on file format self-recognition, you may also use
176@table @option
177@item -vcodec ppm
178@item -vcodec png
179@item -vcodec mjpeg
180@end table
181to force the encoding.
182
183Applying that to the previous example:
184@example
3c88ea24 185 ffmpeg -i movie.mpg -f image2 -vcodec mjpeg menu%d.jpg
ad21ad45
VP
186@end example
187
188Beware that there is no "jpeg" codec. Use "mjpeg" instead.
189
5965e1a9 190@section Why do I see a slight quality degradation with multithreaded MPEG* encoding?
f2fe8752
RS
191
192For multithreaded MPEG* encoding, the encoded slices must be independent,
cacf7199
MM
193otherwise thread n would practically have to wait for n-1 to finish, so it's
194quite logical that there is a small reduction of quality. This is not a bug.
f2fe8752 195
5965e1a9 196@section How can I read from the standard input or write to the standard output?
47d944d2 197
831ec935 198Use @file{-} as file name.
47d944d2 199
9ba42958 200@section -f jpeg doesn't work.
fc3e9202 201
a9d21e78 202Try '-f image2 test%d.jpg'.
fc3e9202 203
cacf7199 204@section Why can I not change the framerate?
73468318 205
9ba42958 206Some codecs, like MPEG-1/2, only allow a small number of fixed framerates.
cacf7199 207Choose a different codec with the -vcodec command line option.
73468318 208
842eabc5 209@section How do I encode Xvid or DivX video with ffmpeg?
f62e9435 210
842eabc5 211Both Xvid and DivX (version 4+) are implementations of the ISO MPEG-4
f62e9435 212standard (note that there are many other coding formats that use this
831ec935 213same standard). Thus, use '-vcodec mpeg4' to encode in these formats. The
c9a08db9 214default fourcc stored in an MPEG-4-coded file will be 'FMP4'. If you want
115329f1
DB
215a different fourcc, use the '-vtag' option. E.g., '-vtag xvid' will
216force the fourcc 'xvid' to be stored as the video fourcc rather than the
f62e9435
MM
217default.
218
18e7d87c 219@section How do I encode videos which play on the iPod?
b4aead58
MN
220
221@table @option
18e7d87c 222@item needed stuff
095247b1 223-acodec libfaac -vcodec mpeg4 width<=320 height<=240
18e7d87c 224@item working stuff
4c74d166 225mv4, title
18e7d87c
DB
226@item non-working stuff
227B-frames
b4aead58 228@item example command line
4c74d166 229ffmpeg -i input -acodec libfaac -ab 128kb -vcodec mpeg4 -b 1200kb -mbd 2 -flags +mv4 -trellis 2 -aic 2 -cmp 2 -subcmp 2 -s 320x180 -metadata title=X output.mp4
b4aead58
MN
230@end table
231
18e7d87c 232@section How do I encode videos which play on the PSP?
b4aead58
MN
233
234@table @option
18e7d87c 235@item needed stuff
095247b1 236-acodec libfaac -vcodec mpeg4 width*height<=76800 width%16=0 height%16=0 -ar 24000 -r 30000/1001 or 15000/1001 -f psp
18e7d87c 237@item working stuff
4c74d166 238mv4, title
18e7d87c
DB
239@item non-working stuff
240B-frames
b4aead58 241@item example command line
4c74d166 242ffmpeg -i input -acodec libfaac -ab 128kb -vcodec mpeg4 -b 1200kb -ar 24000 -mbd 2 -flags +mv4 -trellis 2 -aic 2 -cmp 2 -subcmp 2 -s 368x192 -r 30000/1001 -metadata title=X -f psp output.mp4
f7709b1a 243@item needed stuff for H.264
b96e074d 244-acodec libfaac -vcodec libx264 width*height<=76800 width%16=0? height%16=0? -ar 48000 -coder 1 -r 30000/1001 or 15000/1001 -f psp
f7709b1a
MN
245@item working stuff for H.264
246title, loop filter
247@item non-working stuff for H.264
248CAVLC
249@item example command line
9c16add6 250ffmpeg -i input -acodec libfaac -ab 128kb -vcodec libx264 -b 1200kb -ar 48000 -mbd 2 -coder 1 -cmp 2 -subcmp 2 -s 368x192 -r 30000/1001 -metadata title=X -f psp -flags loop -trellis 2 -partitions parti4x4+parti8x8+partp4x4+partp8x8+partb8x8 output.mp4
084cadab
DS
251@item higher resolution for newer PSP firmwares, width<=480, height<=272
252-vcodec libx264 -level 21 -coder 1 -f psp
253@item example command line
254ffmpeg -i input -acodec libfaac -ab 128kb -ac 2 -ar 48000 -vcodec libx264 -level 21 -b 640kb -coder 1 -f psp -flags +loop -trellis 2 -partitions +parti4x4+parti8x8+partp4x4+partp8x8+partb8x8 -g 250 -s 480x272 output.mp4
b4aead58
MN
255@end table
256
16ab894e 257@section Which are good parameters for encoding high quality MPEG-4?
c62997a5 258
4c74d166 259'-mbd rd -flags +mv4+aic -trellis 2 -cmp 2 -subcmp 2 -g 300 -pass 1/2',
16ab894e 260things to try: '-bf 2', '-flags qprd', '-flags mv0', '-flags skiprd'.
c62997a5 261
16ab894e 262@section Which are good parameters for encoding high quality MPEG-1/MPEG-2?
c62997a5 263
cd0e37d3 264'-mbd rd -trellis 2 -cmp 2 -subcmp 2 -g 100 -pass 1/2'
16ab894e
DB
265but beware the '-g 100' might cause problems with some decoders.
266Things to try: '-bf 2', '-flags qprd', '-flags mv0', '-flags skiprd.
c62997a5 267
f278709c 268@section Interlaced video looks very bad when encoded with ffmpeg, what is wrong?
c62997a5 269
16ab894e
DB
270You should use '-flags +ilme+ildct' and maybe '-flags +alt' for interlaced
271material, and try '-top 0/1' if the result looks really messed-up.
c62997a5 272
99f6278e 273@section How can I read DirectShow files?
2c29781d 274
f8a45fa1 275If you have built Libav with @code{./configure --enable-avisynth}
99f6278e
DB
276(only possible on MinGW/Cygwin platforms),
277then you may use any file that DirectShow can read as input.
2c29781d
VP
278
279Just create an "input.avs" text file with this single line ...
280@example
281 DirectShowSource("C:\path to your file\yourfile.asf")
282@end example
99f6278e 283... and then feed that text file to FFmpeg:
2c29781d
VP
284@example
285 ffmpeg -i input.avs
286@end example
287
288For ANY other help on Avisynth, please visit @url{http://www.avisynth.org/}.
289
f7994861
VP
290@section How can I join video files?
291
5449190f 292A few multimedia containers (MPEG-1, MPEG-2 PS, DV) allow to join video files by
f7994861
VP
293merely concatenating them.
294
295Hence you may concatenate your multimedia files by first transcoding them to
296these privileged formats, then using the humble @code{cat} command (or the
5449190f 297equally humble @code{copy} under Windows), and finally transcoding back to your
f7994861
VP
298format of choice.
299
300@example
301ffmpeg -i input1.avi -sameq intermediate1.mpg
302ffmpeg -i input2.avi -sameq intermediate2.mpg
303cat intermediate1.mpg intermediate2.mpg > intermediate_all.mpg
304ffmpeg -i intermediate_all.mpg -sameq output.avi
305@end example
306
307Notice that you should either use @code{-sameq} or set a reasonably high
308bitrate for your intermediate and output files, if you want to preserve
309video quality.
310
5449190f 311Also notice that you may avoid the huge intermediate files by taking advantage
f7994861
VP
312of named pipes, should your platform support it:
313
314@example
315mkfifo intermediate1.mpg
316mkfifo intermediate2.mpg
317ffmpeg -i input1.avi -sameq -y intermediate1.mpg < /dev/null &
318ffmpeg -i input2.avi -sameq -y intermediate2.mpg < /dev/null &
319cat intermediate1.mpg intermediate2.mpg |\
095247b1 320ffmpeg -f mpeg -i - -sameq -vcodec mpeg4 -acodec libmp3lame output.avi
f7994861
VP
321@end example
322
323Similarly, the yuv4mpegpipe format, and the raw video, raw audio codecs also
324allow concatenation, and the transcoding step is almost lossless.
76597127
JVS
325When using multiple yuv4mpegpipe(s), the first line needs to be discarded
326from all but the first stream. This can be accomplished by piping through
327@code{tail} as seen below. Note that when piping through @code{tail} you
328must use command grouping, @code{@{ ;@}}, to background properly.
329
f7994861
VP
330For example, let's say we want to join two FLV files into an output.flv file:
331
332@example
333mkfifo temp1.a
334mkfifo temp1.v
335mkfifo temp2.a
336mkfifo temp2.v
337mkfifo all.a
338mkfifo all.v
339ffmpeg -i input1.flv -vn -f u16le -acodec pcm_s16le -ac 2 -ar 44100 - > temp1.a < /dev/null &
340ffmpeg -i input2.flv -vn -f u16le -acodec pcm_s16le -ac 2 -ar 44100 - > temp2.a < /dev/null &
341ffmpeg -i input1.flv -an -f yuv4mpegpipe - > temp1.v < /dev/null &
76597127 342@{ ffmpeg -i input2.flv -an -f yuv4mpegpipe - < /dev/null | tail -n +2 > temp2.v ; @} &
f7994861
VP
343cat temp1.a temp2.a > all.a &
344cat temp1.v temp2.v > all.v &
345ffmpeg -f u16le -acodec pcm_s16le -ac 2 -ar 44100 -i all.a \
346 -f yuv4mpegpipe -i all.v \
347 -sameq -y output.flv
348rm temp[12].[av] all.[av]
349@end example
350
fa78d895 351@section FFmpeg does not adhere to the -maxrate setting, some frames are bigger than maxrate/fps.
3b36389a 352
fa78d895 353Read the MPEG spec about video buffer verifier.
3b36389a 354
fa78d895 355@section I want CBR, but no matter what I do frame sizes differ.
3b36389a 356
fa78d895
DB
357You do not understand what CBR is, please read the MPEG spec.
358Read about video buffer verifier and constant bitrate.
359The one sentence summary is that there is a buffer and the input rate is
3b36389a
MN
360constant, the output can vary as needed.
361
fa78d895 362@section How do I check if a stream is CBR?
3b36389a
MN
363
364To quote the MPEG-2 spec:
365"There is no way to tell that a bitstream is constant bitrate without
366examining all of the vbv_delay values and making complicated computations."
367
86852499 368
7ff56c72
FB
369@chapter Development
370
f8a45fa1 371@section Are there examples illustrating how to use the Libav libraries, particularly libavcodec and libavformat?
a93b9dba 372
f8a45fa1 373Yes. Read the Developers Guide of the Libav documentation. Alternatively,
115329f1 374examine the source code for one of the many open source projects that
f8a45fa1 375already incorporate Libav at (@url{projects.html}).
a93b9dba 376
5965e1a9 377@section Can you support my C compiler XXX?
7ff56c72 378
e867d9b9
DB
379It depends. If your compiler is C99-compliant, then patches to support
380it are likely to be welcome if they do not pollute the source code
381with @code{#ifdef}s related to the compiler.
7ff56c72 382
a9d5a448 383@section Is Microsoft Visual C++ supported?
2f0b8fbb 384
a9d5a448 385No. Microsoft Visual C++ is not compliant to the C99 standard and does
f8a45fa1 386not - among other things - support the inline assembly used in Libav.
19671d3f 387If you wish to use MSVC++ for your
c1989552 388project then you can link the MSVC++ code with libav* as long as
2f0b8fbb 389you compile the latter with a working C compiler. For more information, see
f8a45fa1 390the @emph{Microsoft Visual C++ compatibility} section in the Libav
c1989552 391documentation.
2f0b8fbb 392
f8a45fa1 393There have been efforts to make Libav compatible with MSVC++ in the
2f0b8fbb 394past. However, they have all been rejected as too intrusive, especially
a9d5a448 395since MinGW does the job adequately. None of the core developers
c1989552 396work with MSVC++ and thus this item is low priority. Should you find
2f0b8fbb
DB
397the silver bullet that solves this problem, feel free to shoot it at us.
398
19671d3f
RP
399We strongly recommend you to move over from MSVC++ to MinGW tools.
400
f8a45fa1 401@section Can I use Libav or libavcodec under Windows?
7ff56c72 402
f8a45fa1
JG
403Yes, but the Cygwin or MinGW tools @emph{must} be used to compile Libav.
404Read the @emph{Windows} section in the Libav documentation to find more
c1989552 405information.
7ff56c72 406
f8a45fa1 407To get help and instructions for building Libav under Windows, check out
e2ef53fc 408the FFmpeg Windows Help Forum at
ab5ce4ae 409@url{http://ffmpeg.arrozcru.org/}.
e2ef53fc 410
5965e1a9 411@section Can you add automake, libtool or autoconf support?
7ff56c72 412
e867d9b9 413No. These tools are too bloated and they complicate the build.
7ff56c72 414
5965e1a9 415@section Why not rewrite ffmpeg in object-oriented C++?
fbf33e4f 416
f8a45fa1 417Libav is already organized in a highly modular manner and does not need to
115329f1 418be rewritten in a formal object language. Further, many of the developers
cacf7199 419favor straight C; it works for them. For more arguments on this matter,
bc155732 420read "Programming Religion" at (@url{http://www.tux.org/lkml/#s15}).
cacf7199 421
5965e1a9 422@section Why are the ffmpeg programs devoid of debugging symbols?
cacf7199
MM
423
424The build process creates ffmpeg_g, ffplay_g, etc. which contain full debug
831ec935 425information. Those binaries are stripped to create ffmpeg, ffplay, etc. If
b08f59dc 426you need the debug information, use the *_g versions.
fbf33e4f 427
5965e1a9 428@section I do not like the LGPL, can I contribute code under the GPL instead?
61a1e081 429
e180129f 430Yes, as long as the code is optional and can easily and cleanly be placed
b250f9c6 431under #if CONFIG_GPL without breaking anything. So for example a new codec
831ec935 432or filter would be OK under GPL while a bug fix to LGPL code would not.
61a1e081 433
e180129f 434@section I want to compile xyz.c alone but my compiler produced many errors.
61a1e081 435
e180129f
DB
436Common code is in its own files in libav* and is used by the individual
437codecs. They will not work without the common parts, you have to compile
438the whole libav*. If you wish, disable some parts with configure switches.
439You can also try to hack it and remove more, but if you had problems fixing
440the compilation failure then you are probably not qualified for this.
61a1e081 441
4cb3aa09
PI
442@section I'm using libavcodec from within my C++ application but the linker complains about missing symbols which seem to be available.
443
f8a45fa1 444Libav is a pure C project, so to use the libraries within your C++ application
4cb3aa09 445you need to explicitly state that you are using a C library. You can do this by
f8a45fa1 446encompassing your Libav includes using @code{extern "C"}.
4cb3aa09
PI
447
448See @url{http://www.parashift.com/c++-faq-lite/mixing-c-and-cpp.html#faq-32.3}
449
2cab6401 450@section I have a file in memory / a API different from *open/*read/ libc how do I use it with libavformat?
f994f61e 451
e7f6c252 452You have to implement a URLProtocol, see @file{libavformat/file.c} in
f8a45fa1 453Libav and @file{libmpdemux/demux_lavf.c} in MPlayer sources.
f994f61e 454
e9766450
RP
455@section I get "No compatible shell script interpreter found." in MSys.
456
457The standard MSys bash (2.04) is broken. You need to install 2.05 or later.
458
e75f8997
RP
459@section I get "./configure: line <xxx>: pr: command not found" in MSys.
460
461The standard MSys install doesn't come with pr. You need to get it from the coreutils package.
462
7c1ebf17 463@section Where can I find libav* headers for Pascal/Delphi?
04704a78
MN
464
465see @url{http://www.iversenit.dk/dev/ffmpeg-headers/}
466
7c1ebf17 467@section Where is the documentation about ffv1, msmpeg4, asv1, 4xm?
afe28f7c 468
387fe82c 469see @url{http://www.ffmpeg.org/~michael/}
afe28f7c 470
29569571 471@section How do I feed H.263-RTP (and other codecs in RTP) to libavcodec?
8749180c 472
241fb0c4 473Even if peculiar since it is network oriented, RTP is a container like any
33ed2d84
LB
474other. You have to @emph{demux} RTP before feeding the payload to libavcodec.
475In this specific case please look at RFC 4629 to see how it should be done.
8749180c 476
29569571 477@section AVStream.r_frame_rate is wrong, it is much larger than the framerate.
70fd3975
MN
478
479r_frame_rate is NOT the average framerate, it is the smallest framerate
29569571
DB
480that can accurately represent all timestamps. So no, it is not
481wrong if it is larger than the average!
482For example, if you have mixed 25 and 30 fps content, then r_frame_rate
70fd3975
MN
483will be 150.
484
7ff56c72 485@bye