Commit e99c4e10 authored by Fabrice Bellard's avatar Fabrice Bellard
Browse files

added ffplay documentation - added automatic man page generation for ffmpeg, ffserver and ffplay

Originally committed as revision 2136 to svn://svn.ffmpeg.org/ffmpeg/trunk
parent d6eb3c50
all: ffmpeg-doc.html faq.html ffserver-doc.html hooks.html
all: ffmpeg-doc.html faq.html ffserver-doc.html ffplay-doc.html hooks.html \
ffmpeg.1 ffserver.1 ffplay.1
%.html: %.texi Makefile
texi2html -monolithic -number $<
%.pod: %-doc.texi
./texi2pod.pl $< $@
%.1: %.pod
pod2man --section=1 --center=" " --release=" " $< > $@
clean:
rm -f *.html
rm -f *.html *.pod *.1
......@@ -22,19 +22,21 @@ video on the fly with a high quality polyphase filter.
@chapter Quick Start
@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 use a video4linux compatible video source and any Open Sound
System audio source:
@example
ffmpeg /tmp/out.mpg
ffmpeg /tmp/out.mpg
@end example
Note that you must activate the right video source and channel before
launching ffmpeg. You can use any TV viewer such as xawtv
(@url{http://bytesex.org/xawtv/}) by Gerd Knorr which I find very
good. You must also set correctly the audio recording levels with a
standard mixer.
Note that you must activate the right video source and channel before
launching ffmpeg. You can use any TV viewer such as xawtv
(@url{http://bytesex.org/xawtv/}) by Gerd Knorr which I find very
good. You must also set correctly the audio recording levels with a
standard mixer.
@section Video and Audio file format conversion
......@@ -45,109 +47,115 @@ Examples:
* You can input from YUV files:
@example
ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
@end example
It will use the files:
It will use the files:
@example
/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
@end example
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.
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 @option{-s} option
if ffmpeg cannot guess it.
* You can input from a RAW YUV420P file:
@example
ffmpeg -i /tmp/test.yuv /tmp/out.avi
ffmpeg -i /tmp/test.yuv /tmp/out.avi
@end example
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.
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:
@example
ffmpeg -i mydivx.avi -o hugefile.yuv
ffmpeg -i mydivx.avi -o hugefile.yuv
@end example
* You can set several input files and output files:
@example
ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
@end example
Convert the audio file a.wav and the raw yuv video file a.yuv
to mpeg file 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 conversions at the same time:
@example
ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
@end example
Convert the sample rate of a.wav to 22050 Hz and encode it to MPEG audio.
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:
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 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
@end example
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.
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
@example
ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800 -g 300 -bf 2 -acodec mp3 -ab 128 snatch.avi
ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800 -g 300 -bf 2 -acodec mp3 -ab 128 snatch.avi
@end example
This is a typical 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 @code{--enable-mp3lame} when
configuring. The mapping is particularly useful for DVD transcoding
to get the desired audio language.
This is a typical 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 @code{--enable-mp3lame} when
configuring. The mapping is particularly useful for DVD transcoding
to get the desired audio language.
NOTE: to see the supported input formats, use @code{ffmpeg -formats}.
NOTE: to see the supported input formats, use @code{ffmpeg -formats}.
@c man end
@chapter Invocation
@section Syntax
The generic syntax is:
The generic syntax is:
@example
ffmpeg [[options][-i input_file]]... {[options] output_file}...
@c man begin SYNOPSIS
ffmpeg [[options][@option{-i} @var{input_file}]]... @{[options] @var{output_file}@}...
@c man end
@end example
If no input file is given, audio/video grabbing is done.
@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. 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.
As a general rule, options are applied to the next specified
file. For example, if you give the @option{-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 for the outputs as the one
specified for the inputs.
By default, ffmpeg tries to convert as losslessly as possible: it
uses the same audio and video parameter for the outputs as the one
specified for the inputs.
@c man end
@c man begin OPTIONS
@section Main options
@table @samp
@table @option
@item -L
show license
@item -h
show help
@item -formats
show help
@item -formats
show available formats, codecs, protocols, ...
@item -f fmt
force format
......@@ -173,13 +181,11 @@ set the copyright
@item -comment string
set the comment
@item -b bitrate
set video bitrate (in kbit/s)
@end table
@section Video Options
@table @samp
@table @option
@item -s size
set frame size [160x128]
@item -r fps
......@@ -203,7 +209,7 @@ select two pass log file name
@section Audio Options
@table @samp
@table @option
@item -ab bitrate
set audio bitrate (in kbit/s)
@item -ar freq
......@@ -218,7 +224,7 @@ set audio bitrate (in kbit/s)
@section Advanced options
@table @samp
@table @option
@item -map file:stream
set input stream mapping
@item -g gop_size
......@@ -264,6 +270,22 @@ calculate PSNR of compressed frames
@item -vstats
dump video coding statistics to file
@end table
@c man end
@ignore
@setfilename ffmpeg
@settitle FFmpeg video converter
@c man begin SEEALSO
ffserver(1), ffplay(1) and the html documentation of @file{ffmpeg}.
@c man end
@c man begin AUTHOR
Fabrice Bellard
@c man end
@end ignore
@section Protocols
......@@ -272,47 +294,47 @@ to the standard output.
ffmpeg handles also many protocols specified with the URL syntax.
Use 'ffmpeg -formats' to have a list of the supported protocols.
Use 'ffmpeg -formats' to have a list of the supported protocols.
The protocol @code{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 :-)
The protocol @code{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 :-)
@chapter Tips
@itemize
@item 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:
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:
@example
ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
ffmpeg -g 3 -r 3 -t 10 -b 50 -s qcif -f rv10 /tmp/b.rm
@end example
@item 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.
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.
@item 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
completely motion estimation (you have only I frames, which means it
is about as good as JPEG compression).
compression at the expense of the compression ratio. You can use
'-me zero' to speed up motion estimation, and '-intra' to disable
completely motion estimation (you have only I frames, which means it
is about as good as JPEG compression).
@item To have very low bitrates in audio, reduce the sampling frequency
(down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
(down to 22050 kHz for mpeg audio, 22050 or 11025 for ac3).
@item 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).
'-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
quality).
@item 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.
uses in the encoder the same quality factor than in the decoder. It
allows to be almost lossless in encoding.
@end itemize
......
\input texinfo @c -*- texinfo -*-
@settitle FFplay Documentation
@titlepage
@sp 7
@center @titlefont{FFplay Documentation}
@sp 3
@end titlepage
@chapter Introduction
@c man begin DESCRIPTION
FFplay is a very simple and portable media player using the FFmpeg
libraries and the SDL library. It is mostly used as a test bench for the
various APIs of FFmpeg.
@c man end
@chapter Invocation
@section Syntax
@example
@c man begin SYNOPSIS
ffplay [options] @file{input_file}
@c man end
@end example
@c man begin OPTIONS
@section Main options
@table @option
@item -h
show help
@item -x width
force displayed width
@item -y height
force displayed height
@item -an
disable audio
@item -vn
disable video
@item -nodisp
disable graphical display
@item -f fmt
force format
@end table
@section Advanced options
@table @option
@item -stats
show the stream duration, the codec parameters, the current position in
the stream, and the audio/video synchronisation drift.
@item -rtp_tcp
force RTP/TCP protocol usage instead of RTP/UDP. It is only meaningful
if you are doing stream with the RTSP protocol.
@item -sync type
set the master clock to audio (@code{type=audio}), video
(@code{type=video}) or external (@code{type=ext}). Default is audio. The
master clock is used to control audio-video synchronization. Most media
players use audio as master clock, but in some cases (streaming or high
quality broadcast) it is necessary to change that. This option is mainly
used for debugging purposes.
@end table
@section While playing
@table @key
@item q, ESC
quit
@item f
toggle full screen
@item p, SPC
pause
@item a
cycle audio channel
@item v
cycle video channel
@item w
show audio waves
@end table
@c man end
@ignore
@setfilename ffplay
@settitle FFplay media player
@c man begin SEEALSO
ffmpeg(1), ffserver(1) and the html documentation of @file{ffmpeg}.
@c man end
@c man begin AUTHOR
Fabrice Bellard
@c man end
@end ignore
@bye
......@@ -10,6 +10,7 @@
@chapter Introduction
@c man begin DESCRIPTION
FFserver is a streaming server for both audio and video. It supports
several live feeds, streaming from files and time shifting on live feeds
(you can seek to positions in the past on each live feed, provided you
......@@ -17,8 +18,9 @@ specify a big enough feed storage in ffserver.conf).
This documentation covers only the streaming aspects of ffserver /
ffmpeg. All questions about parameters for ffmpeg, codec questions,
etc. are not covered here. Read @file{ffmpeg-doc.[texi|html]} for more
etc. are not covered here. Read @file{ffmpeg-doc.html} for more
information.
@c man end
@chapter QuickStart
......@@ -182,4 +184,39 @@ in the future and so unlikely to useful.
You use this by adding the ?date= to the end of the URL for the stream.
For example: @samp{http://localhost:8080/test.asf?date=2002-07-26T23:05:00}.
@chapter Invocation
@section Syntax
@example
@c man begin SYNOPSIS
ffserver [options]
@c man end
@end example
@section Options
@c man begin OPTIONS
@table @option
@item -L
print the license
@item -h
print the help
@item -f configfile
use @file{configfile} instead of @file{/etc/ffserver.conf}
@end table
@c man end
@ignore
@setfilename ffsserver
@settitle FFserver video server
@c man begin SEEALSO
ffmpeg(1), ffplay(1) and the html documentation of @file{ffmpeg}.
@c man end
@c man begin AUTHOR
Fabrice Bellard
@c man end
@end ignore
@bye
#! /usr/bin/perl -w
# Copyright (C) 1999, 2000, 2001 Free Software Foundation, Inc.
# This file is part of GNU CC.
# GNU CC is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# GNU CC is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with GNU CC; see the file COPYING. If not, write to
# the Free Software Foundation, 59 Temple Place - Suite 330,
# Boston MA 02111-1307, USA.
# This does trivial (and I mean _trivial_) conversion of Texinfo
# markup to Perl POD format. It's intended to be used to extract
# something suitable for a manpage from a Texinfo document.
$output = 0;
$skipping = 0;
%sects = ();
$section = "";
@icstack = ();
@endwstack = ();
@skstack = ();
@instack = ();
$shift = "";
%defs = ();
$fnno = 1;
$inf = "";
$ibase = "";
while ($_ = shift) {
if (/^-D(.*)$/) {
if ($1 ne "") {
$flag = $1;
} else {
$flag = shift;
}
$value = "";
($flag, $value) = ($flag =~ /^([^=]+)(?:=(.+))?/);
die "no flag specified for -D\n"
unless $flag ne "";
die "flags may only contain letters, digits, hyphens, dashes and underscores\n"
unless $flag =~ /^[a-zA-Z0-9_-]+$/;
$defs{$flag} = $value;
} elsif (/^-/) {
usage();
} else {
$in = $_, next unless defined $in;
$out = $_, next unless defined $out;
usage();
}
}
if (defined $in) {
$inf = gensym();
open($inf, "<$in") or die "opening \"$in\": $!\n";
$ibase = $1 if $in =~ m|^(.+)/[^/]+$|;
} else {
$inf = \*STDIN;
}
if (defined $out) {
open(STDOUT, ">$out") or die "opening \"$out\": $!\n";
}
while(defined $inf) {
while(<$inf>) {
# Certain commands are discarded without further processing.
/^\@(?:
[a-z]+index # @*index: useful only in complete manual
|need # @need: useful only in printed manual
|(?:end\s+)?group # @group .. @end group: ditto
|page # @page: ditto
|node # @node: useful only in .info file
|(?:end\s+)?ifnottex # @ifnottex .. @end ifnottex: use contents
)\b/x and next;
chomp;
# Look for filename and title markers.
/^\@setfilename\s+([^.]+)/ and $fn = $1, next;
/^\@settitle\s+([^.]+)/ and $tl = postprocess($1), next;
# Identify a man title but keep only the one we are interested in.
/^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do {
if (exists $defs{$1}) {
$fn = $1;
$tl = postprocess($2);
}
next;
};
# Look for blocks surrounded by @c man begin SECTION ... @c man end.
# This really oughta be @ifman ... @end ifman and the like, but such
# would require rev'ing all other Texinfo translators.
/^\@c\s+man\s+begin\s+([A-Z]+)\s+([A-Za-z0-9-]+)/ and do {
$output = 1 if exists $defs{$2};
$sect = $1;
next;
};
/^\@c\s+man\s+begin\s+([A-Z]+)/ and $sect = $1, $output = 1, next;
/^\@c\s+man\s+end/ and do {
$sects{$sect} = "" unless exists $sects{$sect};
$sects{$sect} .= postprocess($section);
$section = "";
$output = 0;
next;
};
# handle variables
/^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do {
$defs{$1} = $2;
next;
};
/^\@clear\s+([a-zA-Z0-9_-]+)/ and do {
delete $defs{$1};
next;
};
next unless $output;
# Discard comments. (Can't do it above, because then we'd never see
# @c man lines.)
/^\@c\b/ and next;
# End-block handler goes up here because it needs to operate even
# if we are skipping.
/^\@end\s+([a-z]+)/ and do {
# Ignore @end foo, where foo is not an operation which may
# cause us to skip, if we are presently skipping.
my $ended = $1;
next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex)$/;
die "\@end $ended without \@$ended at line $.\n" unless defined $endw;
die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw;
$endw = pop @endwstack;
if ($ended =~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) {
$skipping = pop @skstack;
next;
} elsif ($ended =~ /^(?:example|smallexample|display)$/) {
$shift = "";
$_ = ""; # need a paragraph break
} elsif ($ended =~ /^(?:itemize|enumerate|[fv]?table)$/) {
$_ = "\n=back\n";
$ic = pop @icstack;
} else {
die "unknown command \@end $ended at line $.\n";