Editorial cleanup, thanks Diego =)
[libav.git] / doc / faq.texi
CommitLineData
7ff56c72
FB
1\input texinfo @c -*- texinfo -*-
2
3@settitle FFmpeg FAQ
4@titlepage
5@sp 7
6@center @titlefont{FFmpeg FAQ}
7@sp 3
8@end titlepage
9
10
11@chapter General Problems
12
cacf7199 13@section I cannot read this file although this format seems to be supported by ffmpeg.
7ff56c72
FB
14
15Even if ffmpeg can read the file format, it may not support all its
16codecs. Please consult the supported codec list in the ffmpeg
17documentation.
18
5965e1a9 19@section How do I encode single pictures to movies?
7ff56c72 20
1fee8b3a
VP
21First, rename your pictures to follow a numerical sequence.
22For example, img1.jpg, img2.jpg, img3.jpg,...
23Then you may run:
7ff56c72
FB
24
25@example
a9d21e78 26 ffmpeg -f image2 -i img%d.jpg /tmp/a.mpg
7ff56c72
FB
27@end example
28
1fee8b3a 29Notice that @samp{%d} is replaced by the image number.
7ff56c72 30
1fee8b3a 31@file{img%03d.jpg} means the sequence @file{img001.jpg}, @file{img002.jpg}, etc...
7ff56c72 32
1fee8b3a 33The same logic is used for any image format that ffmpeg reads.
7ff56c72 34
5965e1a9 35@section How do I encode movie to single pictures?
a9d21e78 36
3c88ea24 37Use:
ad21ad45 38
ad21ad45 39@example
3c88ea24 40 ffmpeg -i movie.mpg movie%d.jpg
ad21ad45
VP
41@end example
42
3c88ea24
BC
43The @file{movie.mpg} used as input will be converted to
44@file{movie1.jpg}, @file{movie2.jpg}, etc...
ad21ad45
VP
45
46Instead of relying on file format self-recognition, you may also use
47@table @option
48@item -vcodec ppm
49@item -vcodec png
50@item -vcodec mjpeg
51@end table
52to force the encoding.
53
54Applying that to the previous example:
55@example
3c88ea24 56 ffmpeg -i movie.mpg -f image2 -vcodec mjpeg menu%d.jpg
ad21ad45
VP
57@end example
58
59Beware that there is no "jpeg" codec. Use "mjpeg" instead.
60
5965e1a9 61@section FFmpeg does not support codec XXX. Can you include a Windows DLL loader to support it?
7ff56c72
FB
62
63No. FFmpeg only supports open source codecs. Windows DLLs are not
64portable, bloated and often slow.
65
5965e1a9 66@section I get "Unsupported codec (id=86043) for input stream #0.1". What is the problem?
7a9d265b
BL
67
68This is the Qcelp codec, FFmpeg has no support for that codec currently. Try mencoder/mplayer it might work.
69
5965e1a9 70@section Why do I see a slight quality degradation with multithreaded MPEG* encoding?
f2fe8752
RS
71
72For multithreaded MPEG* encoding, the encoded slices must be independent,
cacf7199
MM
73otherwise thread n would practically have to wait for n-1 to finish, so it's
74quite logical that there is a small reduction of quality. This is not a bug.
f2fe8752 75
5965e1a9 76@section How can I read from the standard input or write to the standard output?
47d944d2
FB
77
78Use @file{-} as filename.
79
5965e1a9 80@section Why does ffmpeg not decode audio in VOB files?
db0e9b03 81
cacf7199 82The audio is AC3 (a.k.a. A/52). AC3 decoding is an optional component in ffmpeg
115329f1 83as the component that handles AC3 decoding (liba52) is currently released under
cacf7199 84the GPL. If you have liba52 installed on your system, enable AC3 decoding
ab9c4087 85with @code{./configure --enable-liba52 --enable-gpl}. Take care: by
db0e9b03
FB
86enabling AC3, you automatically change the license of libavcodec from
87LGPL to GPL.
88
5965e1a9 89@section Which codecs are supported by Windows?
c75f51f6 90
115329f1 91Windows does not support standard formats like MPEG very well, unless you
c75f51f6
MN
92install some additional codecs
93
9ba42958 94The following list of video codecs should work on most Windows systems:
c75f51f6
MN
95@table @option
96@item msmpeg4v2
97.avi/.asf
98@item msmpeg4
99.asf only
100@item wmv1
101.asf only
102@item wmv2
103.asf only
104@item mpeg4
9ba42958 105only if you have some MPEG-4 codec installed like ffdshow or XviD
c75f51f6
MN
106@item mpeg1
107.mpg only
108@end table
115329f1
DB
109Note, ASF files often have .wmv or .wma extensions in Windows. It should also
110be mentioned that Microsoft claims a patent on the ASF format, and may sue
cacf7199
MM
111or threaten users who create ASF files with non-Microsoft software. It is
112strongly advised to avoid ASF where possible.
c75f51f6 113
9ba42958 114The following list of audio codecs should work on most Windows systems:
c75f51f6
MN
115@table @option
116@item adpcm_ima_wav
117@item adpcm_ms
118@item pcm
119@item mp3
9ba42958 120if some MP3 codec like LAME is installed
c75f51f6
MN
121@end table
122
9ba42958 123@section Why does the chrominance data seem to be sampled at a different time from the luminance data on bt8x8 captures on Linux?
7c0dc383 124
115329f1 125This is a well-known bug in the bt8x8 driver. For 2.4.26 there is a patch at
5d171758 126(@url{http://svn.mplayerhq.hu/michael/trunk/patches/bttv-420-2.4.26.patch?view=co}). This may also
cacf7199 127apply cleanly to other 2.4-series kernels.
7c0dc383 128
87759af9 129@section How do I avoid the ugly aliasing artifacts in bt8x8 captures on Linux?
7c0dc383 130
cacf7199 131Pass 'combfilter=1 lumafilter=1' to the bttv driver. Note though that 'combfilter=1'
5d171758
MN
132will cause somewhat too strong filtering. A fix is to apply (@url{http://svn.mplayerhq.hu/michael/trunk/patches/bttv-comb-2.4.26.patch?view=co})
133or (@url{http://svn.mplayerhq.hu/michael/trunk/patches/bttv-comb-2.6.6.patch?view=co})
cacf7199 134and pass 'combfilter=2'.
7c0dc383 135
9ba42958 136@section I have a problem with an old version of ffmpeg; where should I report it?
cacf7199 137Nowhere. Upgrade to the latest release or if there is no recent release upgrade
1c1b5a40 138to Subversion HEAD. You could also try to report it. Maybe you will get lucky and
87759af9 139become the first person in history to get an answer different from "upgrade
1c1b5a40 140to Subversion HEAD".
dd1368db 141
9ba42958 142@section -f jpeg doesn't work.
fc3e9202 143
a9d21e78 144Try '-f image2 test%d.jpg'.
fc3e9202 145
cacf7199 146@section Why can I not change the framerate?
73468318 147
9ba42958 148Some codecs, like MPEG-1/2, only allow a small number of fixed framerates.
cacf7199 149Choose a different codec with the -vcodec command line option.
73468318 150
cacf7199 151@section ffmpeg does not work; What is wrong?
9291d591 152
123bff4b 153Try a 'make distclean' in the ffmpeg source directory before the build. If this does not help see
7a771569 154(@url{http://ffmpeg.org/bugreports.php}).
9291d591 155
87759af9 156@section How do I encode XviD or DivX video with ffmpeg?
f62e9435 157
87759af9 158Both XviD and DivX (version 4+) are implementations of the ISO MPEG-4
f62e9435
MM
159standard (note that there are many other coding formats that use this
160same standard). Thus, use '-vcodec mpeg4' to encode these formats. The
c9a08db9 161default fourcc stored in an MPEG-4-coded file will be 'FMP4'. If you want
115329f1
DB
162a different fourcc, use the '-vtag' option. E.g., '-vtag xvid' will
163force the fourcc 'xvid' to be stored as the video fourcc rather than the
f62e9435
MM
164default.
165
18e7d87c 166@section How do I encode videos which play on the iPod?
b4aead58
MN
167
168@table @option
18e7d87c 169@item needed stuff
095247b1 170-acodec libfaac -vcodec mpeg4 width<=320 height<=240
18e7d87c 171@item working stuff
b4aead58 1724mv, title
18e7d87c
DB
173@item non-working stuff
174B-frames
b4aead58 175@item example command line
095247b1 176ffmpeg -i input -acodec libfaac -ab 128kb -vcodec mpeg4 -b 1200kb -mbd 2 -flags +4mv+trell -aic 2 -cmp 2 -subcmp 2 -s 320x180 -title X output.mp4
b4aead58
MN
177@end table
178
18e7d87c 179@section How do I encode videos which play on the PSP?
b4aead58
MN
180
181@table @option
18e7d87c 182@item needed stuff
095247b1 183-acodec libfaac -vcodec mpeg4 width*height<=76800 width%16=0 height%16=0 -ar 24000 -r 30000/1001 or 15000/1001 -f psp
18e7d87c 184@item working stuff
b4aead58 1854mv, title
18e7d87c
DB
186@item non-working stuff
187B-frames
b4aead58 188@item example command line
095247b1 189ffmpeg -i input -acodec libfaac -ab 128kb -vcodec mpeg4 -b 1200kb -ar 24000 -mbd 2 -flags +4mv+trell -aic 2 -cmp 2 -subcmp 2 -s 368x192 -r 30000/1001 -title X -f psp output.mp4
f7709b1a 190@item needed stuff for H.264
095247b1 191-acodec libfaac -vcodec h264 width*height<=76800 width%16=0? height%16=0? -ar 48000 -coder 1 -r 30000/1001 or 15000/1001 -f psp
f7709b1a
MN
192@item working stuff for H.264
193title, loop filter
194@item non-working stuff for H.264
195CAVLC
196@item example command line
095247b1 197ffmpeg -i input -acodec libfaac -ab 128kb -vcodec h264 -b 1200kb -ar 48000 -mbd 2 -coder 1 -cmp 2 -subcmp 2 -s 368x192 -r 30000/1001 -title X -f psp -flags loop -trellis 2 -partitions parti4x4+parti8x8+partp4x4+partp8x8+partb8x8 output.mp4
b4aead58
MN
198@end table
199
16ab894e 200@section Which are good parameters for encoding high quality MPEG-4?
c62997a5 201
16ab894e
DB
202'-mbd rd -flags +4mv+trell+aic -cmp 2 -subcmp 2 -g 300 -pass 1/2',
203things to try: '-bf 2', '-flags qprd', '-flags mv0', '-flags skiprd'.
c62997a5 204
16ab894e 205@section Which are good parameters for encoding high quality MPEG-1/MPEG-2?
c62997a5 206
16ab894e
DB
207'-mbd rd -flags +trell -cmp 2 -subcmp 2 -g 100 -pass 1/2'
208but beware the '-g 100' might cause problems with some decoders.
209Things to try: '-bf 2', '-flags qprd', '-flags mv0', '-flags skiprd.
c62997a5
MN
210
211@section Interlaced video looks very bad when encoded with ffmpeg, whats wrong?
212
16ab894e
DB
213You should use '-flags +ilme+ildct' and maybe '-flags +alt' for interlaced
214material, and try '-top 0/1' if the result looks really messed-up.
c62997a5 215
99f6278e 216@section How can I read DirectShow files?
2c29781d 217
99f6278e
DB
218If you have built FFmpeg with @code{./configure --enable-avisynth}
219(only possible on MinGW/Cygwin platforms),
220then you may use any file that DirectShow can read as input.
221(Be aware that this feature has been recently added,
222so you will need to help yourself in case of problems.)
2c29781d
VP
223
224Just create an "input.avs" text file with this single line ...
225@example
226 DirectShowSource("C:\path to your file\yourfile.asf")
227@end example
99f6278e 228... and then feed that text file to FFmpeg:
2c29781d
VP
229@example
230 ffmpeg -i input.avs
231@end example
232
233For ANY other help on Avisynth, please visit @url{http://www.avisynth.org/}.
234
626fe955
DB
235@section My bugreport/mail to ffmpeg-devel/user has not received any replies.
236
92574878 237Likely reasons
626fe955
DB
238@itemize
239@item We are busy and haven't had time yet to read your report or
240investigate the issue.
241@item You didn't follow bugreports.html.
242@item You didn't use Subversion HEAD.
243@item You reported a segmentation fault without gdb output.
244@item You describe a problem but not how to reproduce it.
245@item It's unclear if you use ffmpeg as command line tool or use
246libav* from another application.
247@item You speak about a video having problems on playback but
248not what you use to play it.
249@item We have no faint clue what you are talking about besides
250that it is related to FFmpeg.
251@end itemize
92574878 252
f7994861
VP
253@section How can I join video files?
254
5449190f 255A few multimedia containers (MPEG-1, MPEG-2 PS, DV) allow to join video files by
f7994861
VP
256merely concatenating them.
257
258Hence you may concatenate your multimedia files by first transcoding them to
259these privileged formats, then using the humble @code{cat} command (or the
5449190f 260equally humble @code{copy} under Windows), and finally transcoding back to your
f7994861
VP
261format of choice.
262
263@example
264ffmpeg -i input1.avi -sameq intermediate1.mpg
265ffmpeg -i input2.avi -sameq intermediate2.mpg
266cat intermediate1.mpg intermediate2.mpg > intermediate_all.mpg
267ffmpeg -i intermediate_all.mpg -sameq output.avi
268@end example
269
270Notice that you should either use @code{-sameq} or set a reasonably high
271bitrate for your intermediate and output files, if you want to preserve
272video quality.
273
5449190f 274Also notice that you may avoid the huge intermediate files by taking advantage
f7994861
VP
275of named pipes, should your platform support it:
276
277@example
278mkfifo intermediate1.mpg
279mkfifo intermediate2.mpg
280ffmpeg -i input1.avi -sameq -y intermediate1.mpg < /dev/null &
281ffmpeg -i input2.avi -sameq -y intermediate2.mpg < /dev/null &
282cat intermediate1.mpg intermediate2.mpg |\
095247b1 283ffmpeg -f mpeg -i - -sameq -vcodec mpeg4 -acodec libmp3lame output.avi
f7994861
VP
284@end example
285
286Similarly, the yuv4mpegpipe format, and the raw video, raw audio codecs also
287allow concatenation, and the transcoding step is almost lossless.
288
289For example, let's say we want to join two FLV files into an output.flv file:
290
291@example
292mkfifo temp1.a
293mkfifo temp1.v
294mkfifo temp2.a
295mkfifo temp2.v
296mkfifo all.a
297mkfifo all.v
298ffmpeg -i input1.flv -vn -f u16le -acodec pcm_s16le -ac 2 -ar 44100 - > temp1.a < /dev/null &
299ffmpeg -i input2.flv -vn -f u16le -acodec pcm_s16le -ac 2 -ar 44100 - > temp2.a < /dev/null &
300ffmpeg -i input1.flv -an -f yuv4mpegpipe - > temp1.v < /dev/null &
301ffmpeg -i input2.flv -an -f yuv4mpegpipe - > temp2.v < /dev/null &
302cat temp1.a temp2.a > all.a &
303cat temp1.v temp2.v > all.v &
304ffmpeg -f u16le -acodec pcm_s16le -ac 2 -ar 44100 -i all.a \
305 -f yuv4mpegpipe -i all.v \
306 -sameq -y output.flv
307rm temp[12].[av] all.[av]
308@end example
309
7ff56c72
FB
310@chapter Development
311
f007d358
DB
312@section When will the next FFmpeg version be released? / Why are FFmpeg releases so few and far between?
313
314Like most open source projects FFmpeg suffers from a certain lack of
315manpower. For this reason the developers have to prioritize the work
316they do and putting out releases is not at the top of the list, fixing
317bugs and reviewing patches takes precedence. Please don't complain or
318request more timely and/or frequent releases unless you are willing to
319help out creating them.
320
4519b8a6
DB
321@section Why doesn't FFmpeg support feature [xyz]?
322
323Because no one has taken on that task yet. FFmpeg development is
324driven by the tasks that are important to the individual developers.
325If there is a feature that is important to you, the best way to get
326it implemented is to undertake the task yourself.
327
328
5965e1a9 329@section Are there examples illustrating how to use the FFmpeg libraries, particularly libavcodec and libavformat?
a93b9dba 330
cacf7199 331Yes. Read the Developers Guide of the FFmpeg documentation. Alternatively,
115329f1 332examine the source code for one of the many open source projects that
cacf7199 333already incorporate ffmpeg at (@url{projects.php}).
a93b9dba 334
5965e1a9 335@section Can you support my C compiler XXX?
7ff56c72 336
e867d9b9
DB
337It depends. If your compiler is C99-compliant, then patches to support
338it are likely to be welcome if they do not pollute the source code
339with @code{#ifdef}s related to the compiler.
7ff56c72 340
2f0b8fbb
DB
341@section Visual C++ produces many errors.
342
343Visual C++ is not compliant to the C standard and does not support
344the inline assembly used in FFmpeg.
345If you wish - for whatever weird reason - to use Visual C++ for your
346project then you can link the Visual C++ code with libav* as long as
347you compile the latter with a working C compiler. For more information, see
348the @emph{Visual C++ compatibility} section in the FFmpeg documentation.
349
350There have been efforts to make FFmpeg compatible with Visual C++ in the
351past. However, they have all been rejected as too intrusive, especially
352since MinGW does the job perfectly adequately. None of the core developers
353work with Visual C++ and thus this item is low priority. Should you find
354the silver bullet that solves this problem, feel free to shoot it at us.
355
5965e1a9 356@section Can I use FFmpeg or libavcodec under Windows?
7ff56c72 357
988a9f9e
FB
358Yes, but the MinGW tools @emph{must} be used to compile FFmpeg. You
359can link the resulting DLLs with any other Windows program. Read the
be0efc0c
MB
360@emph{Native Windows Compilation} and @emph{Visual C++ compatibility}
361sections in the FFmpeg documentation to find more information.
7ff56c72 362
e2ef53fc
DB
363To get help and instructions for using FFmpeg under Windows, check out
364the FFmpeg Windows Help Forum at
365@url{http://arrozcru.no-ip.org/ffmpeg/}.
366
5965e1a9 367@section Can you add automake, libtool or autoconf support?
7ff56c72 368
e867d9b9 369No. These tools are too bloated and they complicate the build.
7ff56c72 370
5965e1a9 371@section Why not rewrite ffmpeg in object-oriented C++?
fbf33e4f 372
87759af9 373ffmpeg is already organized in a highly modular manner and does not need to
115329f1 374be rewritten in a formal object language. Further, many of the developers
cacf7199 375favor straight C; it works for them. For more arguments on this matter,
bc155732 376read "Programming Religion" at (@url{http://www.tux.org/lkml/#s15}).
cacf7199 377
5965e1a9 378@section Why are the ffmpeg programs devoid of debugging symbols?
cacf7199
MM
379
380The build process creates ffmpeg_g, ffplay_g, etc. which contain full debug
381information. Those binaries are strip'd to create ffmpeg, ffplay, etc. If
382you need the debug information, used the *_g versions.
fbf33e4f 383
5965e1a9 384@section I do not like the LGPL, can I contribute code under the GPL instead?
61a1e081 385
e180129f
DB
386Yes, as long as the code is optional and can easily and cleanly be placed
387under #ifdef CONFIG_GPL without breaking anything. So for example a new codec
388or filter would be OK under GPL while a bugfix to LGPL code would not.
61a1e081 389
e180129f 390@section I want to compile xyz.c alone but my compiler produced many errors.
61a1e081 391
e180129f
DB
392Common code is in its own files in libav* and is used by the individual
393codecs. They will not work without the common parts, you have to compile
394the whole libav*. If you wish, disable some parts with configure switches.
395You can also try to hack it and remove more, but if you had problems fixing
396the compilation failure then you are probably not qualified for this.
61a1e081 397
5965e1a9 398@section I have a file in memory / a API different from *open/*read/ libc how do i use it with libavformat?
f994f61e 399
1c1b5a40
DB
400You have to implement a URLProtocol, see libavformat/file.c in FFmpeg
401and libmpdemux/demux_lavf.c in MPlayer sources.
f994f61e 402
e9766450
RP
403@section I get "No compatible shell script interpreter found." in MSys.
404
405The standard MSys bash (2.04) is broken. You need to install 2.05 or later.
406
5c159f40 407@section I tried to pass RTP packets into a decoder, but it doesn't work.
b72ad042 408
241fb0c4
LB
409RTP is a container format like any other, you must first depacketize the
410codec frames/samples stored in RTP and then feed to the decoder.
b72ad042 411
7c1ebf17 412@section Where can I find libav* headers for Pascal/Delphi?
04704a78
MN
413
414see @url{http://www.iversenit.dk/dev/ffmpeg-headers/}
415
7c1ebf17 416@section Where is the documentation about ffv1, msmpeg4, asv1, 4xm?
afe28f7c
MN
417
418see @url{http://svn.mplayerhq.hu/michael/trunk/docs/}
419
33ed2d84 420@section how do I feed H.263-RTP (and other codecs in RTP) to libavcodec?
8749180c 421
241fb0c4 422Even if peculiar since it is network oriented, RTP is a container like any
33ed2d84
LB
423other. You have to @emph{demux} RTP before feeding the payload to libavcodec.
424In this specific case please look at RFC 4629 to see how it should be done.
8749180c 425
7ff56c72 426@bye