faq: Solutions for common problems with sample paths when running FATE.
[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 Why doesn't Libav support feature [xyz]?
d485fed4 15
f8a45fa1 16Because no one has taken on that task yet. Libav development is
d485fed4
DB
17driven by the tasks that are important to the individual developers.
18If there is a feature that is important to you, the best way to get
4f1ab3ce 19it implemented is to undertake the task yourself or sponsor a developer.
d485fed4 20
f8a45fa1 21@section Libav does not support codec XXX. Can you include a Windows DLL loader to support it?
d485fed4 22
4f1ab3ce 23No. Windows DLLs are not portable, bloated and often slow.
f8a45fa1 24Moreover Libav strives to support all codecs natively.
4f1ab3ce 25A DLL loader is not conducive to that goal.
d485fed4 26
708060d7 27@section I cannot read this file although this format seems to be supported by avconv.
7ff56c72 28
708060d7
LB
29Even if avconv can read the container format, it may not support all its
30codecs. Please consult the supported codec list in the avconv
7ff56c72
FB
31documentation.
32
d485fed4
DB
33@section Which codecs are supported by Windows?
34
35Windows does not support standard formats like MPEG very well, unless you
831ec935 36install some additional codecs.
d485fed4
DB
37
38The following list of video codecs should work on most Windows systems:
39@table @option
40@item msmpeg4v2
41.avi/.asf
42@item msmpeg4
43.asf only
44@item wmv1
45.asf only
46@item wmv2
47.asf only
48@item mpeg4
831ec935 49Only if you have some MPEG-4 codec like ffdshow or Xvid installed.
70ff5573 50@item mpeg1video
d485fed4
DB
51.mpg only
52@end table
53Note, ASF files often have .wmv or .wma extensions in Windows. It should also
54be mentioned that Microsoft claims a patent on the ASF format, and may sue
55or threaten users who create ASF files with non-Microsoft software. It is
56strongly advised to avoid ASF where possible.
57
58The following list of audio codecs should work on most Windows systems:
59@table @option
60@item adpcm_ima_wav
61@item adpcm_ms
70ff5573 62@item pcm_s16le
831ec935 63always
70ff5573 64@item libmp3lame
831ec935 65If some MP3 codec like LAME is installed.
d485fed4
DB
66@end table
67
68
a28d9122
DB
69@chapter Compilation
70
71@section @code{error: can't find a register in class 'GENERAL_REGS' while reloading 'asm'}
72
73This is a bug in gcc. Do not report it to us. Instead, please report it to
74the gcc developers. Note that we will not add workarounds for gcc bugs.
75
5b43368d
DB
76Also note that (some of) the gcc developers believe this is not a bug or
77not a bug they should fix:
78@url{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=11203}.
79Then again, some of them do not know the difference between an undecidable
80problem and an NP-hard problem...
a28d9122 81
d485fed4
DB
82@chapter Usage
83
831ec935 84@section How do I encode single pictures into movies?
7ff56c72 85
1fee8b3a
VP
86First, rename your pictures to follow a numerical sequence.
87For example, img1.jpg, img2.jpg, img3.jpg,...
88Then you may run:
7ff56c72
FB
89
90@example
708060d7 91 avconv -f image2 -i img%d.jpg /tmp/a.mpg
7ff56c72
FB
92@end example
93
1fee8b3a 94Notice that @samp{%d} is replaced by the image number.
7ff56c72 95
1fee8b3a 96@file{img%03d.jpg} means the sequence @file{img001.jpg}, @file{img002.jpg}, etc...
7ff56c72 97
49f64022
JVS
98If you have large number of pictures to rename, you can use the
99following command to ease the burden. The command, using the bourne
100shell syntax, symbolically links all files in the current directory
101that match @code{*jpg} to the @file{/tmp} directory in the sequence of
102@file{img001.jpg}, @file{img002.jpg} and so on.
103
104@example
e063f588 105 x=1; for i in *jpg; do counter=$(printf %03d $x); ln -s "$i" /tmp/img"$counter".jpg; x=$(($x+1)); done
49f64022
JVS
106@end example
107
108If you want to sequence them by oldest modified first, substitute
109@code{$(ls -r -t *jpg)} in place of @code{*jpg}.
110
111Then run:
112
113@example
708060d7 114 avconv -f image2 -i /tmp/img%03d.jpg /tmp/a.mpg
49f64022
JVS
115@end example
116
708060d7 117The same logic is used for any image format that avconv reads.
7ff56c72 118
5965e1a9 119@section How do I encode movie to single pictures?
a9d21e78 120
3c88ea24 121Use:
ad21ad45 122
ad21ad45 123@example
708060d7 124 avconv -i movie.mpg movie%d.jpg
ad21ad45
VP
125@end example
126
3c88ea24
BC
127The @file{movie.mpg} used as input will be converted to
128@file{movie1.jpg}, @file{movie2.jpg}, etc...
ad21ad45
VP
129
130Instead of relying on file format self-recognition, you may also use
131@table @option
708060d7
LB
132@item -c:v ppm
133@item -c:v png
134@item -c:v mjpeg
ad21ad45
VP
135@end table
136to force the encoding.
137
138Applying that to the previous example:
139@example
708060d7 140 avconv -i movie.mpg -f image2 -c:v mjpeg menu%d.jpg
ad21ad45
VP
141@end example
142
143Beware that there is no "jpeg" codec. Use "mjpeg" instead.
144
5965e1a9 145@section Why do I see a slight quality degradation with multithreaded MPEG* encoding?
f2fe8752
RS
146
147For multithreaded MPEG* encoding, the encoded slices must be independent,
cacf7199
MM
148otherwise thread n would practically have to wait for n-1 to finish, so it's
149quite logical that there is a small reduction of quality. This is not a bug.
f2fe8752 150
5965e1a9 151@section How can I read from the standard input or write to the standard output?
47d944d2 152
831ec935 153Use @file{-} as file name.
47d944d2 154
9ba42958 155@section -f jpeg doesn't work.
fc3e9202 156
a9d21e78 157Try '-f image2 test%d.jpg'.
fc3e9202 158
cacf7199 159@section Why can I not change the framerate?
73468318 160
9ba42958 161Some codecs, like MPEG-1/2, only allow a small number of fixed framerates.
708060d7 162Choose a different codec with the -c:v command line option.
73468318 163
708060d7 164@section How do I encode Xvid or DivX video with avconv?
f62e9435 165
842eabc5 166Both Xvid and DivX (version 4+) are implementations of the ISO MPEG-4
f62e9435 167standard (note that there are many other coding formats that use this
708060d7 168same standard). Thus, use '-c:v mpeg4' to encode in these formats. The
c9a08db9 169default fourcc stored in an MPEG-4-coded file will be 'FMP4'. If you want
115329f1
DB
170a different fourcc, use the '-vtag' option. E.g., '-vtag xvid' will
171force the fourcc 'xvid' to be stored as the video fourcc rather than the
f62e9435
MM
172default.
173
16ab894e 174@section Which are good parameters for encoding high quality MPEG-4?
c62997a5 175
4c74d166 176'-mbd rd -flags +mv4+aic -trellis 2 -cmp 2 -subcmp 2 -g 300 -pass 1/2',
16ab894e 177things to try: '-bf 2', '-flags qprd', '-flags mv0', '-flags skiprd'.
c62997a5 178
16ab894e 179@section Which are good parameters for encoding high quality MPEG-1/MPEG-2?
c62997a5 180
cd0e37d3 181'-mbd rd -trellis 2 -cmp 2 -subcmp 2 -g 100 -pass 1/2'
16ab894e
DB
182but beware the '-g 100' might cause problems with some decoders.
183Things to try: '-bf 2', '-flags qprd', '-flags mv0', '-flags skiprd.
c62997a5 184
708060d7 185@section Interlaced video looks very bad when encoded with avconv, what is wrong?
c62997a5 186
16ab894e
DB
187You should use '-flags +ilme+ildct' and maybe '-flags +alt' for interlaced
188material, and try '-top 0/1' if the result looks really messed-up.
c62997a5 189
99f6278e 190@section How can I read DirectShow files?
2c29781d 191
f8a45fa1 192If you have built Libav with @code{./configure --enable-avisynth}
99f6278e
DB
193(only possible on MinGW/Cygwin platforms),
194then you may use any file that DirectShow can read as input.
2c29781d
VP
195
196Just create an "input.avs" text file with this single line ...
197@example
198 DirectShowSource("C:\path to your file\yourfile.asf")
199@end example
708060d7 200... and then feed that text file to avconv:
2c29781d 201@example
708060d7 202 avconv -i input.avs
2c29781d
VP
203@end example
204
2cb6dec6
DB
205For ANY other help on Avisynth, please visit the
206@uref{http://www.avisynth.org/, Avisynth homepage}.
2c29781d 207
f7994861
VP
208@section How can I join video files?
209
5449190f 210A few multimedia containers (MPEG-1, MPEG-2 PS, DV) allow to join video files by
f7994861
VP
211merely concatenating them.
212
213Hence you may concatenate your multimedia files by first transcoding them to
214these privileged formats, then using the humble @code{cat} command (or the
5449190f 215equally humble @code{copy} under Windows), and finally transcoding back to your
f7994861
VP
216format of choice.
217
218@example
708060d7
LB
219avconv -i input1.avi -same_quant intermediate1.mpg
220avconv -i input2.avi -same_quant intermediate2.mpg
f7994861 221cat intermediate1.mpg intermediate2.mpg > intermediate_all.mpg
708060d7 222avconv -i intermediate_all.mpg -same_quant output.avi
f7994861
VP
223@end example
224
708060d7 225Notice that you should either use @code{-same_quant} or set a reasonably high
f7994861
VP
226bitrate for your intermediate and output files, if you want to preserve
227video quality.
228
5449190f 229Also notice that you may avoid the huge intermediate files by taking advantage
f7994861
VP
230of named pipes, should your platform support it:
231
232@example
233mkfifo intermediate1.mpg
234mkfifo intermediate2.mpg
708060d7
LB
235avconv -i input1.avi -same_quant -y intermediate1.mpg < /dev/null &
236avconv -i input2.avi -same_quant -y intermediate2.mpg < /dev/null &
f7994861 237cat intermediate1.mpg intermediate2.mpg |\
708060d7 238avconv -f mpeg -i - -same_quant -c:v mpeg4 -acodec libmp3lame output.avi
f7994861
VP
239@end example
240
241Similarly, the yuv4mpegpipe format, and the raw video, raw audio codecs also
242allow concatenation, and the transcoding step is almost lossless.
76597127
JVS
243When using multiple yuv4mpegpipe(s), the first line needs to be discarded
244from all but the first stream. This can be accomplished by piping through
245@code{tail} as seen below. Note that when piping through @code{tail} you
246must use command grouping, @code{@{ ;@}}, to background properly.
247
f7994861
VP
248For example, let's say we want to join two FLV files into an output.flv file:
249
250@example
251mkfifo temp1.a
252mkfifo temp1.v
253mkfifo temp2.a
254mkfifo temp2.v
255mkfifo all.a
256mkfifo all.v
708060d7
LB
257avconv -i input1.flv -vn -f u16le -acodec pcm_s16le -ac 2 -ar 44100 - > temp1.a < /dev/null &
258avconv -i input2.flv -vn -f u16le -acodec pcm_s16le -ac 2 -ar 44100 - > temp2.a < /dev/null &
259avconv -i input1.flv -an -f yuv4mpegpipe - > temp1.v < /dev/null &
260@{ avconv -i input2.flv -an -f yuv4mpegpipe - < /dev/null | tail -n +2 > temp2.v ; @} &
f7994861
VP
261cat temp1.a temp2.a > all.a &
262cat temp1.v temp2.v > all.v &
708060d7 263avconv -f u16le -acodec pcm_s16le -ac 2 -ar 44100 -i all.a \
f7994861 264 -f yuv4mpegpipe -i all.v \
708060d7 265 -same_quant -y output.flv
f7994861
VP
266rm temp[12].[av] all.[av]
267@end example
268
2bbb4720
AK
269@section -profile option fails when encoding H.264 video with AAC audio
270
271@command{avconv} prints an error like
272
273@example
274Undefined constant or missing '(' in 'baseline'
275Unable to parse option value "baseline"
276Error setting option profile to value baseline.
277@end example
278
279Short answer: write @option{-profile:v} instead of @option{-profile}.
280
281Long answer: this happens because the @option{-profile} option can apply to both
282video and audio. Specifically the AAC encoder also defines some profiles, none
283of which are named @var{baseline}.
284
285The solution is to apply the @option{-profile} option to the video stream only
286by using @url{http://libav.org/avconv.html#Stream-specifiers-1, Stream specifiers}.
287Appending @code{:v} to it will do exactly that.
288
7ff56c72
FB
289@chapter Development
290
f8a45fa1 291@section Are there examples illustrating how to use the Libav libraries, particularly libavcodec and libavformat?
a93b9dba 292
f8a45fa1 293Yes. Read the Developers Guide of the Libav documentation. Alternatively,
115329f1 294examine the source code for one of the many open source projects that
f8a45fa1 295already incorporate Libav at (@url{projects.html}).
a93b9dba 296
5965e1a9 297@section Can you support my C compiler XXX?
7ff56c72 298
e867d9b9
DB
299It depends. If your compiler is C99-compliant, then patches to support
300it are likely to be welcome if they do not pollute the source code
301with @code{#ifdef}s related to the compiler.
7ff56c72 302
a9d5a448 303@section Is Microsoft Visual C++ supported?
2f0b8fbb 304
a9d5a448 305No. Microsoft Visual C++ is not compliant to the C99 standard and does
f8a45fa1 306not - among other things - support the inline assembly used in Libav.
19671d3f 307If you wish to use MSVC++ for your
c1989552 308project then you can link the MSVC++ code with libav* as long as
2f0b8fbb 309you compile the latter with a working C compiler. For more information, see
f8a45fa1 310the @emph{Microsoft Visual C++ compatibility} section in the Libav
c1989552 311documentation.
2f0b8fbb 312
f8a45fa1 313There have been efforts to make Libav compatible with MSVC++ in the
2f0b8fbb 314past. However, they have all been rejected as too intrusive, especially
a9d5a448 315since MinGW does the job adequately. None of the core developers
c1989552 316work with MSVC++ and thus this item is low priority. Should you find
2f0b8fbb
DB
317the silver bullet that solves this problem, feel free to shoot it at us.
318
19671d3f
RP
319We strongly recommend you to move over from MSVC++ to MinGW tools.
320
708060d7 321@section Can I use Libav under Windows?
7ff56c72 322
f8a45fa1
JG
323Yes, but the Cygwin or MinGW tools @emph{must} be used to compile Libav.
324Read the @emph{Windows} section in the Libav documentation to find more
c1989552 325information.
7ff56c72 326
5965e1a9 327@section Can you add automake, libtool or autoconf support?
7ff56c72 328
e867d9b9 329No. These tools are too bloated and they complicate the build.
7ff56c72 330
708060d7 331@section Why not rewrite Libav in object-oriented C++?
fbf33e4f 332
f8a45fa1 333Libav is already organized in a highly modular manner and does not need to
115329f1 334be rewritten in a formal object language. Further, many of the developers
cacf7199 335favor straight C; it works for them. For more arguments on this matter,
2cb6dec6 336read @uref{http://www.tux.org/lkml/#s15, "Programming Religion"}.
cacf7199 337
5965e1a9 338@section I do not like the LGPL, can I contribute code under the GPL instead?
61a1e081 339
e180129f 340Yes, as long as the code is optional and can easily and cleanly be placed
b250f9c6 341under #if CONFIG_GPL without breaking anything. So for example a new codec
831ec935 342or filter would be OK under GPL while a bug fix to LGPL code would not.
61a1e081 343
708060d7 344@section I'm using Libav from within my C++ application but the linker complains about missing symbols which seem to be available.
4cb3aa09 345
f8a45fa1 346Libav is a pure C project, so to use the libraries within your C++ application
4cb3aa09 347you need to explicitly state that you are using a C library. You can do this by
f8a45fa1 348encompassing your Libav includes using @code{extern "C"}.
4cb3aa09
PI
349
350See @url{http://www.parashift.com/c++-faq-lite/mixing-c-and-cpp.html#faq-32.3}
351
d162994a
LB
352@section I'm using libavutil from within my C++ application but the compiler complains about 'UINT64_C' was not declared in this scope
353
354Libav is a pure C project using C99 math features, in order to enable C++
355to use them you have to append -D__STDC_CONSTANT_MACROS to your CXXFLAGS
356
2cab6401 357@section I have a file in memory / a API different from *open/*read/ libc how do I use it with libavformat?
f994f61e 358
e7f6c252 359You have to implement a URLProtocol, see @file{libavformat/file.c} in
f8a45fa1 360Libav and @file{libmpdemux/demux_lavf.c} in MPlayer sources.
f994f61e 361
8b1a2686
DB
362@section Why is @code{make fate} not running all tests?
363
364Make sure you have the fate-suite samples and the @code{SAMPLES} Make variable
365or @code{FATE_SAMPLES} environment variable or the @code{--samples}
366@command{configure} option is set to the right path.
367
368@section Why is @code{make fate} not finding the samples?
369
370Do you happen to have a @code{~} character in the samples path to indicate a
371home directory? The value is used in ways where the shell cannot expand it,
372causing FATE to not find files. Just replace @code{~} by the full path.
373
7ff56c72 374@bye