merge

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

4 files changed, 551 insertions, 0 deletions

diff --git a/doc/README.tech b/doc/README.tech
new file mode 100644
index 0000000000..e110b3a960
--- /dev/null
+++ b/doc/README.tech
@@ -0,0 +1,46 @@
+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.
+
+I also plan to improve the bitrate control which is too simplistic.
+
+Audio:
+-----
+
+- I rewrote the mpeg audio layer 2 compatible encoder 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.
+
+- I rewrote the AC3 audio encoder 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.
diff --git a/doc/TODO b/doc/TODO
new file mode 100644
index 0000000000..09c5f2b6c2
--- /dev/null
+++ b/doc/TODO
@@ -0,0 +1,63 @@
+ffmpeg TODO list:
+----------------
+
+(in approximate decreasing priority order)
+
+Planned in next release:
+
+(DONE) - apply header fixes
+(DONE) - mpeg audio decoder.
+(DONE) - fix decode/encode codec string.
+(DONE) - fix EINTR error if VIDIOCSYNC.
+(DONE) - add CONFIG system. 
+(DONE) - merge mplayer mmx accel.
+(DONE) - fix emms bug.
+(DONE) - add I263 handling
+(DONE) - add RV10 decoding.
+(DONE) - add true pgm support.
+(DONE) - msmpeg4 0x18 fix.
+- add qscale out.
+- add format autodetect with content (for example to distinguish
+  mpegvideo/mpegmux).
+- add external alloc for libavcodec (avifile request).
+- fix -sameq in grabbing
+- find a solution to clear feed1.ffm if format change.
+- new grab architecture : use avformat instead of audio: and video:
+  protocol.
+- correct PTS handling to sync audio and video.
+- fix 0 size picture in AVIs = skip picture
+
+BUGS:
+
+- fix audio/video synchro (including real player synchro bugs)
+
+- Improve the bit rate control for video codecs.
+
+- see ov511.o YUV problem (420 instead of 420P).
+
+- fix file caching pb in windows (add correct headers)
+
+- add low pass filter to suppress noise coming from cheap TV cards.
+
+- test/debug audio in flash format
+
+- sort out ASF streaming pbs.
+
+- Improve psycho acoustic model for AC3 & mpeg audio.
+
+FEATURES:
+
+- add MPEG4 in mpegmux support.
+
+- add RTP / multicast layer.
+
+- demux streams for CCTV : N streams in one stream. Add option to
+  generate multiple streams.
+
+- add disconnect user option in stat.html.
+
+- deny & allow + password in ffserver.
+
+- graphical user interface.
+
+- animated gif as output format
diff --git a/doc/ffmpeg.txt b/doc/ffmpeg.txt
new file mode 100644
index 0000000000..7352a662e2
--- /dev/null
+++ b/doc/ffmpeg.txt
@@ -0,0 +1,181 @@
+*************** 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 paramters, 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:
+
+  ffmpeg -i /tmp/test%d.Y /tmp/out.mpg 
+
+If 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 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.
+
+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:
+
+-h                  show help
+-formats            show available formats, codecs and protocols
+-L                  print the LICENSE
+-i filename         input file name
+-y                  overwrite output files
+-t duration         set recording time in seconds
+-f format           set encoding format                  [guessed]
+-title string       set the title
+-author string      set the author
+-copyright string   set the copyright
+-comment string     set the comment
+
+* 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]
+
+* 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        [12]
+-intra              use only intra frames                [no]
+-qscale q           use fixed video quantiser scale (VBR)
+-c comment          set the comment string
+-vd device          set video4linux device name          [/dev/video]
+-vcodec codec       force audio codec
+-me method          set motion estimation method
+-ad device          set audio device name                [/dev/dsp]
+-acodec codec       force audio codec
+
+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.
diff --git a/doc/ffserver.conf b/doc/ffserver.conf
new file mode 100644
index 0000000000..311f48b817
--- /dev/null
+++ b/doc/ffserver.conf
@@ -0,0 +1,261 @@
+# Port on which the server is listening. You must select a different
+# port from your standard http web server if it is running on the same
+# computer.
+
+Port 8090
+
+# Address on which the server is bound. Only useful if you have
+# several network interfaces.
+
+BindAddress 0.0.0.0
+
+# Number of simultaneous requests that can be handled. Since FFServer
+# is very fast, this limit is determined mainly by your Internet
+# connection speed.
+
+MaxClients 1000
+
+# Access Log file (uses standard Apache log file format)
+# '-' is the standard output
+
+CustomLog -
+
+##################################################################
+# Definition of the live feeds. Each live feed contains one video
+# and/or audio sequence coming from an ffmpeg encoder or another
+# ffserver. This sequence may be encoded simultaneously with several
+# codecs at several resolutions.
+
+<Feed feed1.ffm>
+
+# You must use 'ffmpeg' to send a live feed to ffserver. In this
+# example, you can type:
+# 
+# ffmpeg http://localhost:8090/feed1.ffm
+
+# ffserver can also do time shifting. It means that it can stream any
+# previously recorded live stream. The request should contain:
+# "http://xxxx?date=[YYYY-MM-DDT][[HH:]MM:]SS[.m...]".You must specify
+# a path where the feed is stored on disk. You also specify the
+# maximum size of the feed (100M bytes here). Default:
+# File=/tmp/feed_name.ffm FileMaxSize=5M
+
+File /tmp/feed1.ffm
+FileMaxSize 50M
+
+</Feed>
+
+##################################################################
+# Now you can define each stream which will be generated from the
+# original audio and video stream. Each format has a filename (here
+# 'test128.mpg'). FFServer will send this stream when answering a
+# request containing this filename.
+
+<Stream test1.mpg>
+
+# coming from live feed 'feed1'
+Feed feed1.ffm
+
+# Format of the stream : you can choose among:
+# mpeg       : MPEG1 multiplexed video and audio
+# mpegvideo  : only MPEG1 video
+# mp2        : MPEG audio layer 2
+# mp3        : MPEG audio layer 3 (currently sent as layer 2)
+# rm         : Real Networks compatible stream. Multiplexed audio and video.
+# ra         : Real Networks compatible stream. Audio only.
+# mpjpeg     : Multipart JPEG (works with Netscape without any plugin)
+# jpeg       : Generate a single JPEG image.
+# asf        : ASF compatible stream (Windows Media Player format). Not finished yet.
+# swf        : Macromedia flash(tm) compatible stream
+# avi        : AVI format (open divx video, mpeg audio sound)
+# master     : special ffmpeg stream used to duplicate a server
+
+Format mpeg
+
+# Bitrate for the audio stream. Codecs usually support only a few different bitrates. 
+
+AudioBitRate 32
+
+# Number of audio channels : 1 = mono, 2 = stereo
+
+AudioChannels 1
+
+# Sampling frequency for audio. When using low bitrates, you should
+# lower this frequency to 22050 or 11025. The supported frequencies
+# depend on the selected audio codec.
+
+AudioSampleRate 44100
+
+# Bitrate for the video stream.
+VideoBitRate 64
+
+# Number of frames per second
+VideoFrameRate 3
+
+# Size of the video frame : WxH (default: 160x128)
+# W : width, H : height
+# The following abbreviation are defined : sqcif, qcif, cif, 4cif
+VideoSize    160x128
+
+# transmit only intra frames (useful for low bitrates) 
+VideoIntraOnly
+
+# If non intra only, an intra frame is transmitted every VideoGopSize
+# frames Video synchronization can only begin at an I frames.
+#VideoGopSize 12
+
+# Suppress audio
+#NoAudio
+
+# Suppress video
+#NoVideo
+
+</Stream>
+
+# second mpeg stream with high frame rate
+
+<Stream test2.mpg>
+Feed feed1.ffm
+Format mpegvideo
+VideoBitRate 128
+VideoFrameRate 25
+#VideoSize    352x240
+VideoGopSize 25
+</Stream>
+
+##################################################################
+# A stream coming from a file : you only need to set the input
+# filename and optionnally a new format. Supported conversions:
+#    avi -> asf
+#
+
+<Stream file.asf>
+
+#File "/tmp/file.avi"
+File "tmp/file.avi"
+# avi must be converted to asf to be streamed
+Format asf
+
+</Stream>
+
+# another file streaming
+<Stream file.mp3>
+
+File "tmp/file.mp3"
+
+</Stream>
+
+##################################################################
+# Another stream : Real with audio only at 32 kbits
+
+<Stream test.ra>
+
+Feed feed1.ffm
+Format rm
+AudioBitRate 32
+NoVideo
+
+</Stream>
+
+##################################################################
+# Another stream : Real with audio and video at 64 kbits
+
+<Stream test.rm>
+
+Feed feed1.ffm
+Format rm
+
+AudioBitRate 32
+VideoBitRate 20
+VideoFrameRate 2
+VideoIntraOnly
+
+</Stream>
+
+##################################################################
+# Another stream : Mpeg audio layer 2 at 64 kbits.
+
+<Stream test.mp2>
+
+Feed feed1.ffm
+Format mp2
+AudioBitRate 64
+AudioSampleRate 44100
+
+</Stream>
+
+<Stream test1.mp2>
+
+Feed feed1.ffm
+Format mp2
+AudioBitRate 32
+AudioSampleRate 16000
+
+</Stream>
+
+##################################################################
+# Another stream : Multipart JPEG
+
+<Stream test.mjpg>
+
+Feed feed1.ffm
+Format mpjpeg
+
+VideoFrameRate 2
+VideoIntraOnly
+
+</Stream>
+
+##################################################################
+# Another stream : Multipart JPEG
+
+<Stream test.jpg>
+
+Feed feed1.ffm
+Format jpeg
+
+# the parameters are choose here to take the same output as the
+# Multipart JPEG one.
+VideoFrameRate 2 
+VideoIntraOnly
+#VideoSize 352x240
+
+</Stream>
+
+##################################################################
+# Another stream : Flash
+
+<Stream test.swf>
+
+Feed feed1.ffm
+Format swf
+
+VideoFrameRate 2
+VideoIntraOnly
+
+</Stream>
+
+
+##################################################################
+# Another stream : ASF compatible
+
+<Stream test.asf>
+
+Feed feed1.ffm
+Format asf
+
+AudioBitRate 64
+AudioSampleRate 44100
+VideoFrameRate 2
+VideoIntraOnly
+
+</Stream>
+
+##################################################################
+# Special stream : server status
+
+<Stream stat.html>
+
+Format status
+
+</Stream>