diff options
Diffstat (limited to 'contrib/ffmpeg/doc/ffmpeg-doc.texi')
| -rw-r--r-- | contrib/ffmpeg/doc/ffmpeg-doc.texi | 159 |
1 files changed, 104 insertions, 55 deletions
diff --git a/contrib/ffmpeg/doc/ffmpeg-doc.texi b/contrib/ffmpeg/doc/ffmpeg-doc.texi index 2d814c0fb..e4e6430fd 100644 --- a/contrib/ffmpeg/doc/ffmpeg-doc.texi +++ b/contrib/ffmpeg/doc/ffmpeg-doc.texi @@ -26,11 +26,11 @@ video on the fly with a high quality polyphase filter. @c man begin EXAMPLES @section Video and Audio grabbing -FFmpeg can use a video4linux compatible video source and any Open Sound -System audio source: +FFmpeg can grab video and audio from devices given that you specify the input +format and device. @example -ffmpeg /tmp/out.mpg +ffmpeg -f audio_device -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg @end example Note that you must activate the right video source and channel before @@ -39,6 +39,24 @@ launching FFmpeg with any TV viewer such as xawtv have to set the audio recording levels correctly with a standard mixer. +@section X11 grabbing + +FFmpeg can grab the X11 display. + +@example +ffmpeg -f x11grab -i :0.0 /tmp/out.mpg +@end example + +0.0 is display.screen number of your X11 server, same as +the DISPLAY environment variable. + +@example +ffmpeg -f x11grab -i :0.0+10,20 /tmp/out.mpg +@end example + +0.0 is display.screen number of your X11 server, same as the DISPLAY environment +variable. 10 is the x-offset and 20 the y-offset for the grabbing. + @section Video and Audio file format conversion * FFmpeg can use any supported file format and protocol as input: @@ -99,7 +117,7 @@ Converts a.wav to MPEG audio at 22050Hz sample rate. mapping from input stream to output streams: @example -ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0 +ffmpeg -i /tmp/a.wav -ab 64k /tmp/a.mp2 -ab 128k /tmp/b.mp2 -map 0:0 -map 0:0 @end example Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. '-map @@ -109,7 +127,7 @@ stream, in the order of the definition of output streams. * You can transcode decrypted VOBs @example -ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800k -g 300 -bf 2 -acodec mp3 -ab 128 snatch.avi +ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800k -g 300 -bf 2 -acodec mp3 -ab 128k snatch.avi @end example This is a typical DVD ripping example; the input is a VOB file, the @@ -136,8 +154,6 @@ ffmpeg [[infile options][@option{-i} @var{infile}]]... @{[outfile options] @var{ @c man end @end example @c man begin DESCRIPTION -If no input file is given, audio/video grabbing is done. - As a general rule, options are applied to the next specified file. Therefore, order is important, and you can have the same option on the command line multiple times. Each occurrence is @@ -281,7 +297,7 @@ Set the number of video frames to record. @item -r fps Set frame rate (Hz value, fraction or abbreviation), (default = 25). @item -s size -Set frame size. The format is @samp{wxh} (default = 160x128). +Set frame size. The format is @samp{wxh} (ffserver default = 160x128, ffmpeg default = same as source). The following abbreviations are recognized: @table @samp @item sqcif @@ -544,7 +560,7 @@ Set the number of audio frames to record. @item -ar freq Set the audio sampling frequency (default = 44100 Hz). @item -ab bitrate -Set the audio bitrate in kbit/s (default = 64). +Set the audio bitrate in bit/s (default = 64k). @item -ac channels Set the number of audio channels (default = 1). @item -an @@ -562,7 +578,7 @@ can override the mapping using @code{-map} as usual. Example: @example -ffmpeg -i file.mpg -vcodec copy -acodec ac3 -ab 384 test.mpg -acodec mp2 -ab 192 -newaudio +ffmpeg -i file.mpg -vcodec copy -acodec ac3 -ab 384k test.mpg -acodec mp2 -ab 192k -newaudio @end example @item -alang code Set the ISO 639 language code (3 letters) of the current audio stream. @@ -591,20 +607,12 @@ Set the ISO 639 language code (3 letters) of the current subtitle stream. @section Audio/Video grab options @table @option -@item -vd device -sEt video grab device (e.g. @file{/dev/video0}). @item -vc channel Set video grab channel (DV1394 only). @item -tvstd standard Set television standard (NTSC, PAL (SECAM)). -@item -dv1394 -Set DV1394 grab. -@item -ad device -Set audio device (e.g. @file{/dev/dsp}). -@item -grab format -Request grabbing using. -@item -gd device -Set grab device. +@item -isync +Synchronize read on input. @end table @section Advanced options @@ -890,6 +898,11 @@ library: @tab Material eXchange Format SMPTE 377M, used by D-Cinema, broadcast industry. @item SEQ @tab @tab X @tab Tiertex .seq files used in the DOS CDROM version of the game Flashback. +@item DXA @tab @tab X +@tab This format is used in non-Windows version of Feeble Files game and +different game cutscenes repacked for use with ScummVM. +@item THP @tab @tab X +@tab Used on the Nintendo GameCube (video only) @end multitable @code{X} means that encoding (resp. decoding) is supported. @@ -950,11 +963,11 @@ following image formats are supported: @item Sorenson Video 3 @tab @tab X @tab fourcc: SVQ3 @item On2 VP3 @tab @tab X @tab still experimental @item On2 VP5 @tab @tab X @tab fourcc: VP50 -@item On2 VP6 @tab @tab X @tab fourcc: VP62 -@item Theora @tab @tab X @tab still experimental +@item On2 VP6 @tab @tab X @tab fourcc: VP60,VP61,VP62 +@item Theora @tab X @tab X @tab still experimental @item Intel Indeo 3 @tab @tab X @item FLV @tab X @tab X @tab Sorenson H.263 used in Flash -@item Flash Screen Video @tab @tab X @tab fourcc: FSV1 +@item Flash Screen Video @tab X @tab X @tab fourcc: FSV1 @item ATI VCR1 @tab @tab X @tab fourcc: VCR1 @item ATI VCR2 @tab @tab X @tab fourcc: VCR2 @item Cirrus Logic AccuPak @tab @tab X @tab fourcc: CLJR @@ -989,7 +1002,7 @@ following image formats are supported: @item Fraps FPS1 @tab @tab X @tab @item CamStudio @tab @tab X @tab fourcc: CSCD @item American Laser Games Video @tab @tab X @tab Used in games like Mad Dog McCree -@item ZMBV @tab @tab X @tab +@item ZMBV @tab X @tab X @tab Encoder works only on PAL8 @item AVS Video @tab @tab X @tab Video encoding used by the Creature Shock game. @item Smacker Video @tab @tab X @tab Video encoding used in Smacker. @item RTjpeg @tab @tab X @tab Video encoding used in NuppelVideo files. @@ -997,6 +1010,8 @@ following image formats are supported: @item VMware Video @tab @tab X @tab Codec used in videos captured by VMware. @item Cin Video @tab @tab X @tab Codec used in Delphine Software games. @item Tiertex Seq Video @tab @tab X @tab Codec used in DOS CDROM FlashBack game. +@item DXA Video @tab @tab X @tab Codec originally used in Feeble Files game. +@item AVID DNxHD @tab @tab X @tab aka SMPTE VC3 @end multitable @code{X} means that encoding (resp. decoding) is supported. @@ -1011,7 +1026,7 @@ following image formats are supported: @item AC3 @tab IX @tab IX @tab liba52 is used internally for decoding. @item Vorbis @tab X @tab X -@item WMA V1/V2 @tab @tab X +@item WMA V1/V2 @tab X @tab X @item AAC @tab X @tab X @tab Supported through the external library libfaac/libfaad. @item Microsoft ADPCM @tab X @tab X @@ -1072,6 +1087,9 @@ following image formats are supported: @item Cin Audio @tab @tab X @tab Codec used in Delphine Software games. @item Intel Music Coder @tab @tab X +@item Musepack @tab @tab X +@tab Only SV7 is supported +@item DT$ Coherent Audio @tab @tab X @end multitable @code{X} means that encoding (resp. decoding) is supported. @@ -1081,12 +1099,6 @@ performance on systems without hardware floating point support). @chapter Platform Specific information -@section Linux - -FFmpeg should be compiled with at least GCC 2.95.3. GCC 3.2 is the -preferred compiler now for FFmpeg. All future optimizations will depend on -features only found in GCC 3.2. - @section BSD BSD make will not build FFmpeg, you need to install and use GNU Make @@ -1094,6 +1106,10 @@ BSD make will not build FFmpeg, you need to install and use GNU Make @section Windows +To get help and instructions for using FFmpeg under Windows, check out +the FFmpeg Windows Help Forum at +@url{http://arrozcru.no-ip.org/ffmpeg/}. + @subsection Native Windows compilation @itemize @@ -1101,6 +1117,9 @@ BSD make will not build FFmpeg, you need to install and use GNU Make @url{http://www.mingw.org/}. You can find detailed installation instructions in the download section and the FAQ. +NOTE: Use at least bash 3.1. Older versions are known to be failing on the +configure script. + @item If you want to test the FFplay, also download the MinGW development library of SDL 1.2.x (@file{SDL-devel-1.2.x-mingw32.tar.gz}) from @@ -1120,7 +1139,7 @@ suffices. If you have problems using SDL, verify that @file{sdl-config} can be launched from the MSYS command line. @item You can install FFmpeg in @file{Program Files/FFmpeg} by typing -@file{make install}. Don't forget to copy @file{SDL.dll} to the place +@file{make install}. Do not forget to copy @file{SDL.dll} to the place you launch @file{ffplay} from. @end itemize @@ -1166,7 +1185,7 @@ so they can be used with Visual C++: @enumerate -@item Install Visual C++ (if you haven't done so already). +@item Install Visual C++ (if you have not done so already). @item Install MinGW and MSYS as described above. @@ -1190,7 +1209,7 @@ create Visual-C++-compatible import libraries. @item Type the command @code{./configure --enable-shared --disable-static --enable-memalign-hack} -to configure and, if that didn't produce any errors, +to configure and, if that did not produce any errors, type @code{make} to build FFmpeg. @item The subdirectories @file{libavformat}, @file{libavcodec}, and @@ -1212,8 +1231,8 @@ Application Wizard, uncheck the "Precompiled headers" option. @item Write the source code for your application, or, for testing, just copy the code from an existing sample application into the source file that Visual C++ has already created for you. (Note that your source -filehas to have a @code{.cpp} extension; otherwise, Visual C++ won't -compile the FFmpeg headers correctly because in C mode, it doesn't +filehas to have a @code{.cpp} extension; otherwise, Visual C++ will not +compile the FFmpeg headers correctly because in C mode, it does not recognize the @code{inline} keyword.) For example, you can copy @file{output_example.c} from the FFmpeg distribution (but you will have to make minor modifications so the code will compile under @@ -1246,7 +1265,7 @@ set to "Multi-threaded DLL". the application. Hopefully, it should compile and run cleanly. If you used @file{output_example.c} as your sample application, you will get a few compiler errors, but they are easy to fix. The first type of error -occurs because Visual C++ doesn't allow an @code{int} to be converted to +occurs because Visual C++ does not allow an @code{int} to be converted to an @code{enum} without a cast. To solve the problem, insert the required casts (this error occurs once for a @code{CodecID} and once for a @code{CodecType}). The second type of error occurs because C++ requires @@ -1269,7 +1288,7 @@ You must use the MinGW cross compilation tools available at Then configure FFmpeg with the following options: @example -./configure --enable-mingw32 --cross-prefix=i386-mingw32msvc- +./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc- @end example (you can change the cross-prefix according to the prefix chosen for the MinGW tools). @@ -1311,7 +1330,7 @@ and/or SDL, xvid, faac, faad2 packages from Cygwin Ports, @subsection Crosscompilation for Windows under Cygwin -With Cygwin you can create Windows binaries that don't need the cygwin1.dll. +With Cygwin you can create Windows binaries that do not need the cygwin1.dll. Just install your Cygwin as explained before, plus these additional "Devel" packages: @@ -1323,12 +1342,12 @@ and add some special flags to your configure invocation. For a static build run @example -./configure --enable-mingw32 --enable-memalign-hack --enable-static --disable-shared --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin +./configure --target-os=mingw32 --enable-memalign-hack --enable-static --disable-shared --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin @end example and for a build with shared libraries @example -./configure --enable-mingw32 --enable-memalign-hack --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin +./configure --target-os=mingw32 --enable-memalign-hack --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin @end example @section BeOS @@ -1342,7 +1361,7 @@ Old stuff: François Revol - revol at free dot fr - April 2002 The configure script should guess the configuration itself, -however I still didn't test building on the net_server version of BeOS. +however I still did not test building on the net_server version of BeOS. FFserver is broken (needs poll() implementation). @@ -1392,14 +1411,14 @@ designated struct initializers (@samp{struct s x = @{ .i = 17 @};}) compound literals (@samp{x = (struct s) @{ 17, 23 @};}) @end itemize -These features are supported by all compilers we care about, so we won't -accept patches to remove their use unless they absolutely don't impair +These features are supported by all compilers we care about, so we will not +accept patches to remove their use unless they absolutely do not impair clarity and performance. All code must compile with GCC 2.95 and GCC 3.3. Currently, FFmpeg also compiles with several other compilers, such as the Compaq ccc compiler or Sun Studio 9, and we would like to keep it that way unless it would -be exceedingly involved. To ensure compatibility, please don't use any +be exceedingly involved. To ensure compatibility, please do not use any additional C99 features or GCC extensions. Especially watch out for: @itemize @bullet @item @@ -1424,7 +1443,7 @@ bugs). Comments: Use the JavaDoc/Doxygen format (see examples below) so that code documentation can be generated automatically. All nontrivial functions should have a comment -above them explaining what the function does, even if it's just one sentence. +above them explaining what the function does, even if it is just one sentence. All structures and their member variables should be documented, too. @example /** @@ -1470,13 +1489,19 @@ please use av_log() instead. (#ifdef etc) by default so it does not interfere with other developers' work. @item - You don't have to over-test things. If it works for you, and you think it + You do not have to over-test things. If it works for you, and you think it should work for others, then commit. If your code has problems (portability, triggers compiler bugs, unusual environment etc) they will be reported and eventually fixed. @item Do not commit unrelated changes together, split them into self-contained - pieces. + pieces. Also do not forget that if part B depends on part A, but A does not + depend on B, then A can and should be committed first and separate from B. + Keeping changes well split into self-contained parts makes reviewing and + understanding them on the commit log mailing list easier. This also helps + in case of debugging later on. + Also if you have doubts about splitting or not splitting, do not hesitate to + ask/disscuss it on the developer mailing list. @item Do not change behavior of the program (renaming options etc) without first discussing it on the ffmpeg-devel mailing list. Do not remove @@ -1497,12 +1522,12 @@ please use av_log() instead. developer has his own indentation style, you should not change it. Of course if you (re)write something, you can use your own style, even though we would prefer if the indentation throughout FFmpeg was consistent (Many projects - force a given indentation style - we don't.). If you really need to make + force a given indentation style - we do not.). If you really need to make indentation changes (try to avoid this), separate them strictly from real changes. NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code, - then either do NOT change the indentation of the inner part within (don't + then either do NOT change the indentation of the inner part within (do not move it to the right)! or do so in a separate commit @item Always fill out the commit log message. Describe in a few lines what you @@ -1518,7 +1543,7 @@ please use av_log() instead. Do NOT commit to code actively maintained by others without permission. Send a patch to ffmpeg-devel instead. If noone answers within a reasonable timeframe (12h for build failures and security fixes, 3 days small changes, - 1 week for big patches) then commit your patch if you think it's OK. + 1 week for big patches) then commit your patch if you think it is OK. Also note, the maintainer can simply ask for more time to review! @item Subscribe to the ffmpeg-cvslog mailing list. The diffs of all commits @@ -1530,6 +1555,9 @@ please use av_log() instead. unsure how best to do this, send a patch to ffmpeg-devel, the documentation maintainer(s) will review and commit your stuff. @item + Try to keep important discussions and requests (also) on the public + developer mailing list, so that all developers can benefit from them. +@item Never write to unallocated memory, never write over the end of arrays, always check values read from some untrusted source before using them as array index or other risky things. @@ -1549,6 +1577,9 @@ please use av_log() instead. component of the @file{libavcodec} version number appropriately. If it has a fourcc, add it to @file{libavformat/avienc.c}, even if it is only a decoder. +@item + Do not change code to hide warnings without ensuring that the underlying + logic is correct and thus the warning was inappropriate. @end enumerate We think our rules are not too hard. If you have comments, contact us. @@ -1557,7 +1588,7 @@ Note, these rules are mostly borrowed from the MPlayer project. @section Submitting patches -First, (@pxref{Coding Rules}) above if you didn't yet. +First, (@pxref{Coding Rules}) above if you did not yet. When you submit your patch, try to send a unified diff (diff '-up' option). I cannot read other diffs :-) @@ -1570,7 +1601,7 @@ Run the regression tests before submitting a patch so that you can verify that there are no big problems. Patches should be posted as base64 encoded attachments (or any other -encoding which ensures that the patch won't be trashed during +encoding which ensures that the patch will not be trashed during transmission) to the ffmpeg-devel mailing list, see @url{http://lists.mplayerhq.hu/mailman/listinfo/ffmpeg-devel} @@ -1578,8 +1609,26 @@ It also helps quite a bit if you tell us what the patch does (for example 'replaces lrint by lrintf'), and why (for example '*BSD isn't C99 compliant and has no lrint()') -We reply to all submitted patches and either apply or reject with some -explanation why, but sometimes we are quite busy so it can take a week or two. +@section Patch review process + +All patches posted to ffmpeg-devel will be reviewed, unless they contain a +clear note that the patch is not for SVN. +Reviews and comments will be posted as replies to the patch on the +mailing list. The patch submitter then has to take care of every comment, +that can be by resubmitting a changed patch or by disscussion. Resubmitted +patches will themselves be reviewed like any other patch. If at some point +a patch passes review with no comments then it is approved, that can for +simple and small patches happen immediately while large patches will generally +have to be changed and reviewed many times before they are approved. +After a patch is approved it will be committed to the repository. + +We will review all submitted patches, but sometimes we are quite busy so +especially for large patches this can take several weeks. + +When resubmitting patches, please do not make any significant changes +not related to the comments received during review. Such patches will +be rejected. Instead, submit significant changes or new features as +separate patches. @section Regression tests |