From c70a211997bcb3c582f25e9648a09995484dd63d Mon Sep 17 00:00:00 2001
From: Fabrice Bellard <fabrice@bellard.org>
Date: Tue, 19 Nov 2002 19:47:50 +0000
Subject: ffserver documentation update

Originally committed as revision 1234 to svn://svn.ffmpeg.org/ffmpeg/trunk
---
 doc/HOWTO-STREAM      | 161 --------------------------
 doc/Makefile          |   2 +-
 doc/ffserver-doc.html | 306 ++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/ffserver-doc.texi | 181 +++++++++++++++++++++++++++++
 doc/ffserver.txt      |  79 -------------
 5 files changed, 488 insertions(+), 241 deletions(-)
 delete mode 100644 doc/HOWTO-STREAM
 create mode 100644 doc/ffserver-doc.html
 create mode 100644 doc/ffserver-doc.texi
 delete mode 100644 doc/ffserver.txt

diff --git a/doc/HOWTO-STREAM b/doc/HOWTO-STREAM
deleted file mode 100644
index d260a046b0..0000000000
--- a/doc/HOWTO-STREAM
+++ /dev/null
@@ -1,161 +0,0 @@
-The FFserver streaming HOWTO
-----------------------------
-
-Philip Gladstone <philip-ffserver@gladstonefamily.net>
-Last updated: July 26, 2002
-
-0. What is this HOWTO about?
-
-This covers only the streaming aspects of ffserver / ffmpeg. All questions about
-parameters for ffmpeg, codec questions, etc. are not covered here.
-
-You should also read the ffserver.txt file in this directory. It contains
-roughly the same information.
-
-1. What can this do?
-
-When properly configured and running, you can capture video and audio in real
-time from a suitable capture card, and stream it out over the Internet to
-either Windows Media Player or RealAudio player (with some restrictions).
-
-It can also stream from files, though that is currently broken. Very often, a
-web server can be used to serve up the files just as well.
-
-2. What do I need?
-
-I use Linux on a 900MHz Duron with a cheapo Bt848 based TV capture card. I'm
-using stock linux 2.4.17 with the stock drivers. [Actually that isn't true,
-I needed some special drivers from my motherboard based sound card.]
-
-I understand that FreeBSD systems work just fine as well.
-
-3. How do I make it work?
-
-First, build the kit. It *really* helps to have installed LAME first. Then when
-you run the ffserver ./configure, make sure that you have the --enable-mp3lame
-flag turned on.
-
-LAME is important as it allows streaming of audio to Windows Media Player. Don't
-ask why the other audio types do not work.
-
-As a simple test, just run the following two command lines:
-
-./ffserver -f doc/ffserver.conf &
-./ffmpeg http://localhost:8090/feed1.ffm
-
-At this point you should be able to go to your windows machine and fire up
-Windows Media Player (WMP). Go to Open URL and enter 
-
-    http://<linuxbox>:8090/test.asf
-
-You should see (after a short delay) video and hear audio. 
-
-WARNING: trying to stream test1.mpg doesn't work with WMP as it tries to
-transfer the entire file before starting to play.
-
-4. What happens next?
-
-You should edit the ffserver.conf file to suit your needs (in terms of 
-frame rates etc). Then install ffserver and ffmpeg, write a script to start
-them up, and off you go.
-
-5. Troubleshooting
-
-* I don't hear any audio, but video is fine
-
-Maybe you didn't install LAME, or get your ./configure statement right. Check
-the ffmpeg output to see if a line referring to mp3 is present. If not, then
-your configuration was incorrect. If it is, then maybe your wiring is not
-setup correctly. Maybe the sound card is not getting data from the right 
-input source. Maybe you have a really awful audio interface (like I do)
-that only captures in stereo and also requires that one channel be flipped. 
-If you are one of these people, then export 'AUDIO_FLIP_LEFT=1' before 
-starting ffmpeg.
-
-* The audio and video loose sync after a while.
-
-Yes, they do.
-
-* After a long while, the video update rate goes way down in WMP.
-
-Yes, it does. Who knows why?
-
-* WMP 6.4 behaves differently to WMP 7.
-
-Yes, it does. Any thoughts on this would be gratefully received. These
-differences extend to embedding WMP into a web page. [There are two
-different object ids that you can use, one of them -- the old one -- cannot
-play very well, and the new one works well (both on the same system). However, 
-I suspect that the new one is not available unless you have installed WMP 7].
-
-6. What else can it do?
-
-There seems to be a bunch of code that allows you to replay previous
-video. I've never tried it, so it probably doesn't work properly. YMMV.
-In fact, in order to get some level of stability, ffserver now deletes
-all the previously sent video whenever it restarts.
-
-You can fiddle with many of the codec choices and encoding parameters, and
-there are a bunch more parameters that you cannot control. Post a message
-to the mailing list if there are some 'must have' parameters. Look in the
-ffserver.conf for a list of the currently available controls.
-
-It will automatically generate the .ASX or .RAM files that are often used
-in browsers. These files are actually redirections to the underlying .ASF
-or .RM file. The reason for this is that the browser often fetches the
-entire file before starting up the external viewer. The redirection files
-are very small and can be transferred quickly. [The stream itself is
-often 'infinite' and thus the browser tries to download it and never 
-finishes.]
-
-7. Tips
-
-* When you connect to a live stream, most players (WMP, RA etc) want to
-buffer a certain number of seconds of material so that they can display the
-signal continuously. However, ffserver (by default) starts sending data
-in real time. This means that there is a pause of a few seconds while the
-buffering is being done by the player. The good news is that this can be
-cured by adding a '?buffer=5' to the end of the URL. This says that the
-stream should start 5 seconds in the past -- and so the first 5 seconds 
-of the stream is sent as fast as the network will allow. It will then
-slow down to real time. This noticeably improves the startup experience.
-
-You can also add a 'Preroll 15' statement into the ffserver.conf that will
-add the 15 second prebuffering on all requests that do not otherwise
-specify a time. In addition, ffserver will skip frames until a key_frame
-is found. This further reduces the startup delay by not transferring data
-that will be discarded.
-
-* You may want to adjust the MaxBandwidth in the ffserver.conf to limit
-the amount of bandwidth consumed by live streams.
-
-8. Why does the ?buffer / Preroll stop working after a time?
-
-It turns out that (on my machine at least) the number of frames successfully
-grabbed is marginally less than the number that ought to be grabbed. This
-means that the timestamp in the encoded data stream gets behind real time.
-This means that if you say 'preroll 10', then when the stream gets 10
-or more seconds behind, there is no preroll left.
-
-Fixing this requires a require in the internals in how timestampts are 
-handled.
-
-9. Does the ?date= stuff work.
-
-Yes (subject to the caution above). Also note that whenever you start
-ffserver, it deletes the ffm file, thus wiping out what you had recorded
-before. This behaviour is a temporary fix to various crashes. The aim is
-to fix it so that the old data is saved if possible.
-
-The format of the ?date=xxxxxx is fairly flexible. You should use one
-of the following formats (the 'T' is literal):
-
-* YYYY-MM-DDTHH:MM:SS     (localtime)
-* YYYY-MM-DDTHH:MM:SSZ    (UTC)
-
-You can omit the YYYY-MM-DD, and then it refers to the current day. However 
-note that ?date=16:00:00  refers to 4PM on the current day -- this may be
-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:   http://localhost:8080/test.asf?date=2002-07-26T23:05:00
diff --git a/doc/Makefile b/doc/Makefile
index d951c33e13..dd5bca1f1d 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,4 +1,4 @@
-all: ffmpeg-doc.html faq.html
+all: ffmpeg-doc.html faq.html ffserver-doc.html
 
 %.html: %.texi
 	texi2html -monolithic -number $<
diff --git a/doc/ffserver-doc.html b/doc/ffserver-doc.html
new file mode 100644
index 0000000000..8e5c9f7d95
--- /dev/null
+++ b/doc/ffserver-doc.html
@@ -0,0 +1,306 @@
+<HTML>
+<HEAD>
+<!-- Created by texi2html 1.56k from ffserver-doc.texi on 19 November 2002 -->
+
+<TITLE>FFserver Documentation</TITLE>
+</HEAD>
+<BODY>
+<H1>FFserver Documentation</H1>
+<P>
+<P><HR><P>
+<H1>Table of Contents</H1>
+<UL>
+<LI><A NAME="TOC1" HREF="ffserver-doc.html#SEC1">1. Introduction</A>
+<LI><A NAME="TOC2" HREF="ffserver-doc.html#SEC2">2. QuickStart</A>
+<UL>
+<LI><A NAME="TOC3" HREF="ffserver-doc.html#SEC3">2.1 What can this do?</A>
+<LI><A NAME="TOC4" HREF="ffserver-doc.html#SEC4">2.2 What do I need?</A>
+<LI><A NAME="TOC5" HREF="ffserver-doc.html#SEC5">2.3 How do I make it work?</A>
+<LI><A NAME="TOC6" HREF="ffserver-doc.html#SEC6">2.4 What happens next?</A>
+<LI><A NAME="TOC7" HREF="ffserver-doc.html#SEC7">2.5 Troubleshooting</A>
+<UL>
+<LI><A NAME="TOC8" HREF="ffserver-doc.html#SEC8">2.5.1 I don't hear any audio, but video is fine</A>
+<LI><A NAME="TOC9" HREF="ffserver-doc.html#SEC9">2.5.2 The audio and video loose sync after a while.</A>
+<LI><A NAME="TOC10" HREF="ffserver-doc.html#SEC10">2.5.3 After a long while, the video update rate goes way down in WMP.</A>
+<LI><A NAME="TOC11" HREF="ffserver-doc.html#SEC11">2.5.4 WMP 6.4 behaves differently to WMP 7.</A>
+</UL>
+<LI><A NAME="TOC12" HREF="ffserver-doc.html#SEC12">2.6 What else can it do?</A>
+<LI><A NAME="TOC13" HREF="ffserver-doc.html#SEC13">2.7 Tips</A>
+<LI><A NAME="TOC14" HREF="ffserver-doc.html#SEC14">2.8 Why does the ?buffer / Preroll stop working after a time?</A>
+<LI><A NAME="TOC15" HREF="ffserver-doc.html#SEC15">2.9 Does the <CODE>?date=</CODE> stuff work.</A>
+</UL>
+</UL>
+<P><HR><P>
+
+<P>
+FFserver Documentation
+
+
+
+
+<H1><A NAME="SEC1" HREF="ffserver-doc.html#TOC1">1. Introduction</A></H1>
+
+<P>
+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
+specify a big enough feed storage in ffserver.conf).
+
+
+<P>
+This documentation covers only the streaming aspects of ffserver /
+ffmpeg. All questions about parameters for ffmpeg, codec questions,
+etc. are not covered here. Read <TT>`ffmpeg-doc.[texi|html]'</TT> for more
+information.
+
+
+
+
+<H1><A NAME="SEC2" HREF="ffserver-doc.html#TOC2">2. QuickStart</A></H1>
+
+<P>
+[Contributed by Philip Gladstone, philip-ffserver at gladstonefamily dot net]
+
+
+
+
+<H2><A NAME="SEC3" HREF="ffserver-doc.html#TOC3">2.1 What can this do?</A></H2>
+
+<P>
+When properly configured and running, you can capture video and audio in real
+time from a suitable capture card, and stream it out over the Internet to
+either Windows Media Player or RealAudio player (with some restrictions).
+
+
+<P>
+It can also stream from files, though that is currently broken. Very often, a
+web server can be used to serve up the files just as well.
+
+
+
+
+<H2><A NAME="SEC4" HREF="ffserver-doc.html#TOC4">2.2 What do I need?</A></H2>
+
+<P>
+I use Linux on a 900MHz Duron with a cheapo Bt848 based TV capture card. I'm
+using stock linux 2.4.17 with the stock drivers. [Actually that isn't true,
+I needed some special drivers from my motherboard based sound card.]
+
+
+<P>
+I understand that FreeBSD systems work just fine as well.
+
+
+
+
+<H2><A NAME="SEC5" HREF="ffserver-doc.html#TOC5">2.3 How do I make it work?</A></H2>
+
+<P>
+First, build the kit. It *really* helps to have installed LAME first. Then when
+you run the ffserver ./configure, make sure that you have the --enable-mp3lame
+flag turned on.
+
+
+<P>
+LAME is important as it allows streaming of audio to Windows Media Player. Don't
+ask why the other audio types do not work.
+
+
+<P>
+As a simple test, just run the following two command lines:
+
+
+
+<PRE>
+./ffserver -f doc/ffserver.conf &#38;
+./ffmpeg http://localhost:8090/feed1.ffm
+</PRE>
+
+<P>
+At this point you should be able to go to your windows machine and fire up
+Windows Media Player (WMP). Go to Open URL and enter 
+
+
+
+<PRE>
+    http://&#60;linuxbox&#62;:8090/test.asf
+</PRE>
+
+<P>
+You should see (after a short delay) video and hear audio. 
+
+
+<P>
+WARNING: trying to stream test1.mpg doesn't work with WMP as it tries to
+transfer the entire file before starting to play.
+
+
+
+
+<H2><A NAME="SEC6" HREF="ffserver-doc.html#TOC6">2.4 What happens next?</A></H2>
+
+<P>
+You should edit the ffserver.conf file to suit your needs (in terms of 
+frame rates etc). Then install ffserver and ffmpeg, write a script to start
+them up, and off you go.
+
+
+
+
+<H2><A NAME="SEC7" HREF="ffserver-doc.html#TOC7">2.5 Troubleshooting</A></H2>
+
+
+
+<H3><A NAME="SEC8" HREF="ffserver-doc.html#TOC8">2.5.1 I don't hear any audio, but video is fine</A></H3>
+
+<P>
+Maybe you didn't install LAME, or get your ./configure statement right. Check
+the ffmpeg output to see if a line referring to mp3 is present. If not, then
+your configuration was incorrect. If it is, then maybe your wiring is not
+setup correctly. Maybe the sound card is not getting data from the right 
+input source. Maybe you have a really awful audio interface (like I do)
+that only captures in stereo and also requires that one channel be flipped. 
+If you are one of these people, then export 'AUDIO_FLIP_LEFT=1' before 
+starting ffmpeg.
+
+
+
+
+<H3><A NAME="SEC9" HREF="ffserver-doc.html#TOC9">2.5.2 The audio and video loose sync after a while.</A></H3>
+
+<P>
+Yes, they do.
+
+
+
+
+<H3><A NAME="SEC10" HREF="ffserver-doc.html#TOC10">2.5.3 After a long while, the video update rate goes way down in WMP.</A></H3>
+
+<P>
+Yes, it does. Who knows why?
+
+
+
+
+<H3><A NAME="SEC11" HREF="ffserver-doc.html#TOC11">2.5.4 WMP 6.4 behaves differently to WMP 7.</A></H3>
+
+<P>
+Yes, it does. Any thoughts on this would be gratefully received. These
+differences extend to embedding WMP into a web page. [There are two
+different object ids that you can use, one of them -- the old one -- cannot
+play very well, and the new one works well (both on the same system). However, 
+I suspect that the new one is not available unless you have installed WMP 7].
+
+
+
+
+<H2><A NAME="SEC12" HREF="ffserver-doc.html#TOC12">2.6 What else can it do?</A></H2>
+
+<P>
+There seems to be a bunch of code that allows you to replay previous
+video. I've never tried it, so it probably doesn't work properly. YMMV.
+In fact, in order to get some level of stability, ffserver now deletes
+all the previously sent video whenever it restarts.
+
+
+<P>
+You can fiddle with many of the codec choices and encoding parameters, and
+there are a bunch more parameters that you cannot control. Post a message
+to the mailing list if there are some 'must have' parameters. Look in the
+ffserver.conf for a list of the currently available controls.
+
+
+<P>
+It will automatically generate the .ASX or .RAM files that are often used
+in browsers. These files are actually redirections to the underlying .ASF
+or .RM file. The reason for this is that the browser often fetches the
+entire file before starting up the external viewer. The redirection files
+are very small and can be transferred quickly. [The stream itself is
+often 'infinite' and thus the browser tries to download it and never 
+finishes.]
+
+
+
+
+<H2><A NAME="SEC13" HREF="ffserver-doc.html#TOC13">2.7 Tips</A></H2>
+
+<P>
+* When you connect to a live stream, most players (WMP, RA etc) want to
+buffer a certain number of seconds of material so that they can display the
+signal continuously. However, ffserver (by default) starts sending data
+in real time. This means that there is a pause of a few seconds while the
+buffering is being done by the player. The good news is that this can be
+cured by adding a '?buffer=5' to the end of the URL. This says that the
+stream should start 5 seconds in the past -- and so the first 5 seconds 
+of the stream is sent as fast as the network will allow. It will then
+slow down to real time. This noticeably improves the startup experience.
+
+
+<P>
+You can also add a 'Preroll 15' statement into the ffserver.conf that will
+add the 15 second prebuffering on all requests that do not otherwise
+specify a time. In addition, ffserver will skip frames until a key_frame
+is found. This further reduces the startup delay by not transferring data
+that will be discarded.
+
+
+<P>
+* You may want to adjust the MaxBandwidth in the ffserver.conf to limit
+the amount of bandwidth consumed by live streams.
+
+
+
+
+<H2><A NAME="SEC14" HREF="ffserver-doc.html#TOC14">2.8 Why does the ?buffer / Preroll stop working after a time?</A></H2>
+
+<P>
+It turns out that (on my machine at least) the number of frames successfully
+grabbed is marginally less than the number that ought to be grabbed. This
+means that the timestamp in the encoded data stream gets behind real time.
+This means that if you say 'preroll 10', then when the stream gets 10
+or more seconds behind, there is no preroll left.
+
+
+<P>
+Fixing this requires a require in the internals in how timestampts are 
+handled.
+
+
+
+
+<H2><A NAME="SEC15" HREF="ffserver-doc.html#TOC15">2.9 Does the <CODE>?date=</CODE> stuff work.</A></H2>
+
+<P>
+Yes (subject to the caution above). Also note that whenever you start
+ffserver, it deletes the ffm file, thus wiping out what you had recorded
+before. This behaviour is a temporary fix to various crashes. The aim is
+to fix it so that the old data is saved if possible.
+
+
+<P>
+The format of the <CODE>?date=xxxxxx</CODE> is fairly flexible. You should use one
+of the following formats (the 'T' is literal):
+
+
+
+<PRE>
+* YYYY-MM-DDTHH:MM:SS     (localtime)
+* YYYY-MM-DDTHH:MM:SSZ    (UTC)
+</PRE>
+
+<P>
+You can omit the YYYY-MM-DD, and then it refers to the current day. However 
+note that <SAMP>`?date=16:00:00'</SAMP>  refers to 4PM on the current day -- this may be
+in the future and so unlikely to useful.
+
+
+<P>
+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'</SAMP>.
+
+
+<P><HR><P>
+This document was generated on 19 November 2002 using
+<A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>&nbsp;1.56k.
+</BODY>
+</HTML>
diff --git a/doc/ffserver-doc.texi b/doc/ffserver-doc.texi
new file mode 100644
index 0000000000..051038ed87
--- /dev/null
+++ b/doc/ffserver-doc.texi
@@ -0,0 +1,181 @@
+\input texinfo @c -*- texinfo -*-
+
+@settitle FFserver Documentation
+@titlepage
+@sp 7
+@center @titlefont{FFserver Documentation}
+@sp 3
+@end titlepage
+
+
+@chapter Introduction
+
+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
+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
+information.
+
+@chapter QuickStart
+
+[Contributed by Philip Gladstone, philip-ffserver at gladstonefamily dot net]
+
+@section What can this do?
+
+When properly configured and running, you can capture video and audio in real
+time from a suitable capture card, and stream it out over the Internet to
+either Windows Media Player or RealAudio player (with some restrictions).
+
+It can also stream from files, though that is currently broken. Very often, a
+web server can be used to serve up the files just as well.
+
+@section What do I need?
+
+I use Linux on a 900MHz Duron with a cheapo Bt848 based TV capture card. I'm
+using stock linux 2.4.17 with the stock drivers. [Actually that isn't true,
+I needed some special drivers from my motherboard based sound card.]
+
+I understand that FreeBSD systems work just fine as well.
+
+@section How do I make it work?
+
+First, build the kit. It *really* helps to have installed LAME first. Then when
+you run the ffserver ./configure, make sure that you have the --enable-mp3lame
+flag turned on.
+
+LAME is important as it allows streaming of audio to Windows Media Player. Don't
+ask why the other audio types do not work.
+
+As a simple test, just run the following two command lines:
+
+@example
+./ffserver -f doc/ffserver.conf &
+./ffmpeg http://localhost:8090/feed1.ffm
+@end example
+
+At this point you should be able to go to your windows machine and fire up
+Windows Media Player (WMP). Go to Open URL and enter 
+
+@example
+    http://<linuxbox>:8090/test.asf
+@end example
+
+You should see (after a short delay) video and hear audio. 
+
+WARNING: trying to stream test1.mpg doesn't work with WMP as it tries to
+transfer the entire file before starting to play.
+
+@section What happens next?
+
+You should edit the ffserver.conf file to suit your needs (in terms of 
+frame rates etc). Then install ffserver and ffmpeg, write a script to start
+them up, and off you go.
+
+@section Troubleshooting
+
+@subsection I don't hear any audio, but video is fine
+
+Maybe you didn't install LAME, or get your ./configure statement right. Check
+the ffmpeg output to see if a line referring to mp3 is present. If not, then
+your configuration was incorrect. If it is, then maybe your wiring is not
+setup correctly. Maybe the sound card is not getting data from the right 
+input source. Maybe you have a really awful audio interface (like I do)
+that only captures in stereo and also requires that one channel be flipped. 
+If you are one of these people, then export 'AUDIO_FLIP_LEFT=1' before 
+starting ffmpeg.
+
+@subsection The audio and video loose sync after a while.
+
+Yes, they do.
+
+@subsection After a long while, the video update rate goes way down in WMP.
+
+Yes, it does. Who knows why?
+
+@subsection WMP 6.4 behaves differently to WMP 7.
+
+Yes, it does. Any thoughts on this would be gratefully received. These
+differences extend to embedding WMP into a web page. [There are two
+different object ids that you can use, one of them -- the old one -- cannot
+play very well, and the new one works well (both on the same system). However, 
+I suspect that the new one is not available unless you have installed WMP 7].
+
+@section What else can it do?
+
+There seems to be a bunch of code that allows you to replay previous
+video. I've never tried it, so it probably doesn't work properly. YMMV.
+In fact, in order to get some level of stability, ffserver now deletes
+all the previously sent video whenever it restarts.
+
+You can fiddle with many of the codec choices and encoding parameters, and
+there are a bunch more parameters that you cannot control. Post a message
+to the mailing list if there are some 'must have' parameters. Look in the
+ffserver.conf for a list of the currently available controls.
+
+It will automatically generate the .ASX or .RAM files that are often used
+in browsers. These files are actually redirections to the underlying .ASF
+or .RM file. The reason for this is that the browser often fetches the
+entire file before starting up the external viewer. The redirection files
+are very small and can be transferred quickly. [The stream itself is
+often 'infinite' and thus the browser tries to download it and never 
+finishes.]
+
+@section Tips
+
+* When you connect to a live stream, most players (WMP, RA etc) want to
+buffer a certain number of seconds of material so that they can display the
+signal continuously. However, ffserver (by default) starts sending data
+in real time. This means that there is a pause of a few seconds while the
+buffering is being done by the player. The good news is that this can be
+cured by adding a '?buffer=5' to the end of the URL. This says that the
+stream should start 5 seconds in the past -- and so the first 5 seconds 
+of the stream is sent as fast as the network will allow. It will then
+slow down to real time. This noticeably improves the startup experience.
+
+You can also add a 'Preroll 15' statement into the ffserver.conf that will
+add the 15 second prebuffering on all requests that do not otherwise
+specify a time. In addition, ffserver will skip frames until a key_frame
+is found. This further reduces the startup delay by not transferring data
+that will be discarded.
+
+* You may want to adjust the MaxBandwidth in the ffserver.conf to limit
+the amount of bandwidth consumed by live streams.
+
+@section Why does the ?buffer / Preroll stop working after a time?
+
+It turns out that (on my machine at least) the number of frames successfully
+grabbed is marginally less than the number that ought to be grabbed. This
+means that the timestamp in the encoded data stream gets behind real time.
+This means that if you say 'preroll 10', then when the stream gets 10
+or more seconds behind, there is no preroll left.
+
+Fixing this requires a require in the internals in how timestampts are 
+handled.
+
+@section Does the @code{?date=} stuff work.
+
+Yes (subject to the caution above). Also note that whenever you start
+ffserver, it deletes the ffm file, thus wiping out what you had recorded
+before. This behaviour is a temporary fix to various crashes. The aim is
+to fix it so that the old data is saved if possible.
+
+The format of the @code{?date=xxxxxx} is fairly flexible. You should use one
+of the following formats (the 'T' is literal):
+
+@example
+* YYYY-MM-DDTHH:MM:SS     (localtime)
+* YYYY-MM-DDTHH:MM:SSZ    (UTC)
+@end example
+
+You can omit the YYYY-MM-DD, and then it refers to the current day. However 
+note that @samp{?date=16:00:00}  refers to 4PM on the current day -- this may be
+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}.
+
+@bye
diff --git a/doc/ffserver.txt b/doc/ffserver.txt
deleted file mode 100644
index 6b1228870c..0000000000
--- a/doc/ffserver.txt
+++ /dev/null
@@ -1,79 +0,0 @@
-*************** FFserver live broadcast server *****************
-
-0) Introduction
-
-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 specify a big enough feed storage in ffserver.conf).
-
-1) Quick help
-
-- First you must ensure that your grab system is OK. Verify with
-  'xawtv' that your TV card is tuned on a correct video source.
-
-- Try with ffmpeg that you can record correctly. For example:
-
-  ffmpeg /tmp/a.mpg
-
-will record a ten seconds mpeg file from your TV card and audio
-card. Use for example the mpegtv player or MPlayer to view the created
-MPEG file.
-
-- Launch ffserver on your PC with the sample config file:
-
-  ffserver -f doc/ffserver.conf
-
-- Verify with your browser that ffserver is working correctly. For
-  that purpose, explore: http://localhost:8090/stat.html .
-
-- Now launch ffmpeg to do real time encoding :
-
-  ffmpeg http://localhost:8090/feed1.ffm
-
-- Then, use your favorite players to see each generated stream:
-
-  mtvp http://localhost:8090/test1.mpg
-
-  mpg123 http://localhost:8090/test.mp2
-
-  netscape http://localhost:8090/test.swf
-
-  realplayer http://localhost:8090/test.rm
-
-  etc...
-
-  Note that ffserver generates multiple streams in multiple formats AT
-  THE SAME TIME. It should be able to handle hundreds of users at the
-  same time if you internet connection is fast enough.
-
-- Now you can configure ffserver for your real needs. Edit the
-  ffserver.conf file to use only the formats you want. Read the ffmpeg
-  documentation (ffmpeg.txt) to learn more about the codec and format
-  stuff.
-
-- Report any bug you find (and the fix if you have it!).
-
-2) URL Format
-
-  ffserver supports that you seek in some formats. The syntax is to
-  add a '?' option to the URL. Only the 'date' option is supported. 
-
-  The date format is [YYYY-MM-DDT][[HH:]MM:]SS[.m...] (clost to ISO
-  date format). For live streams, the date is absolute and give in
-  GMT. If the day is not specified, the current day is used.
-
-  example: 
-
-     mpg123 http://localhost:8090/test.mp2?date=10:00
-
-  play the stream starting at 10:00 AM GMT today.
-
-     mpg123 http://localhost:8090/test.mp2?date=2001-06-23T23:00
-
-  is also a valid date.
-
-  For file streams, the date is relative to the start of the file. No
-  day can be specified.
-
-
-- 
cgit v1.2.3