Fix "ouput" typo and add a check.
[ffmpeg.git] / doc / ffmpeg.txt
index 7352a66..a028ca2 100644 (file)
-*************** 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.
+                                                                                                                                       :
+                                             ffmpeg.c                                                                                  :       libav*
+                                             ========                                                                                  :       ======
+                                                                                                                                       :
+                                                                                                                                       :
+                                                                                                       --------------------------------:---> AVStream...
+                                                                    InputStream input_streams[]      /                                 :
+                                                                                                    /                                  :
+                    InputFile input_files[]                         +==========================+   /   ^                               :
+                                                          ------> 0 |      : st ---:-----------:--/    :                               :
+                 ^  +------+-----------+-----+          /           +--------------------------+       :                               :
+                 :  |      :ist_index--:-----:---------/          1 |      : st    :           |       :                               :
+                 :  +------+-----------+-----+                      +==========================+       :                               :
+ nb_input_files  :  |      :ist_index--:-----:------------------> 2 |      : st    :           |       :                               :
+                 :  +------+-----------+-----+                      +--------------------------+       :  nb_input_streams             :
+                 :  |      :ist_index  :     |                    3 |            ...           |       :                               :
+                 v  +------+-----------+-----+                      +--------------------------+       :                               :
+                                                              --> 4 |                          |       :                               :
+                                                             |      +--------------------------+       :                               :
+                                                             |    5 |                          |       :                               :
+                                                             |      +==========================+       v                               :
+                                                             |                                                                         :
+                                                             |                                                                         :
+                                                             |                                                                         :
+                                                             |                                                                         :
+                                                              ---------                                --------------------------------:---> AVStream...
+                                                                        \                            /                                 :
+                                                                    OutputStream output_streams[]   /                                  :
+                                                                          \                        /                                   :
+                                                                    +======\======================/======+      ^                      :
+                                                          ------> 0 |   : source_index  : st-:---        |      :                      :
+                    OutputFile output_files[]           /           +------------------------------------+      :                      :
+                                                       /          1 |   :               :    :           |      :                      :
+                 ^  +------+------------+-----+       /             +------------------------------------+      :                      :
+                 :  |      : ost_index -:-----:------/            2 |   :               :    :           |      :                      :
+ nb_output_files :  +------+------------+-----+                     +====================================+      :                      :
+                 :  |      : ost_index -:-----|-----------------> 3 |   :               :    :           |      :                      :
+                 :  +------+------------+-----+                     +------------------------------------+      : nb_output_streams    :
+                 :  |      :            :     |                   4 |                                    |      :                      :
+                 :  +------+------------+-----+                     +------------------------------------+      :                      :
+                 :  |      :            :     |                   5 |                                    |      :                      :
+                 v  +------+------------+-----+                     +------------------------------------+      :                      :
+                                                                  6 |                                    |      :                      :
+                                                                    +------------------------------------+      :                      :
+                                                                  7 |                                    |      :                      :
+                                                                    +====================================+      v                      :
+                                                                                                                                       :