new texinfo documentation - HTML version also included

Originally committed as revision 1085 to svn://svn.ffmpeg.org/ffmpeg/trunk

doc/Makefile

+all: ffmpeg-doc.html
+
+%.html: %.texi
+	texi2html -monolithic -number $<

doc/README.dev

-1) API
-------
-
-* libavcodec is the library containing the codecs (both encoding and
-  decoding). See libavcodec/apiexample.c to see how to use it.
-
-* libav is the library containing the file formats handling (mux and
-  demux code for several formats). (no example yet, the API is likely
-  to evolve).
-
-2) Integrating libavcodec or libav in your GPL'ed program
----------------------------------------------------------
-
-You can integrate all the source code of the libraries to link them
-statically to avoid any version problem. All you need is to provide a
-'config.mak' and a 'config.h' in the parent directory. See the defines
-generated by ./configure to understand what is needed.
-
-3) Coding Rules
----------------
-
-ffmpeg is programmed in ANSI C language. GCC extensions are
-tolerated. Indent size is 4. The TAB character should not be used.
-
-The presentation is the one specified by 'indent -i4 -kr'.
-
-Main priority in ffmpeg is simplicity and small code size (=less
-bugs).
-
-Comments: for functions visible from other modules, use the JavaDoc
-format (see examples in libav/utils.c) so that a documentation can be
-generated automatically.
-
-4) Submitting patches
----------------------
-
-When you submit your patch, try to send a unified diff (diff '-u'
-option). I cannot read other diffs :-)
-
-Run the regression tests before submitting a patch so that you can
-verify that there is no big problems.
-
-Except if your patch is really big and adds an important feature, by
-submitting it to me, you accept implicitely to put it under my
-copyright. I prefer to do this to avoid potential problems if
-licensing of ffmpeg changes.
-
-Patches should be posted as base64 encoded attachments (or any other
-encoding which ensures that the patch wont be trashed during 
-transmission) to the ffmpeg-devel mailinglist, see 
-http://lists.sourceforge.net/lists/listinfo/ffmpeg-devel
-
-5) Regression tests
--------------------
-
-Before submitting a patch (or commiting with CVS), you should at least
-test that you did not break anything.
-
-The regression test build a synthetic video stream and a synthetic
-audio stream. Then there are encoded then decoded with all codecs or
-formats. The CRC (or MD5) of each generated file is recorded in a
-result file. Then a 'diff' is launched with the reference results and
-the result file.
-
-Run 'make test' to test all the codecs.
-
-Run 'make libavtest' to test all the codecs.
-
-[Of course, some patches may change the regression tests results. In
-this case, the regression tests reference results shall be modified
-accordingly].

doc/README.tech

-Technical notes:
----------------
-
-Video:
------
-
-- The decision intra/predicted macroblock is the algorithm suggested
-  by the mpeg 1 specification.
-
-- only Huffman based H263 is supported, mainly because of patent
-  issues.
-
-- MPEG4 is supported, as an extension of the H263 encoder. MPEG4 DC
-  prediction is used, but not AC prediction. Specific VLC are used for
-  intra pictures. The output format is compatible with Open DIVX
-  version 47.
-
-- MJPEG is supported, but in the current version the huffman tables
-  are not optimized. It could be interesting to add this feature for
-  the flash format.
-
-- To increase speed, only motion vectors (0,0) are tested for real
-  time compression. NEW: now motion compensation is done with several
-  methods : none, full, log, and phods. The code is mmx/sse optimized.
-
-- In high quality mode, full search is used for motion
-  vectors. Currently, only fcode = 1 is used for both H263/MPEG1. Half
-  pel vectors are used.
-
-Audio:
------
-
-- The mpeg audio layer 2 compatible encoder was rewritten from
-  scratch. It is one of the simplest encoder you can imagine (800
-  lines of C code !). It is also one of the fastest because of its
-  simplicity. There are still some problems of overflow. A minimal
-  psycho acoustic model could be added. Currently, stereo is
-  supported, but not joint stereo.
-
-- The AC3 audio encoder was rewritten from scratch. It is fairly
-  naive, but the result are quiet interesting at 64 kbit/s. It
-  includes extensions for low sampling rates used in some Internet
-  formats. Differential and coupled stereo is not handled. Stereo
-  channels are simply handled as two mono channels.
-
-- The mpeg audio layer 3 decoder was rewritten from scratch. It uses
-  only integers and can be 16 bit precision for the synthesis filter
-  at the expense of a slight precision loss. A slower bit exact mode
-  is available too for compliance testing.

doc/TODO

@@ -4,23 +4,20 @@ ffmpeg TODO list:
 (in approximate decreasing priority order)
 
 Short term fixes:
-- mpeg audio fix
-- ffserver fix
-- fix stream selection (aka map) syntax. Start stream numbers at 1 in
-  listing. Find a syntax for stream ids (such as TS pids).
+- AV sync fix
+- put ffserver patches
 - reconstruct mpeg header frame rate in telecine case so that we do
   not need to infer the real rate if it is not possible.
-- remove unused DCT code.
-- AV sync fix
 - RTP/RTSP streaming support in ffserver and in libav
 - minimal support of video in ffplay
 
 Planned in next releases:
 
+- remove unused DCT code.
+- fix stream selection (aka map) syntax. Start stream numbers at 1 in
+  listing. Find a syntax for stream ids (such as TS pids).
 - add DV codec/format support
 - fix bugs when stream begins with a P/B frame 
-- fix ffserver (partially done)
-- add raw h263 decoding support, see vivo streams (partially done)
 - add qscale out.
 - fix -sameq in grabbing
 - add vivo format support (may need long term prediction support)

doc/ffmpeg.txt

-*************** FFMPEG soft VCR documentation *****************
-
-0) Introduction
----------------
-
-  FFmpeg is a very fast video and audio encoder. It can grab from
-  files or from a live audio/video source. 
-  
-  The command line interface is designed to be intuitive, in the sense
-  that ffmpeg tries to figure out all the parameters, when
-  possible. You have usually to give only the target bitrate you want.
-
-  FFmpeg can also convert from any sample rate to any other, and
-  resize video on the fly with a high quality polyphase filter.
-
-1) Video and Audio grabbing
----------------------------
-
-* FFmpeg can use a video4linux compatible video source and any Open
-  Sound System audio source:
-
-  ffmpeg /tmp/out.mpg 
-
-  Note that you must activate the right video source and channel
-  before launching ffmpeg. You can use any TV viewer such as xawtv by
-  Gerd Knorr which I find very good. You must also set correctly the
-  audio recording levels with a standard mixer.
-
-2) Video and Audio file format convertion
------------------------------------------
-
-* ffmpeg can use any supported file format and protocol as input: 
-
-Examples:
-
-* You can input from YUV files:
-
-  ffmpeg -i /tmp/test%d.Y /tmp/out.mpg 
-
-  It will use the files: 
-       /tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
-       /tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
-
-  The Y files use twice the resolution of the U and V files. They are
-  raw files, without header. They can be generated by all decent video
-  decoders. You must specify the size of the image with the '-s' option
-  if ffmpeg cannot guess it.
-
-* You can input from a RAW YUV420P file:
-
-  ffmpeg -i /tmp/test.yuv /tmp/out.avi
-
-  The RAW YUV420P is a file containing RAW YUV planar, for each frame first
-  come the Y plane followed by U and V planes, which are half vertical and
-  horizontal resolution.
-
-* You can output to a RAW YUV420P file:
-
-  ffmpeg -i mydivx.avi -o hugefile.yuv
-
-* You can set several input files and output files:
-
-  ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
-
-  Convert the audio file a.wav and the raw yuv video file a.yuv
-  to mpeg file a.mpg
-
-* You can also do audio and video convertions at the same time:
-
-  ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
-
-  Convert the sample rate of a.wav to 22050 Hz and encode it to MPEG audio.
-
-* You can encode to several formats at the same time and define a
-  mapping from input stream to output streams:
-
-  ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
-
-  Convert a.wav to a.mp2 at 64 kbits and b.mp2 at 128 kbits. '-map
-  file:index' specify which input stream is used for each output
-  stream, in the order of the definition of output streams.
-
-* You can transcode decrypted VOBs
-
-  ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800 -g 300 -bf 2 -acodec
-  mp3 -ab 128 snatch.avi
-
-  This is a typicall DVD ripper example, input from a VOB file, output to
-  an AVI file with MPEG-4 video and MP3 audio, note that in this command we
-  use B frames so the MPEG-4 stream is DivX5 compatible, GOP size is 300
-  that means an INTRA frame every 10 seconds for 29.97 fps input video.
-  Also the audio stream is MP3 encoded so you need LAME support which is
-  enabled using '--enable-mp3lame' when configuring.
-  The mapping is particullary usefull for DVD transcoding to get the desired
-  audio language.
-
-  NOTE: to see the supported input formats, use 'ffmpeg -formats'.
-
-2) Invocation
--------------
-
-* The generic syntax is :
-
-  ffmpeg [[options][-i input_file]]... {[options] output_file}...
-
-  If no input file is given, audio/video grabbing is done.
-
-  As a general rule, options are applied to the next specified
-  file. For example, if you give the '-b 64' option, it sets the video
-  bitrate of the next file. Format option may be needed for raw input
-  files.
-
-  By default, ffmpeg tries to convert as losslessly as possible: it
-  uses the same audio and video parameter fors the outputs as the one
-  specified for the inputs.
-
-* Main options are:
-
--L                  show license
--h                  show help
--formats            show available formats, codecs, protocols, ...
--f fmt              force format
--i filename         input file name
--y                  overwrite output files
--t duration         set the recording time
--title string       set the title
--author string      set the author
--copyright string   set the copyright
--comment string     set the comment
--b bitrate          set video bitrate (in kbit/s)
-
-* Video Options are:
-
--s size             set frame size                       [160x128]
--r fps              set frame rate                       [25]
--b bitrate          set the video bitrate in kbit/s      [200]
--vn                 disable video recording              [no]
--bt tolerance       set video bitrate tolerance (in kbit/s)
--sameq              use same video quality as source (implies VBR)
--ab bitrate         set audio bitrate (in kbit/s)
-
-* Audio Options are:
-
--ar freq     set the audio sampling freq          [44100]
--ab bitrate  set the audio bitrate in kbit/s      [64]
--ac channels set the number of audio channels     [1]
--an          disable audio recording              [no]
-
-* Advanced options are:
-
--map file:stream    set input stream mapping
--g gop_size         set the group of picture size
--intra              use only intra frames
--qscale q           use fixed video quantiser scale (VBR)
--qmin q             min video quantiser scale (VBR)
--qmax q             max video quantiser scale (VBR)
--qdiff q            max difference between the quantiser scale (VBR)
--qblur blur         video quantiser scale blur (VBR)
--qcomp compression  video quantiser scale compression (VBR)
--vd device          set video device
--vcodec codec       force video codec
--me method          set motion estimation method
--bf frames          use 'frames' B frames (only MPEG-4)
--hq                 activate high quality settings
--4mv                use four motion vector by macroblock (only MPEG-4)
--ad device          set audio device
--acodec codec       force audio codec
--deinterlace        deinterlace pictures
--benchmark          add timings for benchmarking
--hex                dump each input packet
--psnr               calculate PSNR of compressed frames
--vstats             dump video coding statistics to file
-
-The output file can be "-" to output to a pipe. This is only possible
-with mpeg1 and h263 formats. 
-
-3) Protocols
-
- ffmpeg handles also many protocols specified with the URL syntax.
-
- Use 'ffmpeg -formats' to have a list of the supported protocols.
-
- The protocol 'http:' is currently used only to communicate with
- ffserver (see the ffserver documentation). When ffmpeg will be a
- video player it will also be used for streaming :-)
-
-4) File formats and codecs
---------------------------
-
- Use 'ffmpeg -formats' to have a list of the supported output
- formats. Only some formats are handled as input, but it will improve
- in the next versions.
-
-5) Tips
--------
-
-- For streaming at very low bit rate application, use a low frame rate
-  and a small gop size. This is especially true for real video where
-  the Linux player does not seem to be very fast, so it can miss
-  frames. An example is:
-
-  ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
-
-- The parameter 'q' which is displayed while encoding is the current
-  quantizer. The value of 1 indicates that a very good quality could
-  be achieved. The value of 31 indicates the worst quality. If q=31
-  too often, it means that the encoder cannot compress enough to meet
-  your bit rate. You must either increase the bit rate, decrease the
-  frame rate or decrease the frame size.
-
-- If your computer is not fast enough, you can speed up the
-  compression at the expense of the compression ratio. You can use
-  '-me zero' to speed up motion estimation, and '-intra' to disable
-  completly motion estimation (you have only I frames, which means it
-  is about as good as JPEG compression).
-
-- To have very low bitrates in audio, reduce the sampling frequency
-  (down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
-
-- To have a constant quality (but a variable bitrate), use the option
-  '-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
-  quality).
-
-- When converting video files, you can use the '-sameq' option which
-  uses in the encoder the same quality factor than in the decoder. It
-  allows to be almost lossless in encoding.